nginx反向代理中实现路径透明转换需用rewrite+proxy_pass组合：正则location捕获路径后rewrite重写为绝对路径并加break，proxy_pass后不带路径；非正则location中rewrite末尾必须用break防循环，且proxy_pass结尾不能加斜杠，否则rewrite失效；参数需显式保留，避免相对路径、last跳转、if中变量等常见陷阱。
要让 Nginx 在反向代理过程中“悄悄”改掉请求路径，既不暴露给客户端，又准确送达后端，关键不是靠 rewrite 单独跳转，而是用 rewrite + proxy_pass 的组合 + 正确 flag 和路径拼接逻辑。所谓“透明转换”，是指用户访问 /api/v2/users，后端实际收到的是 /v2/users 或 /users，地址栏不变、无重定向、参数完整保留。
正则 location 捕获路径段再重写
这是最可控的方式，适合版本号、模块名等可提取的动态结构：
- 用
location ~ ^/api/(?<version>v\d+)/(?<path>.*)$</path></version>匹配并命名捕获 -
rewrite ^/api/(?<version>v\d+)/(?<path>.*)$ /$version/$path break;</path></version>—— 注意以 / 开头，否则 proxy_pass 会当作相对路径拼接 -
proxy_pass http://backend;—— 后面不能带路径（如不能写http://backend/api），否则 rewrite 生效但被覆盖
前缀匹配 + rewrite break 剥离固定前缀
适用于统一入口（如所有 API 都走 /api/）需标准化后端路径的场景：
location /api/ {-
rewrite ^/api/(.*)$ /$1 break;—— 把 /api/users → /users -
proxy_pass http://backend;—— 不加斜杠，确保 rewrite 后的 URI 被完整使用 }
⚠️ 若写成 proxy_pass http://backend/;（结尾有斜杠），Nginx 会忽略 rewrite 结果，直接把原始路径裁剪后转发（即 /api/users → /users），看似一样，但 rewrite 实际未生效，后续扩展性差。
保留查询参数与原始上下文
rewrite 默认不自动带参数，必须显式处理：
- 用
$args或$is_args$args拼接：例如rewrite ^/old/(\d+)$ /new?id=$1?$args break; - 或更稳妥地用
$request_uri（含路径+参数）配合 proxy_set_header 透传：proxy_set_header X-Original-URI $request_uri; - 后端可通过该 header 还原原始请求，便于日志追踪或兼容旧逻辑
避免常见陷阱
这些细节出错会导致 404、双斜杠、循环或静默失败：
- rewrite 后的路径不以
/开头 → Nginx 当作相对路径，可能拼出http://backend/old//users - 在非正则 location（如
location /api/）里用last→ 重写后重新匹配 location，容易触发无限循环（尤其当有location /存在时） - 在 if 块中直接用
proxy_pass http://$var→ 变量无法在 proxy_pass 中解析，必须用map预定义合法 upstream 名称 - 没加
break→ rewrite 触发内部重定向，跳到 server 级别重新匹配，proxy_pass 被跳过
