Nginx location 匹配规则测试器 — 为何是这个块

nginx location 匹配：快速解答

什么是 nginx location 块？

# From the nginx documentation. Which block serves each request?
server {
    location = /                   { }   # A
    location /                     { }   # B
    location /documents/           { }   # C
    location ^~ /images/           { }   # D
    location ~* \.(gif|jpg|jpeg)$  { }   # E
}

#   /                        -> A   exact match, search ends here
#   /index.html              -> B   no regex matched, longest prefix used
#   /documents/document.html -> C   longer prefix than B
#   /images/1.gif            -> D   ^~ won the prefix stage, regex skipped
#   /documents/1.jpg         -> E   regex beats the longer prefix C

# The last two lines are the whole lesson: identical-looking prefixes
# behave differently because only one of them carries ^~.

核心功能

回答这个问题的其他办法

nginx location 匹配示例

location /documents/  ·  location ~* \.(gif|jpg|jpeg)$  ·  GET /documents/1.jpg

~* \.(gif|jpg|jpeg)$ wins

location /uploads/  ·  location ~ \.php$ { fastcgi_pass ... }  ·  GET /uploads/evil.php

~ \.php$ wins — the upload lands in the interpreter

location ^~ /a/  ·  location /a/b/  ·  location ~ \.php$  ·  GET /a/b/x.php

~ \.php$ wins — the ^~ never applied

location /static  ·  location /static/  ·  GET /staticfoo

/static wins

location ~ ^/a  ·  location ~ ^/a/b/c$  ·  GET /a/b/c

~ ^/a wins; ~ ^/a/b/c$ is unreachable

location /a/  ·  location /b/  ·  GET /a/b%2F..%2Fzz

$uri becomes /a/zz, so /a/ wins

nginx location 测试器怎么用

1. 1

   粘贴 server 块

   整段 server 块可以，只放你正在琢磨的那几个 location 块也可以。嵌套 location 能被识别，原始行号会保留，表格和你的文件对得上。

2. 2

   填入请求 URI

   按它在链路上真实到达的样子输入路径，包括百分号编码和查询字符串。表格上方那三行会显示它在匹配前是怎么被规范化的。

3. 3

   先看胜出者，再看落败者

   结论卡片写出被选中的块和一行原因。下面的判定表解释其余每一个块：它在哪一步被淘汰，为什么。

4. 4

   看诊断提示

   未加锚点的正则、少了尾斜杠的前缀、写了正则模式的 ^~、不可达的重复项，以及能被 PHP 正则接管的上传目录，都会被报出来。

5. 5

   把当前状态分享出去

   复制链接会把配置和 URI 编码进 URL 片段，同事打开看到的就是你眼前这一份。片段永远不会传给服务器。

nginx location 常见错误

location ^~ /a/ { }
location /a/b/ { }
location ~ \.php$ { }
# /a/b/x.php -> ~ \.php$

location ^~ /a/ { }
location ^~ /a/b/ { }
location ~ \.php$ { }
# /a/b/x.php -> ^~ /a/b/

location /static { root /var/www; }
# also serves /staticfoo and /static-backup

location /static/ { root /var/www; }
location = /static { return 301 /static/; }

location ~ ^/api { }
location ~ ^/api/v2/users$ { }
# the second is unreachable

location ~ ^/api/v2/users$ { }
location ~ ^/api { }

location ^~ "\.php$" { deny all; }

location ~ \.php$ { deny all; }

location /search?q= { }
# never matches anything

location /search {
    if ($arg_q = "") { return 400; }
}

用 nginx location 测试器能做什么

配置上生产前先过一遍

对一份改完但还没部署的 server 块推演路由。它抓的是那种只在特定 URI 形状下才暴露的故障，而这恰恰是 reload 之后随手冒烟测试最容易漏掉的一类。

查清一条规则为什么不再生效

以前会跑、现在不跑的正则，几乎总是顺序的受害者：要么有更早的匹配了，要么它上面多了一个 ^~。表格会把这个块标为不可达，并指出是谁把请求接走的。

