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

问题现象

在前后端分离的 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指令的路径处理规则

问题的根源在于 Nginx proxy_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 前缀而后端收不到”这个经典问题的核心在于理解 Nginx proxy_pass 指令的路径处理规则：

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

到此这篇关于Nginx 代理路径重写问题解析：为什么前端携带了 /api 前缀后端却无法访问的文章就介绍到这了,更多相关nginx 代理路径重写内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！