直接配 Nginx 的人谁没在location和proxy_pass上栽过跟头明明后端接口是对的代理过去就是 404明明 location 写了正则请求就是进不来proxy_pass后面多一个斜杠少一个斜杠转发路径完全两个样。这些东西官方文档写得清清楚楚但说实话真到排查问题的时候很少有人会去翻文档基本靠试试错了再改改完了过几天又忘。这篇就把location匹配和proxy_pass转发这两块彻底捋一遍该讲的原理讲透该给的配置直接给最后附上我这些年攒下来的排查经验和踩坑记录。这篇文章适合所有用 Nginx 做反向代理、网关路由、静态资源分离的开发和运维同学不管是刚入门还是配了好几年只要能耐心看完后面配置代理基本不用再靠猜。1. 别急着配先搞懂 location 匹配规则很多人配location全凭感觉写出来能跑就完事一旦出问题就抓瞎。其实location的匹配规则非常固定只要记住优先级和匹配特点任何请求进来你都能准确判断它会命中哪个块。1.1 五种匹配方式逐个拆解location后面跟的修饰符决定了匹配方式常见的有五种。第一种是精确匹配用开头比如location /api/login { proxy_pass http://backend; }这种写法要求请求 URI 必须完全等于/api/login多一个字符都不行/api/login/也匹配不上。它的优先级是最高的一旦命中后面的正则和前缀匹配全都不会执行。第二种是普通前缀匹配也就是什么都不加直接写路径location /api { proxy_pass http://backend; }这种匹配的是以/api开头的所有 URI比如/api/user/list、/api/order都能命中但/api2也能命中因为这个前缀匹配只看开头是不是/api不关心后面的字符边界。第三种是非正则前缀匹配用^~开头location ^~ /api { proxy_pass http://backend; }它和第二种的行为一样都是前缀匹配区别在于优先级只要命中了^~的 locationNginx 就不会再去检查正则表达式了。第四种是正则匹配用~或~*开头location ~ \.(png|jpg|gif)$ { root /data/images; } location ~* \.(css|js)$ { root /data/static; }~区分大小写~*不区分大小写。正则匹配的优先级低于精确匹配和^~前缀匹配但高于普通前缀匹配而且在同一层级的正则里面按配置文件里出现的先后顺序匹配谁先出现谁生效。第五种是命名 location用开头比如error、fallback。它不参与请求的直接匹配只能被try_files、error_page、rewrite等指令内部跳转外部请求进不来。1.2 匹配优先级Nginx 是怎么“挑选”的梳理一下 Nginx 收到一个请求时完整的匹配流程第一步检查精确匹配。如果有命中的直接使用这个 location后面所有的匹配全部跳过。第二步检查前缀匹配普通前缀和^~。Nginx 会遍历所有前缀 location找出匹配的那个而且是最长匹配。也就是说/api/user和/api都匹配/api/user/list时取更长的/api/user。第三步如果最长前缀匹配是^~类型的直接用它不再检查正侧。如果不是^~Nginx 会继续检查正则 location。第四步按配置文件中的顺序执行正则匹配一旦有命中的立即使用这个正则 location。第五步所有正则都没有匹配才会使用之前找到的最长前缀匹配。用一张优先级表方便对照匹配类型修饰符优先级精确匹配最高非正则前缀匹配^~高命中后跳过正则正则匹配~~*中按配置顺序普通前缀匹配无低取最长匹配这里的核心逻辑其实一句话就能概括Nginx 先用最长前缀找一个“保底”的 location再去看有没有更合适的正则^~和则是用来提前锁死结果不让正则插队的。1.3 用演示案例看懂匹配流程光说规则不够我用一个实际的配置演示完整匹配过程location /api { return 200 exact; } location ^~ /api/ { proxy_pass http://backend; } location ~ /api/\d { return 200 regex; } location /api/ { return 200 prefix; }请求/api进来命中精确匹配直接返回exact后面的完全不用看。请求/api/123进来精确匹配不中进入前缀匹配阶段/api/和^~ /api/都命中^~的优先级更高于是直接用这个 location 代理到后端正则/api/\d根本没机会执行。请求/api/user进来前缀匹配找到/api/它不是^~所以继续检查正则所有正则都不匹配最终使用普通前缀 location/api/。这个案例把优先级规则实际跑了一遍比死记硬背强得多。后面配置遇到“为什么我这个正则没生效”这种问题先回来看这个流程99% 的情况都能解释清楚。2. proxy_pass 的两种形态行为完全不同proxy_pass是反向代理的灵魂但它的行为取决于后面写的 URI 带不带斜杠和路径。这个细节坑了无数人我必须在这一节彻底讲清楚。2.1 带 URI 与不带 URI 的本质区别proxy_pass的两种写法# 写法一不带 URI proxy_pass http://backend; # 写法二带 URI proxy_pass http://backend/; proxy_pass http://backend/api/;带不带 URI 的区别在于如果 proxy_pass 后面只有协议和地址没有路径部分Nginx 会把原始请求的 URI 原封不动地转发给后端如果带了路径那么 location 匹配到的部分会被替换成 proxy_pass 里写的路径。我举个例子。假设请求进来是/api/user/infolocation 匹配的是/apilocation /api { proxy_pass http://backend; }因为proxy_pass没带 URI转发到后端的 URI 就是原始 URI也就是/api/user/info。后端收到的还是完整的路径要求后端接口本身就是/api/user/info才能对上。同样请求换成带 URI 的写法location /api { proxy_pass http://backend/; }转发到后端的 URI 就变成了/user/info因为/api这个部分被替换成了/。后端收到的就不是/api开头的路径了。这个替换逻辑是整个 Nginx 代理配置里最容易出错的地方下面我专门拆开讲。2.2 路径拼接规则与计算演示要算清楚最终转发的 URI有一个简单公式不带 URI 的 proxy_pass最终URI 原始URI带 URI 的 proxy_pass路径不带正则的 location最终URI proxy_pass 中的URI 原始URI去掉location匹配部分这里的“location 匹配部分”指的是 location 配置里写的那个前缀也就是 Nginx 用来做匹配的那一段字符串。我多列几个组合方便对照location 配置原始请求 URIproxy_pass 配置后端实际收到的 URIlocation /api/api/user/listhttp://backend/api/user/listlocation /api/api/user/listhttp://backend//user/listlocation /api//api/user/listhttp://backend/api/user/listlocation /api//api/user/listhttp://backend//user/listlocation /api/api/user/listhttp://backend/server/server/user/listlocation /api//api/user/listhttp://backend/server//server/user/list注意最后两行proxy_pass带了具体的路径/server那么 location 匹配掉的那一段就会被直接替换成/server。第一行里location 写的是/api原始 URI 是/api/user/listNginx 匹配到的前缀是/api替换后剩下的就是/user/list再加上proxy_pass里的/结果就是/user/list。这里有个细节很容易被忽略location 后面带不带斜杠会影响匹配出的前缀长度。location /api匹配/api/user/list时匹配出来的前缀是/apilocation /api/匹配同一 URI 时匹配出来的前缀是/api/。这两个在替换时结果可能完全不同。还有一种情况需要特别小心就是location是正则匹配的时候proxy_pass能不能带 URI 的问题下一小节展开。2.3 正则 location 下的特殊限制正则匹配的location里使用proxy_pass规则和普通前缀匹配不一样proxy_pass不能带 URI 路径部分。如果带了Nginx 启动时会直接报错。具体来说location ~、location ~*下面proxy_pass只能写成http://backend这种不带路径的形式不能写成http://backend/更不能写成http://backend/api/。这是 Nginx 的设计限制因为正则匹配本身是动态的不像前缀匹配那样可以明确算出被替换的路径范围所以 Nginx 禁止在正则 location 里对 URI 做替换。# 这样写启动会报错 location ~ ^/api/\d$ { proxy_pass http://backend/api/; } # 必须这样写 location ~ ^/api/\d$ { proxy_pass http://backend; }为什么很多人还是会把这两个搞混因为很多反向代理场景里正则 location 的匹配结果和前缀 location 看起来差不多但 Nginx 的语法限制是硬性的配置之前一定要看清自己写的是哪一类 location。如果非要在正则 location 里做路径改写办法是用rewrite把 URI 先改掉再交给proxy_pass处理。但rewrite的用法和proxy_pass的替换逻辑又不一样建议优先通过调整 location 的写法来规避不要硬绕。3. 高频场景配置实例原理讲清楚了接下来上实战。我挑几个最常用的反向代理场景直接给出完整配置和要点说明你照着改就能用。3.1 前后端分离静态资源与 API 分流现在前后端分离的项目前端打包出来的静态文件放在服务器上后端接口单独跑在一台服务上。Nginx 需要做到静态资源直接读文件系统接口请求转发到后端二者互不干扰。server { listen 80; server_name example.com; # 静态资源直接返回文件 location /assets/ { alias /data/frontend/assets/; expires 7d; add_header Cache-Control public; } # 接口转发到后端服务 location /api/ { proxy_pass http://backend_api; 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; } # 前端页面入口 location / { root /data/frontend; index index.html; try_files $uri $uri/ /index.html; } }这里的location /api/用了前缀匹配proxy_pass http://backend_api不带 URI所以后端收到的 URI 还是完整的/api/xxx路径。后端如果用的是 Spring Boot 这类框架接口路径里带着/api前缀这种配置直接就能通。注意静态资源的alias和root的区别。alias /data/frontend/assets/表示请求/assets/foo.png时实际查找的文件是/data/frontend/assets/foo.png也就是用 alias 路径替换掉 location 前缀。如果用root则实际查找的是/data/frontend/assets/assets/foo.png路径会多一层所以静态资源这种情况下用alias更直观。try_files $uri $uri/ /index.html是前端路由比如 vue-router、react-router 的 history 模式的标配不管地址栏输入什么非静态资源路径都回落到index.html交给前端路由去渲染。3.2 WebSocket 代理的注意点WebSocket 和普通的 HTTP 代理有个关键区别连接需要升级长连接要保持不断。Nginx 默认是按 HTTP/1.0 转发上游请求的如果不加配置WebSocket 会直接握手失败。正确配置location /ws/ { proxy_pass http://backend_ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 3600s; }proxy_http_version 1.1是必须的因为 HTTP/1.0 不支持 Upgrade 头。Upgrade和Connection两个头是用来告诉后端“这个请求要升级成 WebSocket 协议”的缺一个都不行。proxy_read_timeout建议设长一些。默认的 60 秒意味着如果 60 秒内后端没有任何数据返回Nginx 会主动断开连接。WebSocket 场景下服务器可能 10 分钟才推一次心跳这个时间必须改否则客户端会不定时掉线。反向代理后的 WebSocket 还有个常见问题客户端连的是ws://example.com/ws但后端拿到的 Host 变成了 Nginx 的地址。如果后端的 WebSocket 服务做了域名校验需要在proxy_set_header Host $host之外补充proxy_set_header Origin $http_origin。发心跳检测的时候后端的业务逻辑可能依赖X-Real-IP拿客户端真实 IP这些请求头都要一并带上proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;WebSocket 连接一旦建立Nginx 基本就是个透明隧道数据不再经过 Nginx 的应用层处理所以转发效率很高。正因如此proxy_read_timeout和proxy_send_timeout是唯一能控制长连接存活的开关实测场景里 90% 的 WebSocket 掉线问题都出在这一项。3.3 路径重写与代理结合不少老系统的接口路径混乱比如前端请求/new-api/user/info但后端实际接口是/v1/user/info。这时不能简单改后端代码就要靠 Nginx 做路径重写。推荐的办法是组合使用rewrite和proxy_passlocation /new-api/ { rewrite ^/new-api/(.*)$ /v1/$1 break; proxy_pass http://backend; }解释一下rewrite把原始 URI/new-api/user/info改写成/v1/user/info命中break标志后在当前 location 内继续处理然后proxy_pass转发。因为proxy_pass不带 URI转发的就是改写后的/v1/user/info。这个方案比在proxy_pass里强行带 URI 写正则要可靠得多因为proxy_pass带 URI 和rewrite组合时的行为非常绕一不小心就出现路径拼接错误。如果对 Nginx 对rewrite的执行顺序不熟悉可以记住一个原则rewrite在proxy_pass之前执行break标志表示改完以后不再执行后续重写和重定向直接把当前 URI 交给代理转发。还有一种场景是去掉前缀反向代理比如把/api/user代理成后端/userlocation /api/ { rewrite ^/api/(.*)$ /$1 break; proxy_pass http://backend; }请求/api/user进来rewrite 改成/user后端收到的路径就是/user。这里要注意location /api/末尾的斜杠如果漏掉/api2这种路径也会进到这个块里rewrite 匹配不到就会出奇怪的问题。4. 实战踩坑与排查技巧配置写多了总会踩坑这一节把我遇到过的、以及身边同事问得最多的问题集中整理出来按现象分类直接给排查方法和解决思路。4.1 常见故障现象与根因故障一代理后全是 404这个是最常见的。现象是接口直接访问后端服务能通通过 Nginx 访问就 404。根因基本可以锁定在路径不一致上后端接口是/api/user但你配置的proxy_pass带 URI 把/api替换掉了转发到后端的路径变成了/user后端没这个路径自然 404。排查方法很简单打开 Nginx 的 access log看转发出去的实际 URI或者直接在location里加一行location /api/ { add_header X-Debug-URI $request_uri always; proxy_pass http://backend; }请求进来以后用curl -I看返回头里的X-Debug-URI就知道 Nginx 拿到的原始 URI 是什么。然后到后端服务的 access log 里找对应的 URI两边一对比问题就清楚了。故障二代理后变成 502502 意味着 Nginx 连不上后端。先确认后端服务是不是真的活着然后看 Nginx 的upstream配置upstream backend { server 127.0.0.1:8080 max_fails3 fail_timeout10s; } server { location /api/ { proxy_pass http://backend; } }proxy_pass http://backend里的backend必须对应一个upstream名字名字拼错了 Nginx 启动时就报错了。如果启动时没报错但运行中突然 502大概率是后端挂了或者被max_fails踢下线了。还有一个容易忽略的原因proxy_pass 写的后端地址带不带协议。必须是http://开头写成proxy_pass backend这种 Nginx 不会识别直接启动报错。故障三WebSocket 总是掉线前面讲过proxy_read_timeout的坑但这个问题的真正排查思路是先确认后端有没有发心跳包再看 Nginx 的 timeout 配的多长。如果后端每 30 秒发一次心跳Nginx 配了 60 秒正常但如果后端用的是第三方库心跳间隔不确定就把 Nginx 的 timeout 直接拉到 3600 秒宁可配置大一点也别让连接在业务中间断掉。如果你用curl -i测试 WebSocket 接口看到返回的101 Switching Protocols说明握手阶段通了。这时掉线问题就锁定在连接保持上去看 timeout 和防火墙的闲置连接断开策略很多云服务商的负载均衡层默认会断掉空闲 60 秒的连接这种问题配 Nginx 是解决不了的要去找链路里其他的转发组件。4.2 调试利器与排查思路Nginx 自带的调试手段其实很够用关键是要会用。第一招开启error.log调试级别error_log /var/log/nginx/error.log debug;调试级别日志会打出 Nginx 处理每个请求的完整流程包括匹配了哪个 location、执行了哪些 rewrite、转发给哪个 upstream、结果如何。排查复杂问题时这个日志的参考价值非常高。注意线上环境不要长期开 debug日志量太大磁盘容易爆排查完立刻改回warn或error。第二招利用return指令做短路测试想验证某个 location 是否被命中不用真的代理到后端直接返回一个固定状态码location /test/ { return 200 hit test location; }curl http://example.com/test/foo返回这个字符串就说明请求确实进入了这个 location后面再逐步加proxy_pass。这个方法对验证匹配规则特别有效比一次次改配置、reload、观察日志要快得多。第三招验证 rewrite 结果在 rewrite 后面加一行return 200 $uri看改写后的值location /api/ { rewrite ^/api/(.*)$ /$1 break; return 200 after rewrite: $uri; }请求/api/user返回after rewrite: /user说明 rewrite 生效了再删掉 return 换成 proxy_pass。这一招省去了反复试错的过程。第四招检查配置语法每次改完配置先执行nginx -t语法检查通过再执行nginx -s reload。如果nginx -t报错它通常会明确告诉你哪个文件哪一行有问题比如正则 location 里的 proxy_pass 带了 URI这个错误在nginx -t阶段就会被拦截。不要跳过这个步骤直接 reload那是在拿线上环境做实验。第五招实测请求头nginx 转发给后端时真实请求头是什么用户可以借助后端的回显接口来确认。假如某公司有个 demo 回显服务返回收到的所有请求头和 URI把它配成后端一次请求就能看到 Nginx 实际转发了什么过去location /debug/ { proxy_pass http://127.0.0.1:9000/echo; }后端收到什么一目了然。这个方法比猜配置靠谱得多常用于确认Host、X-Forwarded-*头和 URI 的最终形态。4.3 常见问题速查表我手头整理了一份速查表把平时高频出现的问题和对应的解法都收进来可以直接当成手册用现象主要原因解决方法代理后 404proxy_pass带 URI 替换掉路径检查后端接口路径调整 proxy_pass 写法或加 rewrite代理后 502后端服务挂了/超时/upstream 踢下线排查后端健康状态调整max_fails和fail_timeout正则 location 不生效前缀匹配优先或正则顺序靠后确认没有^~干扰调整正则顺序总是命中错误 location普通前缀匹配选择最长匹配检查 location 前缀长度必要时用^~锁定WebSocket 握手失败缺少 Upgrade 头或 HTTP 版本不对配置proxy_http_version 1.1和 Upgrade 相关 headerWebSocket 掉线read_timeout太短或中间链路断空闲连接调大proxy_read_timeout检查链路组件静态资源路径不对root和alias用混了按规则重新选择指令确认路径拼接代理后拿到的是内网 IP没设置X-Forwarded-For添加proxy_set_header X-Forwarded-For相关配置改了配置不生效没有 reload 或语法错误被忽略执行nginx -t确认后用nginx -s reload这张表本质上还是围绕两个根源展开一是 location 匹配路径不对二是 proxy_pass 替换规则不符合预期。把这两个根源吃透了大部分问题看一眼配置就能定位。我在实际配置中最常犯的一个低级错误是改完 location 以后忘记检查proxy_pass后面有没有多余的斜杠。比如从proxy_pass http://backend/改成proxy_pass http://backend看起来差别不大但后端收到的路径就变了。所以现在我每次改完配置都会用上面说的 debug location 方法验证一遍实际转发的 URI确认无误才收手。另外还有一个小技巧用nginx -T可以打印出当前完整的生效配置里面包含所有 include 进来的文件排错时比在/etc/nginx/conf.d里一个个翻文件高效得多。配上grep搜索关键词一分钟就能找到目标 server 块和相关 location 配置。这个命令在配置特别多、又是多层 include 的情况下几乎成了我的救星。最后分享一个我坚持了很久的习惯每个项目我都会把 location 和 proxy_pass 的对应关系画一张简表哪个前缀匹配进哪个后端proxy_pass 带不带 URI预期转发路径是什么全部列出来更新配置时先改表再改配置。看起来多了一步实际上省掉的是无数次线上踩坑后的排查时间。你也试试看配 Nginx 会变得从容很多。