审计上传目录或媒体目录

载入复现「上传即执行」形状的预设，再把你自己的路径粘进去。如果一条 PHP 正则正在接管某个可写目录里的请求，诊断会指出来，并同时点名两个块。

用证据结束一条评审意见

复制链接会把确切的配置和 URI 存进 URL 片段。把它贴进 PR，就用一张谁都能重跑的判定表，取代一场关于优先级的争论。

讲清楚选择算法

两张参考表是静态的、可被抓取的材料，可以直接指过去；预设按钮不用弄坏一台服务器就能演示每个陷阱。尤其是 ^~ 那个例子，通常几句话就能结束争论。

nginx location 匹配规则：选择是怎么跑的

规范化发生在查找任何 location 之前

URI 先被百分号解码，. 和 .. 段被解析，重复斜杠被合并，然后才开始挑 location。解码出的 %2F 变成真正的分隔符并参与这一步解析，所以 /a/b%2F..%2Fzz 是按 /a/zz 匹配的。有三个解码字符是例外，会保持字面：%25、%23 和 %3F——这就是 /a%3Fx=1 路径里带问号、查询字符串却为空的原因。这里的 + 不是空格，只有 %20 才是。爬到根目录之上的穿越和非法转义，都会在匹配开始前被 400 拒掉。

决定胜负的是前缀长度，不是配置顺序

所有匹配的前缀 location 会被拿来比较，最长的胜出，无论它写在文件的最前面还是最后面。比较按字符进行，不按路径段，所以 /static 匹配 /staticfoo。胜出者只是被记住而不是立刻使用，因为正则阶段仍可能把它覆盖掉。

^~ 压制正则，不是提升优先级

这个修饰符只在已经按长度胜出的那个前缀上被检查。如果还有一个更长的普通前缀也匹配，被记住的就是它，正则阶段照常运行——那个 ^~ 块对这个请求毫无作用。把 ^~ 放在嵌套 location 上，挡不住在外层声明的正则；它也从不压制嵌套在自己块内部的正则。

正则按文件顺序跑，第一条匹配就结束查找

nginx 按写入顺序保存正则 location，不会排序。具体程度、长度和锚点都不影响谁先被尝试，所以一条精确模式如果写在宽泛模式下面，就是死配置。匹配到的正则 location 同样会被进入，其嵌套 location 随后被查找。

PCRE 和 ECMAScript 不是同一种语言

nginx 用 PCRE 编译 location 正则，不开 UTF 也不开多行模式，所以模式作用在字节上，^ 只锚定 URI 的开头。有一处差异带安全后果：PCRE 的 $ 也匹配紧邻结尾换行之前的位置，所以以 %0A 结尾的 URI 仍然满足 \.php$，尽管 JavaScript 引擎会拒绝。本页模拟并报告这个行为，因为它是绕过按扩展名设定的规则的已知手法。

nginx location 最佳实践

可写目录用 ^~ 保护，别用普通前缀

任何接受上传的目录都需要 location ^~ /uploads/，好让正则阶段没机会把存进去的文件交给解释器。普通前缀看起来等价，其实不是。

目录前缀带上尾斜杠

写 location /static/ 而不是 location /static，除非你就是想让 /staticfoo 和 /static-backup 也走同一个块。裸路径也需要处理时，另加一条 location = /static。

正则从最具体排到最宽泛

第一条匹配的胜出，所以把宽泛模式放在精确模式上面，会让精确的那条永远不可达。让正则数量少一点、顺序刻意一点，比事后推理重叠关系更好维护。

打算匹配路径前缀的正则要加锚点

location ~ /admin 会在 URI 的任意位置搜索，也会匹配 /public/admin/x。你要的是开头，就写 ~ ^/admin。只在结尾加锚点，对按扩展名路由来说是正常且正确的。

任何一次重排之后都重新检查路由

挪动块对前缀是安全的，对正则则会改变行为。既然一份只调换了行顺序的 diff 在评审里看着人畜无害，把受影响的 URI 重跑一遍就是最省事的兜底。

nginx location 测试器常见问题