先看一个最常见的翻车现场：后端服务在8080端口的/api路径下提供接口，Nginx上配置了location /api/加proxy_pass http://127.0.0.1:8080/;，结果后端日志里收到的请求全是/开头的路径，api这一段凭空消失了。而把斜杠去掉改成proxy_pass http://127.0.0.1:8080;之后，路径又变成了/api/xxx。同样一个斜杠，转发结果天差地别，这就是proxy_pass斜杠问题的典型表现。
proxy_pass的核心规则：带不带URI是分水岭
判断proxy_pass的转发行为，只需要记住一条核心规则：看proxy_pass指令的值里带不带URI部分。这里的URI指的是域名端口后面那一段路径，哪怕只是一个斜杠/，也算带URI。
当proxy_pass不带URI时，也就是只写到端口就结束了，例如proxy_pass http://127.0.0.1:8080;，Nginx会把原始请求的完整路径原封不动地透传给后端。客户端请求/api/user/list，后端收到的就是/api/user/list，location匹配到的部分不会被裁剪。
而当proxy_pass带URI时，例如proxy_pass http://127.0.0.1:8080/;，Nginx的行为就完全变了：它会拿请求URI中匹配掉location的那部分前缀，替换成proxy_pass里指定的URI。假设location是/api/，proxy_pass是http://127.0.0.1:8080/，客户端请求/api/user/list，匹配掉的前缀是/api/，剩余部分是user/list，替换后后端收到的是/user/list。这就是开头那个api凭空消失的原因。
换句话说，proxy_pass末尾那个斜杠并不是可有可无的装饰，它本身就是URI为/的合法写法，直接改变了Nginx的路径处理逻辑。
四种常见组合的实际转发效果对比
为了直观对比，我们固定location为/api/，后端为http://127.0.0.1:8080，客户端请求/api/user/list，逐一验证四种典型写法。
第一种：location带斜杠，proxy_pass不带URI，即location /api/加proxy_pass http://127.0.0.1:8080;。后端收到/api/user/list，路径原样透传。适合后端服务本身就部署在/api前缀下的场景。
第二种：location带斜杠，proxy_pass带斜杠，即proxy_pass http://127.0.0.1:8080/;。后端收到/user/list，/api/前缀被替换成了/。适合后端服务根路径就是接口根路径，前端调用带/api前缀、后端处理时不带的场景，这是前后端分离项目中最常用的写法。
第三种：proxy_pass带自定义路径，例如proxy_pass http://127.0.0.1:8080/v2/;。后端收到/v2/user/list，/api/被替换成/v2/。可以用来做接口版本重写，无需额外配置rewrite。
第四种：location是精确匹配或正则匹配。精确匹配location = /api时路径处理比较特殊，而正则匹配的location中，proxy_pass是被禁止带URI的，写了斜杠直接报配置错误。汇总成表格如下：
| 写法 | 后端收到的路径 |
|---|---|
| proxy_pass http://127.0.0.1:8080; | /api/user/list |
| proxy_pass http://127.0.0.1:8080/; | /user/list |
| proxy_pass http://127.0.0.1:8080/v2/; | /v2/user/list |
| 正则location中带URI | 配置报错，禁止使用 |
正则与命名location中的限制及替代方案
当location使用正则表达式（如location ~ ^/api/）或者命名location（location @backend）时，Nginx无法知道精确匹配的前缀长度，因此压根不允许proxy_pass携带URI，末尾带个斜杠都会在nginx -t检查时报错，提示proxy_pass不能有URI。这种情况下如果需要改写路径，就得借助rewrite。
location ~ ^/api/(.*)$ {
# 正则location中proxy_pass禁止带URI，用rewrite实现前缀替换
rewrite ^/api/(.*)$ /$1 break;
proxy_pass http://127.0.0.1:8080;
}这里的关键是rewrite末尾的break标志，它让重写后的URI直接在当前location内继续处理，不再重新匹配location，从而交给proxy_pass转发。如果写成last，URI会重新走一遍location匹配，可能造成循环或者落到别的location上。
另外要注意，当location是proxy_pass写在if块里或者使用了变量的情况，例如proxy_pass http://$backend;，此时Nginx不会自动做前缀替换，传给后端的路径是原始URI，若想改变路径同样需要配合rewrite处理。
实践建议：如何避免斜杠引发的404
第一，配置前先和后端开发确认清楚接口的真实前缀。如果后端Tomcat、Spring Boot应用本身就部署在/api上下文路径下，那么直接透传即可，proxy_pass不要带URI；如果后端接口没有这个前缀，就用带斜杠的写法把前缀剥掉。这个信息不确认清楚，配置就是碰运气。
第二，调试时别只看浏览器结果，要多看后端访问日志。后端日志里记录的request路径才是最终真相。也可以临时在后端打印X-Forwarded-*相关头信息，确认转发的完整请求形态。
第三，保持location和proxy_pass的斜杠风格一致。推荐两种规范组合：要么location /api/加proxy_pass http://backend/;（剥前缀），要么location /api加proxy_pass http://backend;（透传）。尽量避免location /api加proxy_pass http://backend/;这种混合写法，虽然Nginx能处理，但匹配前缀的计算容易让人困惑，维护时极易出错。
最后补充一个容易忽略的细节：末尾斜杠问题还存在于location本身。客户端请求/api（不带末尾斜杠）时，如果只配置了location /api/，该请求不会被这个location命中，可能落到默认location去。稳妥的做法是两个都配，或者利用Nginx对目录式location的自动301重定向行为来兜底。搞懂了斜杠背后的URI替换机制，再遇到路径莫名的404，就能快速定位到底是哪一层的斜杠出了问题。
Nginx proxy_pass反向代理路径匹配修改时间：2026-09-03 18:19:02