nginx location匹配优先级为:1.精确匹配(=);2.前缀匹配(^~),命中即终止正则检查;3.正则匹配(~、~*),按书写顺序取首个命中;4.普通前缀匹配,选最长;5.通用匹配(/)兜底。

Nginx 的 location 匹配不是简单按配置顺序从上到下执行,而是有一套明确的、固定的优先级逻辑。理解这个优先级,是避免 404、路径错转、正则被跳过等常见问题的关键。
匹配优先级从高到低依次为
1. 精确匹配(=)
只匹配完全相同的 URI,不带查询参数,也不容许末尾斜杠差异。
例如:location = /api 只匹配 /api,不匹配 /api/、/api/v1 或 /api?x=1。
2. 前缀匹配(^~)
以指定字符串开头即匹配,且一旦命中,**立即终止后续所有正则检查**,不看 ~ 或 ~*。
适合静态资源、API 前缀等需稳定、高效、不被正则干扰的场景。
例如:location ^~ /static/ 匹配 /static/css/app.css,即使后面有 location ~ \.css$ 也不会生效。
3. 正则匹配(~ 和 ~*)
区分大小写(~)或不区分(~*),按配置文件中出现的**书写顺序自上而下执行**,第一个命中即停止。
注意:只有在没有更高级别的精确或 ^~ 匹配时,才会进入这一阶段。
例如:location ~* \.(js|css|png)$ 可统一处理各类静态资源,但必须确保它没被前面的 ^~ /static/ 拦截。
4. 普通前缀匹配(无修饰符)
也是前缀匹配,但优先级低于 ^~;Nginx 会先收集所有这类 location,选出**最长匹配的那一个**作为候选。
若该最长匹配带有 ^~,直接采用;否则,继续往下检查正则;若正则全不匹配,才回退使用这个最长前缀匹配。
例如:location /admin 和 location /admin/users 同时存在,请求 /admin/users/list 会命中后者(更长)。
5. 通用匹配(location /)
兜底规则,所有请求都至少会匹配到这里,但优先级最低,仅当其他规则全部未命中时才生效。
关键细节提醒
- 匹配对象是
$uri,即解码后的路径部分,不包含查询参数(?key=val)和锚点(#section) - 所有匹配都不区分请求方法(GET/POST 等),只看路径
- 多个
location块可共存,Nginx 内部一次性完成全部比对,不是“逐行扫描” -
^~和普通前缀匹配都属于“前缀匹配”,但^~具有“中断正则”的语义特权
一句话总结决策流程
Nginx 先找有没有 = 精确匹配;没有就找出所有前缀匹配中最长的那条;如果这条带 ^~,立刻用它;否则继续按顺序试正则;正则全失败,才用刚才那个最长前缀;实在没得选,才落到 location /。











