Nginx的location匹配顺序是什么?前缀、正则与优先级如何判断

发布人:A5数据发布时间:2026-11-02 12:48阅读量:91

同一个请求同时符合 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 本身。前缀匹配不等于按目录名或单词边界匹配。

为什么不是“谁写得靠前谁优先”

对没有嵌套的普通配置,可以把一次选择理解为以下过程:

为什么不是“谁写得靠前谁优先”配图

  1. 先查找精确匹配。存在匹配的 location = ... 时,直接使用它。
  2. 没有精确匹配,就找出所有匹配请求路径的前缀,记住其中最长的一个。
  3. 如果这个最长前缀使用了 ^~,选择它,不再尝试同层级正则。
  4. 否则,按配置中的先后顺序尝试正则;第一条匹配成功的正则胜出。
  5. 正则均不匹配时,使用第二步记住的最长前缀。

这套机制有两个容易被简化错的地方。

其一,^~ 不是“只要匹配到就赢”。假设同时存在 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=2exact查询参数不参与路径匹配,精确匹配直接胜出
/assets/private/a.pngprivate-prefix最长前缀是 ^~ /assets/private/,跳过正则
/assets/a.pngasset-image-regex最长普通前缀是 /assets/,但随后首条正则命中
/reports/a.pnggeneric-image-regex/reports/ 是最长前缀,第二条正则命中并覆盖它
/reports/a.csvreports-prefix两条图片正则都不匹配,回到最长前缀
/otherroot-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

相关推荐