现象:proxy_pass 加 upstream 后接口全是 404
给后端 API 集群加了 Nginx upstream 做负载均衡,proxy_pass 写成 http://api_baCkend 以为大功告成,结果所有请求都是 404。curl 测上游服务器本身接口正常,Nginx access_log 显示请求确实转发到了 upstream 但 URL 路径被改写了。排查半小时才发现是 location 和 proxy_pass 末尾斜杠的经典坑。
根因:proxy_pass 末尾斜杠决定路径怎么拼
Nginx proxy_pass 有两种行为:URL 里带 URI(末尾有 /)时,location 匹配部分会被替换成 URI;不带 URI 时完整 location 原样透传。最经典的坑:location /api/ 配了 proxy_pass http://api_backend;(末尾没斜杠),浏览器请求 /api/users,上游收到 /api/users 没问题;但 proxy_pass 写成 http://api_backend/(末尾有斜杠),上游收到的是 /users,api 前缀被吃掉了。
# location 无尾斜杠 / proxy_pass 有尾斜杠 - 路径被替换
location /api {
proxy_pass http://api_backend/;
}
# 请求 /api/users -> 上游收到 /users
# location 有尾斜杠 / proxy_pass 无尾斜杠 - 完整透传
location /api/ {
proxy_pass http://api_backend;
}
# 请求 /api/users -> 上游收到 /api/users
加 upstream 后更要小心
用 upstream 后 proxy_pass 只能写 http://upstream_name 或 http://upstream_name/,不能带端口。规则和直连一样:末尾有 / 就替换,没 / 就透传。后端接口本身不带 /api 前缀(微服务常见)时,要用带斜杠的 proxy_pass 把前缀去掉。
upstream api_backend {
server 127.0.0.1:8001;
server 127.0.0.1:8002;
}
server {
location /api/ {
proxy_pass http://api_backend/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
快速验证
配完用 curl 加上游 IP 直接测接口,和通过 Nginx 测,对比返回是否一致。直接测正常、走 Nginx 404,十有八九是路径被改写了,回头检查 location 和 proxy_pass 的尾斜杠组合。Nginx 这个行为文档里有写但很少被注意到,属于"看一眼就懂、不看就踩坑"的类型。
总结:proxy_pass 404 八成是 location 和 proxy_pass 末尾斜杠组合错了。记住规则——proxy_pass 带 / 就替换 location,不带 / 就透传。加 upstream 后规则一样,只要关注末尾斜杠就好。
