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

问题现象

在前后端分离的 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;