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
2
3
location /name/ {
proxy_pass http://127.0.0.1:8000;
}

客户端请求 GET /name/test,上游收到的就是 /name/test。官方对"不带 URI"的定义是:请求 URI 以客户端发来的原始形式(或内部重定向后的完整规范化形式)传给服务器,location 前缀不会被去掉。

这是最容易踩的坑:本意是"把 /name/ 映射成上游的 /",结果上游拿到带 /name/ 前缀的路径。

二、带 URI:前缀被替换

1
2
3
location /name/ {
proxy_pass http://127.0.0.1:8000/remote/;
}

客户端请求 /name/test,上游收到 /remote/test。规则是:与 location 匹配的那部分 URI 被指令里写的 URI 替换。

要点:

  • 指令里写 /remote/ 与写 /remote,语义不同:前者替换前缀,后者也会替换,但拼接方式要注意末尾斜杠;
  • location 用正则时,带 URI 的 proxy_pass 不能使用捕获变量(官方限制);
  • 替换发生在规范化后的 URI 上(//、./、../ 已被 Nginx 归一化)。

三、用 rewrite … break 改写

当"替换前缀"的自动规则不够用(比如要把 /name/ 改成 /users/ 并调整结构),用 rewrite 配合 break:

1
2
3
4
location /name/ {
rewrite /name/(.*) /users/$1 break;
proxy_pass http://127.0.0.1:8000;
}

客户端 /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
2
3
4
5
6
7
8
location /name/ {
proxy_pass http://127.0.0.1:8000;
proxy_redirect default;
# 或显式指定
proxy_redirect http://127.0.0.1:8000/ /name/;
# 关掉
# proxy_redirect off;
}
  • 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
2
3
4
5
location / {
resolver 8.8.8.8;
set $backend "backend.example.com:8000";
proxy_pass http://$backend;
}

六、常见坑

坑说明
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
期望改写响应体里的 URLproxy_redirect 只改头,需 sub_filter(见第 22 篇)

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module(proxy_pass) —— 带/不带 URI 的替换规则、变量与 resolver;
  2. Nginx 官方文档:ngx_http_proxy_module(proxy_redirect) —— 改写 Location/Refresh;
  3. Nginx 官方文档:ngx_http_rewrite_module(rewrite) —— break 与 last 的差异;
  4. 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
作者
一念
发布于
2026年11月21日
许可协议