Nginx location 匹配优先级：一个让 502 变 404 的反斜杠

排查一个诡异案例：客户端偶发 404，后端服务日志却显示请求根本没到达。折腾两小时，结论是一个反斜杠引发的路由吞噬。

一、location 匹配的完整优先级

Nginx 收到请求后按这个顺序找 location：

1. 精确匹配 = /api/v1/health 直接命中即止

2. 前缀匹配 ^~ 命中后不再看正则

3. 正则匹配 ~ 或 ~* 按 configuration 顺序，第一个命中即止

4. 普通前缀匹配，取最长的那条

常见误解：以为写在前面的 location 优先。顺序只在正则之间有意义。

二、事故还原

配置里有两条：

location /api { proxy_pass http://backend; }

location ~ ^/api/v1/(.*)$ { return 404; }

开发同事加了第二条做旧版接口下线，结果所有 /api/v1/* 全部 404——正则优先级高于普通前缀，proxy_pass 根本没机会执行。

三、修复

location ^~ /api/ { proxy_pass http://backend; }

^~ 让前缀匹配跳过正则检查，一劳永逸。或者把正则改得更精确：^/api/v1/legacy/.*$。

四、调试技巧

- error_log 加 debug 级别，能看到 location 的完整匹配决策链

- curl -H "Host: x" 直接打 Nginx，排除上游干扰

- nginx -T 输出完整合并配置，别看碎片文件猜

五、沉淀

location 的四种匹配模式是四个不同的抽屉，精确、^~、正则、普通前缀——顺序只在同一个抽屉里有效。改配置前先画一遍决策树，比出事后翻日志快得多。