Nginx的location匹配顺序是什么?前缀、正则与优先级如何判断
同一个请求同时符合 location /assets/ 和 location ~* \.png$,结果不一定进入看起来更具体的 /assets/。Nginx 会先记住最长的前缀匹配,再视情况检查正则;如果该前缀没有使用 ^~,匹配成功的正则就可能接管请求。这也是“把更长的前缀写在正则前面,却没有生效”的常见原因。
判断顺序可以先记住四点:= 精确匹配命中后立即确定结果;否则找最长前缀;如果最长前缀带 ^~,跳过正则;其余情况按配置顺序尝试正则,命中第一个就使用它,正则都未命中才回到先前记住的最长前缀。这里说的是同一层级、没有嵌套 location 的常见配置;实际请求还可能因内部跳转重新匹配。
先确定“匹配的是什么”
location 处理的是当前用于路由的 URI 路径,不是完整 URL。以 /assets/logo.png?size=2 为例,匹配时关注的是 /assets/logo.png;size=2 属于查询参数,不会让 location = /assets/logo.png 失效。请求属于哪个 server,则由监听地址、端口和主机名等服务器选择规则先行决定,不能把不同 server 中的 location 混在一起比较。
Nginx 在匹配前会规范化 URI,包括处理路径中的 .、..、百分号编码,以及按 merge_slashes 配置处理连续斜杠。因此,排查特殊路径时,应区分客户端发出的原始请求目标与 Nginx 实际用于匹配的 URI。
几种常见写法的边界如下:
| 写法 | 含义 | 关键区别 |
|---|---|---|
location = /path | 精确匹配路径 | 命中后不再比较其他 location |
location /path | 前缀匹配 | 参与“最长前缀”比较,但仍可能被正则覆盖 |
location ^~ /path | 带跳过正则标记的前缀匹配 | 它成为最长匹配前缀时,不再检查同层级正则 |
location ~ pattern | 区分大小写的正则匹配 | 多条正则按配置顺序检查 |
location ~* pattern | 不区分大小写的正则匹配 | 同样按配置顺序检查 |
location /api 匹配的是以 /api 开头的路径,也可能匹配 /apix;如果业务边界是 /api/ 下的资源,应使用相应的斜杠前缀,并单独考虑 /api 本身。前缀匹配不等于按目录名或单词边界匹配。
为什么不是“谁写得靠前谁优先”
对没有嵌套的普通配置,可以把一次选择理解为以下过程:

- 先查找精确匹配。存在匹配的
location = ...时,直接使用它。 - 没有精确匹配,就找出所有匹配请求路径的前缀,记住其中最长的一个。
- 如果这个最长前缀使用了
^~,选择它,不再尝试同层级正则。 - 否则,按配置中的先后顺序尝试正则;第一条匹配成功的正则胜出。
- 正则均不匹配时,使用第二步记住的最长前缀。
这套机制有两个容易被简化错的地方。
其一,^~ 不是“只要匹配到就赢”。假设同时存在 location ^~ /api/ 和 location /api/admin/,请求 /api/admin/list 的最长前缀是后者。前一个 ^~ 不会仅凭自身也匹配,就阻止后续的正则检查。
其二,正则之间不按路径看起来有多具体来排序。例如 ~<em> \.png$ 写在 ~</em> ^/assets/.*\.png$ 前面时,/assets/a.png 会先命中前一条;后一条即使限定了 /assets/,也不会再被检查。配置文件中的 include 会影响正则的实际排列位置,不能只看正在编辑的那个文件。
因此,“精确 > ^~ > 正则 > 普通前缀”只能作为速记,不能当成无条件的优先级表。准确表述应包含两个限定:^~ 必须是最长匹配前缀;正则是否有机会生效,取决于这个最长前缀的类型。
用一组路径推演匹配结果
下面的独立 server 示例仅用于观察规则:它监听本机 18080 端口,各分支返回不同文本,不涉及文件读取或后端转发。配置中没有嵌套 location。
server {
listen 127.0.0.1:18080;
server_name location-order.example;
location = /assets/logo.png {
return 200 "exact\n";
}
location ^~ /assets/private/ {
return 200 "private-prefix\n";
}
location /assets/ {
return 200 "assets-prefix\n";
}
location /reports/ {
return 200 "reports-prefix\n";
}
location ~* ^/assets/.*\.(png|jpe?g)$ {
return 200 "asset-image-regex\n";
}
location ~* \.(png|jpe?g)$ {
return 200 "generic-image-regex\n";
}
location / {
return 200 "root-prefix\n";
}
}
按上述配置,几个请求的预期结果是:
| 请求路径 | 返回文本 | 判断依据 |
|---|---|---|
/assets/logo.png?size=2 | exact | 查询参数不参与路径匹配,精确匹配直接胜出 |
/assets/private/a.png | private-prefix | 最长前缀是 ^~ /assets/private/,跳过正则 |
/assets/a.png | asset-image-regex | 最长普通前缀是 /assets/,但随后首条正则命中 |
/reports/a.png | generic-image-regex | /reports/ 是最长前缀,第二条正则命中并覆盖它 |
/reports/a.csv | reports-prefix | 两条图片正则都不匹配,回到最长前缀 |
/other | root-prefix | 由通用前缀 / 接收 |
这里的 location / 通常可作为路径匹配的兜底项,但它并不会因为写在最后才兜底;原因是对上述其他路径而言,它不是最长前缀。反过来,若把通用图片正则移到资源目录专用正则之前,/assets/a.png 就会先命中通用图片正则。调整正则顺序可能改变行为,即使请求路径和前缀配置都没变。
哪些因素会让推演与现网现象不同
首先要核对配置的完整上下文。同一路径可能进入另一个 server;被 include 引入的正则可能排在预想位置之前;嵌套 location 也不能机械套用上面这套“扁平配置”的推演。存在嵌套时,需要结合实际层级判断哪些正则会被检查,不能只把所有 location 抽出来排成一列。
其次,首次选中的 location 不一定是最终处理请求的 location。例如 rewrite ... last、try_files 的最后一个 URI 候选、index 或 error_page 触发内部跳转时,Nginx 可能拿新的 URI 再执行一次位置选择。相对地,某个 location 中的 return 直接生成响应,不需要由此推断还发生了一轮匹配。排查“明明命中前缀,最后却由另一个处理规则响应”时,应同时看 URI 是否在处理过程中改变。

