Nginx 工程实践 -- 15. proxy_pass 的 URI 规则与路径拼接
反向代理最容易出错的地方,往往不是"连不连得上",而是转发给上游的 URI 到底长什么样。同一句 proxy_pass,带不带末尾斜杠、带不带路径,结果完全不同;再叠加 rewrite ... break、内部重定向、变量化地址,路径会被多次改写。把规则记牢,能省掉大量"上游 404 但 Nginx 日志显示 200"的排查时间。
flowchart TD
A["客户端请求 /name/test"] --> B{"proxy_pass 写法"}
B -->|"不带 URI
proxy_pass http://up"| C["原样透传
上游收到 /name/test"]
B -->|"带 URI
proxy_pass http://up/remote/"| D["前缀替换
上游收到 /remote/test"]
B -->|"先 rewrite ... break"| E["改写 $uri
再按不带 URI 透传"]
E --> F["上游收到改写后的 URI"]
一、不带 URI:原样透传
1 | |
客户端请求 GET /name/test,上游收到的就是 /name/test。官方对"不带 URI"的定义是:请求 URI 以客户端发来的原始形式(或内部重定向后的完整规范化形式)传给服务器,location 前缀不会被去掉。
这是最容易踩的坑:本意是"把 /name/ 映射成上游的 /",结果上游拿到带 /name/ 前缀的路径。
二、带 URI:前缀被替换
1 | |
客户端请求 /name/test,上游收到 /remote/test。规则是:与 location 匹配的那部分 URI 被指令里写的 URI 替换。
要点:
- 指令里写
/remote/与写/remote,语义不同:前者替换前缀,后者也会替换,但拼接方式要注意末尾斜杠; - location 用正则时,带 URI 的
proxy_pass不能使用捕获变量(官方限制); - 替换发生在规范化后的 URI 上(
//、./、../已被 Nginx 归一化)。
三、用 rewrite … break 改写
当"替换前缀"的自动规则不够用(比如要把 /name/ 改成 /users/ 并调整结构),用 rewrite 配合 break:
1 | |
客户端 /name/test → $uri 被改写为 /users/test → proxy_pass 不带 URI,原样透传 → 上游收到 /users/test。
注意两点:
- 这里必须用
break,用last会触发"改写后重新匹配 location",可能再次进入本 location 造成循环; rewrite改的是$uri(解码、规范化的路径),不影响$args;查询参数仍会自动追加。
四、proxy_redirect:改写上游的跳转地址
上游返回 301/302 时,Location 头里常带上它自己的内网地址(如 http://127.0.0.1:8000/users/1),直接透传给客户端会跳到内网。proxy_redirect 负责改写这个头:
1 | |
default:把Location中的上游地址替换成当前 Nginx 的 host,是最常用值;- 可配置多条,按顺序匹配;
- 只影响响应头
Location和Refresh,不改写响应体里出现的 URL。
五、变量化 proxy_pass 的注意
proxy_pass 支持变量(如 proxy_pass http://$backend;),用于动态选址。但有几点不同:
- 含变量且未写 URI 时,请求 URI 按原始形式传递,行为与"不带 URI"一致;
- 含变量时通常需要
resolver指令(resolver 8.8.8.8;),因为此时 Nginx 不再在启动时解析域名,而是在运行时解析; - 变量化后
proxy_redirect default的替换行为可能不可用,需要显式配置。
1 | |
六、常见坑
| 坑 | 说明 |
|---|---|
proxy_pass http://up; 以为会去掉 /name/ | 不带 URI 就是原样透传,前缀保留 |
| 末尾斜杠写错 | /remote/ 与 /remote 的拼接结果不同,务必显式写全 |
| 正则 location + 带 URI 的 proxy_pass | 官方不支持在带 URI 的 proxy_pass 中使用捕获变量 |
用 last 而非 break 改 URI | 触发重新匹配 location,可能循环 |
| 上游跳转暴露内网地址 | 配 proxy_redirect default |
| 变量 proxy_pass 不配 resolver | 运行时无法解析域名,直接 502/500 |
| 期望改写响应体里的 URL | proxy_redirect 只改头,需 sub_filter(见第 22 篇) |
参考链接
- Nginx 官方文档:ngx_http_proxy_module(proxy_pass) —— 带/不带 URI 的替换规则、变量与 resolver;
- Nginx 官方文档:ngx_http_proxy_module(proxy_redirect) —— 改写 Location/Refresh;
- Nginx 官方文档:ngx_http_rewrite_module(rewrite) ——
break与last的差异; - Nginx 官方文档:ngx_http_core_module(location) —— 前缀与正则匹配规则。
小结
- 不带 URI:原样透传,location 前缀保留;带 URI:匹配前缀被替换;
- 需要灵活改写用
rewrite ... break,别用last; - 上游跳转地址用
proxy_redirect default兜底; - 变量化
proxy_pass必须配resolver,且proxy_redirect default可能失效。
系列导航
Nginx 工程实践 -- 15. proxy_pass 的 URI 规则与路径拼接
https://bubao.github.io/posts/f5a6b7c8.html
