Nginx 反向代理路径详解：proxy_pass 末尾斜杠的区别

前言

使用 Nginx 反向代理网站或 API 时，经常会遇到一种情况：后端服务本身运行正常，Nginx 配置检查也通过了，但访问代理地址却返回 404。

这时候不一定是后端程序的问题，也可能是 Nginx 转发请求时修改了 URL 路径。

尤其是 proxy_pass 后面的斜杠，虽然看起来只是一个很小的区别，却会直接影响请求最终被转发到哪个路径。

下面通过几个简单的配置示例，说明 Nginx 的路径匹配和转发规则。

一、一个最简单的反向代理

假设后端应用监听在本机的 3000 端口，可以通过以下配置转发请求：

server {
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

在这个配置中，用户访问 Nginx 的 /users 路径，请求会被转发到后端的 /users。

反向代理的主要作用是接收客户端请求，再交给后端服务处理，最后把响应返回给客户端。

这样可以把多个服务统一放在 Nginx 后面，也方便后续配置 HTTPS、访问日志和其他功能。

二、proxy_pass 末尾有没有斜杠？

这是本文最重要的部分。

先看第一种写法：

location /api/ {
    proxy_pass http://127.0.0.1:3000/;
}

假设用户访问：

/api/users

后端实际收到的路径是：

/users

原因是 proxy_pass 指定了 URI /，Nginx 会将匹配到的 /api/ 前缀替换为 /。

再看第二种写法：

location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

这次 proxy_pass 没有指定 URI。

相同的请求：

/api/users

在没有其他 URI 重写的情况下，后端收到的仍然是：

/api/users

也就是说，这两种写法虽然只差一个斜杠，但转发后的路径完全不同。

可以简单对比：

严格来说，关键不是斜杠这个字符本身，而是 proxy_pass 是否指定了 URI。

三、什么时候应该保留 /api 前缀？

假设后端程序已经定义了以下接口：

GET /api/users
GET /api/products
GET /api/orders

这时后端本身就需要 /api 前缀。

可以这样配置：

location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

请求路径会被保留。

但是，如果后端实际定义的是：

GET /users
GET /products
GET /orders

而希望用户通过 /api/users 访问，就可以使用：

location /api/ {
    proxy_pass http://127.0.0.1:3000/;
}

让 Nginx 在转发时去掉 /api/ 前缀。

所以配置反向代理之前，最好先确认后端真正需要的路径是什么，而不是看到别人使用某种写法就直接复制。

四、location 的匹配也很重要

除了 proxy_pass，location 的匹配规则也会影响请求最终由哪个配置处理。

例如：

location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

它可以匹配 /api/users、/api/orders 等路径。

对于普通前缀匹配，Nginx 会优先寻找最长的匹配前缀，但正则 location 和其他匹配修饰符也可能影响最终选择。

如果只是希望精确匹配某个地址，可以使用 =：

location = /health {
    return 200 "OK";
}

这条规则只精确匹配 /health。

需要注意，以 /api/ 结尾且配置了 proxy_pass 的前缀 location，在没有其他特殊匹配规则干预时，请求 /api 还可能被 Nginx 自动重定向到 /api/。

所以排查路径问题时，不仅要检查 proxy_pass，也要检查最终命中了哪个 location。

五、反向代理需要传递哪些请求头？

实际部署 Web 应用时，除了路径，还经常需要传递原始域名、客户端 IP 和访问协议。

可以参考以下配置：

location /api/ {
    proxy_pass http://127.0.0.1:3000;

    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;
}

其中：

• Host：把当前请求的主机名传递给后端。
• X-Real-IP：提供 Nginx 看到的客户端地址。
• X-Forwarded-For：记录经过代理的客户端地址链。
• X-Forwarded-Proto：让后端了解当前代理入口使用的协议。

如果后端需要根据原始域名生成跳转地址，这些请求头就可能非常重要。

不过也要注意，如果 Nginx 前面还有 CDN 或其他反向代理，$remote_addr 可能是上一层代理的地址，而不是真正的用户 IP。

此外，后端不能无条件相信客户端传入的 X-Forwarded-For，还需要设置可信代理范围，避免来源地址被伪造。

六、如何检查 Nginx 配置？

修改配置后，建议先执行：

sudo nginx -t

这条命令用于检查配置语法和部分配置文件访问问题。

如果检查成功，再执行：

sudo nginx -s reload

让 Nginx 重新加载配置。

这里需要注意，nginx -t 检查成功只代表配置通过了相关检查，并不能证明后端一定能正常访问。

如果想查看 Nginx 实际加载的完整配置，可以使用：

sudo nginx -T

这对于排查多个配置文件中存在重复的 server 或 location 规则很有帮助。

七、反向代理返回 404 怎么排查？

遇到 404 时，可以按照以下顺序处理。

首先，直接访问后端接口，确认后端提供了正确的路径：

curl -i http://127.0.0.1:3000/users

如果该接口本身不存在，自然无法通过代理访问。

其次，访问 Nginx 对应的代理地址：

curl -i http://127.0.0.1/api/users

这里假设 Nginx 监听本机 80 端口，且当前请求能够命中目标 server。如果配置了多个虚拟主机，还需要使用正确的 Host 请求头。

如果直接访问后端正常，但经过 Nginx 返回 404，就可以重点检查：

1. location 是否匹配了预期路径。
2. proxy_pass 是否保留或替换了路径前缀。
3. 请求是否进入了其他 server 或 location。
4. 后端是否对 Host、路径大小写等有额外要求。

如果返回的是 502，则通常应该优先检查后端地址、端口、进程监听状态和 Nginx 错误日志，而不是只修改路径斜杠。

八、几个容易忽略的问题

第一，proxy_pass 后面的斜杠不能随意添加。后端是否需要保留路径前缀，决定了应该使用哪种配置。

第二，修改配置后记得重新加载 Nginx，否则可能仍然使用旧配置。

第三，不要把所有 404 都当成路径错误。后端确实没有对应资源，也会正常返回 404。

第四，如果 location 使用正则表达式，或者配置了 rewrite、变量形式的 proxy_pass，URI 转发规则会有额外限制，不能完全照搬普通前缀匹配的示例。

第五，反向代理转发成功不代表 WebSocket、长连接等功能一定正常。此类协议可能还需要额外的请求头和超时配置。

总结

Nginx 反向代理的路径处理其实不难，关键是理解 location 和 proxy_pass 的关系。

在普通前缀 location 中：

• proxy_pass 带 URI 时，会按规则替换匹配到的路径前缀。
• proxy_pass 不带 URI 时，通常会保留原始请求路径。
• 后端接口是否包含 /api 等前缀，决定应该选择哪种写法。

遇到代理访问异常时，先确认后端实际路径，再检查 Nginx 匹配和转发规则，最后结合 curl 和日志排查。

很多看起来复杂的反向代理问题，实际上只是请求被转发到了错误的路径。