nginx location匹配按四类符号优先级执行：=最高，^~次之且不回退，~和~*按配置顺序匹配，无修饰符最低；同一请求仅进入最高优先级中首个成功匹配块。
在 Nginx 中，location 匹配不是简单的“从上到下”或“最长前缀”，而是严格按 匹配类型优先级 + 规则顺序 两级机制执行。理解这个机制，是写出稳定、可预期路由逻辑的前提。
location 匹配的四类符号及其硬性优先级
Nginx 将所有 location 块按匹配方式分为四档，**同一请求只进入最高优先级中第一个匹配成功的块**，后续同级或低级规则全部跳过：
-
=（精确匹配）：优先级最高。必须完全一致（含大小写、结尾斜杠），如
location = /api只匹配/api，不匹配/api/或/api/users。 - ^~（前缀匹配，非正则且禁止回退）：第二高。匹配最长前缀路径，一旦命中即终止搜索，不会尝试任何正则 location。适合静态资源、API 前缀等确定性路径。
-
~ 和 ~*（区分/不区分大小写的正则匹配）：第三级。Nginx 按配置文件中出现的**顺序依次尝试**，遇到第一个成功匹配的即停止。注意：
~*不区分大小写但性能略低；~区分大小写但更高效。 - 无修饰符（普通前缀匹配）：优先级最低。也是找最长前缀，但仅在“没有 =、^~、正则匹配成功”时才启用。它本质是兜底行为。
关键细节：^~ 的“非回退性”与常见误用
^~ 是最容易被误解的符号。它的核心语义是：一旦匹配成功，Nginx 立即停止 location 查找，不再检查任何正则表达式（哪怕写在它后面）。
例如：
location ^~ /static/ {
alias /var/www/static/;
}
location ~ \.js$ {
add_header X-Handler js;
}
访问 /static/app.js 会进入 ^~ /static/ 块，不会触发 .js 正则——即使正则更“精确”。若希望 JS 文件走正则处理，必须将正则块提前，或改用 = /static/app.js 等精确匹配覆盖。
正则 location 的顺序敏感性与调试技巧
当多个 ~ 或 ~* 并存时，顺序决定结果。Nginx 不做“最长正则”或“最具体正则”判断，只认第一个成功匹配项。
- 错误写法（后置通用正则覆盖前置特例）：
location ~ \.html$ { ... }<br> location ~ \.php$ { ... }<br> location ~ \..*$ { ... }
→ 所有带点的路径都会被最后一个捕获，前面两个失效。 - 正确做法：把更具体的正则放前面，通用兜底放最后；或用
=或^~提前截断。 - 调试建议：启用
error_log /path/to/log notice;，配合nginx -t验证语法，并用curl -I查看响应头中的X-Handler类标记来验证实际进入的 location。
混合场景下的真实匹配流程（以请求 /api/v2/users?id=1 为例）
假设配置如下：
location = /api { ... }
location ^~ /api/ { ... }
location ~ ^/api/v\d+/ { ... }
location /api/ { ... }
匹配过程为：
- 检查
= /api→ 请求是/api/v2/users，不匹配； - 检查
^~ /api/→/api/v2/users以/api/开头，匹配成功 → 立即进入该块，忽略后续所有正则和普通前缀； - 即使
~ ^/api/v\d+/在语义上更精确，也完全不参与本次匹配。
若想让版本号正则生效，需删除或注释掉 ^~ /api/，或将其改为更短前缀（如 ^~ /api），再靠正则细化分流。
