Nginx 代理路径重写问题解析：为什么前端携带了 /api 前缀，后端却无法访问？

问题现象在前后端分离的 Web 项目中我们经常使用 Nginx 作为反向代理服务器。一个典型的配置场景是前端页面通过/api前缀将请求发送给 Nginx期望 Nginx 将这些请求代理到后端服务例如运行在http://localhost:8080的 Spring Boot 应用。然而开发者常常会遇到一个令人困惑的问题前端请求http://your-domain.com/api/user/listNginx 配置看起来正确地将/api路径代理到了后端。后端日志却显示收到了/user/list的请求缺少了/api前缀。结果后端因为没有/api这个路由映射返回 404 错误。为什么前端明明携带了/api前缀经过 Nginx 代理后后端收到的请求却没有这个前缀了呢核心原因proxy_pass指令的路径处理规则问题的根源在于 Nginxproxy_pass指令对 URI 的处理方式。其行为取决于proxy_pass后跟的代理目标地址是否包含路径部分。规则一代理目标地址不带路径当proxy_pass后面的地址只有协议://主机:端口没有以/结尾的路径时Nginx 会将客户端请求的原始 URI包含/api前缀完整地传递给后端。location /api/ { # 代理目标不带路径 proxy_pass http://localhost:8080; }请求转换过程前端请求GET /api/user/listNginx 转发给后端的请求GET /api/user/list(发送到http://localhost:8080/api/user/list)这种情况下后端需要能处理/api/user/list这个路径。规则二代理目标地址带路径当proxy_pass后面的地址包含以/结尾的路径时Nginx 会进行路径替换将location匹配到的部分即/api/从原始 URI 中删除然后将剩余部分拼接到代理目标的路径后面。location /api/ { # 代理目标带路径以 / 结尾 proxy_pass http://localhost:8080/; }请求转换过程前端请求GET /api/user/listlocation /api/匹配到/api/Nginx 将其删除剩余/user/list拼接到代理目标路径/后面/user/listNginx 转发给后端的请求GET /user/list(发送到http://localhost:8080/user/list)这正是大多数问题出现的原因开发者本意是想把请求代理到后端根路径但无意中在proxy_pass地址末尾加了一个/导致了路径被“吃掉”。解决方案与配置示例根据你的后端路由设计选择以下一种配置方式。方案一后端需要完整路径包含 /api 前缀如果你的后端控制器统一配置了RequestMapping(/api)或类似前缀你需要让 Nginx 保留/api前缀。server { listen 80; server_name your-domain.com; location /api/ { # 关键proxy_pass 地址末尾不要加 / proxy_pass http://localhost:8080; # 可选添加一些常用代理头 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }方案二后端不需要 /api 前缀更常见如果你的后端路由直接从根路径开始例如GetMapping(/user/list)你希望 Nginx 去掉/api前缀。server { listen 80; server_name your-domain.com; location /api/ { # 关键proxy_pass 地址末尾加上 / proxy_pass http://localhost:8080/; # 同样可以添加代理头 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }方案三使用rewrite指令进行更灵活的重写如果路径转换逻辑更复杂例如将/api/v1/重写为/v1/可以使用rewrite指令配合break标记。location /api/ { # 去掉 /api 前缀保留其他部分 rewrite ^/api/(.*)$ /$1 break; proxy_pass http://localhost:8080; proxy_set_header Host $host; # ... 其他头 }break标记表示重写后的 URI 在当前 location 内不再匹配其他rewrite规则并直接用于proxy_pass。调试与验证技巧log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for; access_log /var/log/nginx/access.log main;检查 Nginx 配置语法运行nginx -t确保配置无误。查看 Nginx 访问日志在配置中添加或检查访问日志格式确认 Nginx 收到的原始请求。查看后端应用日志确认后端实际接收到的请求路径。使用 curl 或浏览器开发者工具直接测试 API 端点观察请求和响应。总结“前端带/api前缀而后端收不到”这个经典问题的核心在于理解 Nginxproxy_pass指令的路径处理规则proxy_pass http://backend-host;(无尾随/)传递完整URI。proxy_pass http://backend-host/;(有尾随/)进行路径替换去掉location匹配的部分。