nginx location匹配按优先级而非书写顺序执行：先=精确匹配，再^~最长前缀锁死，后正则~/~*，最后无修饰符前缀；^~应优先用于稳定路径，正则需精简靠前，验证用nginx -t和add_header。
location 匹配被意外覆盖，根本原因不是配置写错了，而是 Nginx 的匹配机制没被理解清楚——它不看书写顺序，只按规则优先级“选最优”，而很多看似合理的规则，其实根本轮不到执行。
看清匹配优先级：不是谁在前面就先执行
Nginx 对每个请求只执行一条 location 块，流程是固定的：
- 先找 =（精确匹配），命中即停
- 再找 ^~（前缀匹配且锁死），最长前缀命中即停
- 如果没有 ^~ 中断，则按配置文件中出现顺序，逐条检查 ~ 和 ~* 正则
- 最后才考虑无修饰符的前缀匹配（如 location /api）和兜底的 location /
常见误判：把 location ~ ^/api/v2/.* 写在 location ^~ /api/ 后面，以为它能生效——实际只要请求是 /api/v2/user，就会被 ^~ /api/ 直接截走，正则根本不会被扫描。
用 ^~ 主动“锁死”关键路径
对明确、稳定的路径前缀（如 /static/、/healthz、/.git/），必须用 ^~，而不是依赖正则或普通前缀：
- location ^~ /static/ { try_files $uri =404; } → 稳定、零回溯、不往后查
- location ^~ /.git/ { deny all; } → 防止被后面 location ~ \.php$ 之类规则意外接管
- 避免写成 location /static/ 或 location ~ ^/static/，前者优先级低，后者引入正则开销且易被绕过
正则规则要精简、靠前、防冲突
如果确实需要正则（比如匹配多版本 API 或文件后缀），必须满足三个条件：
- 位置靠前：放在所有 ^~ 块之后、但要在通用 location / 之前；尤其不能被 location / 或 location ~ \.php$ 这类宽泛规则盖住
- 模式收敛：不用 .* 和 .+，改用 [^/]+、[a-z0-9_]+ 等限定字符集；避免 ^/api/v\d+/.*/.*$ 这类高回溯写法
- 合并同类项：把 /v1/、/v2/、/beta/ 统一写成 ^/api/(v[12]|beta)/，减少规则数量和匹配耗时
快速验证是否被覆盖
别只靠 reload 后测几个 URL，要用确定性方法确认实际生效规则：
- 运行 nginx -T | grep -A 5 "location.*your_path"，看完整展开后的配置顺序
- 发请求时加 curl -v https://yoursite.com/your-path，观察返回的 Server 和响应头，辅助判断走到哪个 server/location
- 在怀疑的 location 块里临时加 add_header X-Location-Hit "v2-api";，用响应头直接标记命中结果
