Nginx利用proxy_pass配置路径重写与URL映射-Nginx-PHP中文网

Nginx中proxy_pass路径重写由location匹配方式与proxy_pass结尾斜杠共同决定：带/时剥离匹配前缀后拼接，不带/时直接替换路径，正则匹配需配合rewrite；常见场景包括去前缀、路径替换和正则重写。

nginx利用proxy_pass配置路径重写与url映射

用 proxy_pass 做路径重写和 URL 映射，关键在于理解 Nginx 如何处理 location 匹配后的 URI 传递逻辑——它不是简单“转发”，而是根据 location 和 proxy_pass 的结尾斜杠规则自动裁剪和拼接路径。

location 与 proxy_pass 斜杠决定路径是否被重写

Nginx 的路径重写行为由 location 的匹配方式和 proxy_pass 指令末尾是否有 / 共同决定：

当 location 使用精确匹配（= /api）或前缀匹配（/api），且 proxy_pass 以 / 结尾时，Nginx 会剥离 location 匹配前缀，再将剩余路径拼到 proxy_pass 后面
当 proxy_pass 不以 / 结尾（如 proxy_pass http://backend:8080/api），Nginx 会直接替换整个匹配路径为 proxy_pass 中指定的路径，不保留原始 URI 剩余部分
如果 location 是正则匹配（~ ^/api/v\d+），proxy_pass 后不能带路径，必须只写协议+主机（如 http://backend:8080），否则报错；此时需用 rewrite 配合 break 或 redirect 控制路径

常见映射场景与配置示例

以下是最常遇到的三种需求及对应写法：

① 把 /admin/ → 后端 / （去前缀）
适用于前端统一入口、后端服务无上下文路径

location /admin/ {
    proxy_pass http://127.0.0.1:3000/;  # 注意末尾 /
}

请求 /admin/users → 转发为 http://127.0.0.1:3000/users

② 把 /v1/ → 后端 /api/v1/ （路径替换）
适用于版本路由透传但需补全后端路径结构

location /v1/ {
    proxy_pass http://127.0.0.1:4000/api/v1/;  # 末尾 /
}

请求 /v1/posts → 转发为 http://127.0.0.1:4000/api/v1/posts

③ 正则匹配并重写（如 /api/v2/** → /v2/**）
适用于动态版本或需要条件改写路径

location ~ ^/api/(?<version>v\d+)/(.*)$ {
    rewrite ^/api/(?<version>v\d+)/(.*)$ /$version/$2 break;
    proxy_pass http://127.0.0.1:5000;
}</version></version>

请求 /api/v2/users?sort=id → 重写为 /v2/users?sort=id → 转发给后端

容易踩坑的细节

这些点不注意会导致 404、循环重定向或路径错乱：

proxy_pass 中的域名或 IP 必须可被 Nginx 解析，若用 localhost，确保没被 hosts 重定向到 127.0.0.1:80（引发自环）
使用 rewrite ... break 时，break 会终止后续 rewrite 并跳过 location 内其他指令；若要用 proxy_pass，必须保证 rewrite 后仍落在当前 location 内
开启 proxy_redirect 可修正后端返回的 Location 头（如 302 跳转地址），默认是 proxy_redirect default，一般无需改动，但后端返回绝对路径时建议显式设置：proxy_redirect http://backend/ /;
路径中含中文或特殊字符时，确保 client 和 backend 编码一致，并开启 underscores_in_headers on;（如需透传下划线字段）

调试技巧：快速验证路径行为

在 proxy_pass 前加一行日志，查看实际转发的 URI：

log_format upstreamlog '[$time_local] $upstream_addr : $request_uri → $upstream_http_location';
access_log /var/log/nginx/upstream.log upstreamlog;
<p>location /api/ {
set $backend "<a href="https://www.php.cn/link/f0838b2ebfc6440a474eabdc326bf31a">https://www.php.cn/link/f0838b2ebfc6440a474eabdc326bf31a</a>";
proxy_pass $backend/;
}</p>

配合 curl -v http://yourdomain/api/test 查看 access log 输出，比猜更可靠。