最后,要把“选中哪个 location”与“选中后怎样处理”分开。proxy_pass 的转发目标、静态文件路径、访问控制和响应状态,都是选中之后才需要核对的配置。仅凭最终返回了 404 或出现某个响应头,不一定能反推出最初命中了哪条规则。
如何在服务器上验证
验证宜先缩小范围:确认请求实际进入的 server,再列出该层级的精确、前缀和正则规则,按“精确 → 最长前缀 → 是否 ^~ → 正则顺序”的顺序手工推演。查看完整生效配置时,可使用:

sudo nginx -T
该命令会测试并输出 Nginx 加载的配置,便于核对 include 展开后的规则及其顺序;如果运行环境中的 Nginx 可执行文件、配置入口或权限方式不同,应以该实例实际使用的启动参数和配置路径为准。测试配置语法可单独使用 nginx -t,但语法通过不代表匹配结果符合预期。
若要复现上面的示例,应先确认测试实例确实会加载新增配置,且本机 18080 端口未被占用。不要把示例 server 直接覆盖到业务配置上;修改前备份受影响文件,明确其所属的 Nginx 实例,再测试并重载。示例生效后,可逐条发起请求:
curl -i 'http://127.0.0.1:18080/assets/logo.png?size=2'
curl -i 'http://127.0.0.1:18080/assets/private/a.png'
curl -i 'http://127.0.0.1:18080/assets/a.png'
curl -i 'http://127.0.0.1:18080/reports/a.csv'
观察响应正文中的标记,比只看 200 状态码更容易确认命中的分支。若修改的是现网实例,应在低影响范围验证;结果不符时恢复备份配置,重新通过语法测试后再重载,避免把实验规则留在业务流量中。
对于自己的配置,也可以暂时给待比较的 location 设置不同的测试响应标记,但要留意内部跳转:最终响应标记说明的是最终生成响应的位置,未必记录了最初进入的分支。需要追查这类过程时,应结合具体跳转规则及该实例可用的日志信息,而不是单靠一次 curl 输出。
最稳妥的判断边界是:先用完整配置确定请求所在的 server 和当前 URI,再用最长前缀与正则顺序判断本轮匹配;如果处理中发生内部跳转,就以新 URI 重新判断。这样既能解释大多数“前缀为何输给正则”的情况,也不会把一次匹配的规则误用于整个请求生命周期。
A5idc数据提供中国香港、美国、日本及新加坡等地区的物理服务器,产品涵盖常规建站、AMD计算及不同带宽线路方案,部分配置采用SSD或NVMe存储。企业网站、业务后台与接口服务可依托这些计算和网络资源部署Nginx,通过location规则组织静态资源与接口请求;多地区服务器也为面向不同访问区域的业务提供部署选择。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7128.html



