问题现象

在前后端分离的 Web 项目中，我们经常使用 Nginx 作为反向代理服务器。一个典型的配置场景是：前端页面通过/api前缀将请求发送给 Nginx，期望 Nginx 将这些请求代理到后端服务（例如运行在http://localhost:8080的 Spring Boot 应用）。然而，开发者常常会遇到一个令人困惑的问题：

• 前端请求：http://your-domain.com/api/user/list
• Nginx 配置：看起来正确地将/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/list
• Nginx 转发给后端的请求：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/list
• location /api/匹配到/api/
• Nginx 将其删除，剩余/user/list
• 拼接到代理目标路径/后面：/user/list
• Nginx 转发给后端的请求：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;

1. 检查 Nginx 配置语法：运行nginx -t确保配置无误。
2. 查看 Nginx 访问日志：在配置中添加或检查访问日志格式，确认 Nginx 收到的原始请求。
3. 查看后端应用日志：确认后端实际接收到的请求路径。
4. 使用 curl 或浏览器开发者工具：直接测试 API 端点，观察请求和响应。

总结

“前端带/api前缀而后端收不到”这个经典问题的核心在于理解 Nginxproxy_pass指令的路径处理规则：

• proxy_pass http://backend-host;(无尾随/)：传递完整URI。
• proxy_pass http://backend-host/;(有尾随/)：进行路径替换，去掉location匹配的部分。