Nginx 的 location 匹配

⚠️ 除非特殊说明，本文基于 Nginx Linux 环境。

匹配类型

Nginx server 配置块中可以根据不同的请求路径采取不同的处理方式，对请求路径的匹配有五种类型。语法如下：

server {
  location [ = | none | ^~ | ~ | ~* ] pattern { ... }
}

除此之外，还有一个特殊的命名匹配，语法如下：

server {
  location @name { ... }
}

特别注意：

• 路径匹配前会进行 URI 标准化：

  • 进行 URL 解码
  • 解析相对路径 . / ..
  • 压缩重复分隔符 /a///b/ -> /a/b

• 路径匹配忽略查询参数，即 ?xxx=xxx 的部分。

• 精准匹配与前缀匹配是否区分大小写取决于操作系统是否 case-insensitive.

精准匹配 - =

顾名思义，路径必须完全匹配才可以。

🌰 例子：

server {
  server_name chenhe.me;
  location = /admin { ... }
}

• https://chenhe.me/admin ✅
• https://chenhe.me/admin?lang=zh ✅ 忽略查询参数
• https://chenhe.me/Admin ❓ 取决于操作系统
• https://chenhe.me/ ❌ 路径为 /
• https://chenhe.me/admin/ ❌ 路径为 /admin/ 结尾多了一个斜杠。

前缀匹配 - none

none 就是什么都不写。

🌰 例子：

server {
  server_name chenhe.me;
  location ^~ /admin { ... }
  # OR
  location /admin { ... }
}

• https://chenhe.me/admin ✅
• https://chenhe.me/admin/ ✅
• https://chenhe.me/admin/A/B/C ✅
• https://chenhe.me/Admin/a/b/c ❓ 取决于操作系统
• https://chenhe.me/a/admin ❌

最长前缀匹配 - ^~

这个符号可以这么记忆：~ 是正则匹配，^ 在正则中意为「非」，所以非正则匹配就就是前缀匹配了。

^~ 和 none 的规则一样，其区别体现在匹配顺序上。前者匹配成功后立即停止，进入对应的配置块。后者则作为正则匹配的替补，如有正则匹配成功那么正则优先。

正则（区分大小写）- ~

注意，正则表达式是全局搜索的。

最强大的一个，正则支持的它就支持。什么？你不知道正则？这就是另一个大话题了...

🌰 例子：

server {
  server_name chenhe.me;
  location ~ '/img/\d{4}/' { ... }
}

1. 因为模式串中出现了大括号，所以用引号括起来。
2. \d{4} 是正则语法，表示匹配 4 个连续的数字。

• https://chenhe.me/img/2010/ ✅
• https://chenhe.me/a/B/img/2020/a.jpg ✅ 正则是全局搜索的
• https://chenhe.me/img/2010 ❌ 少一个斜杠
• https://chenhe.me/IMG/2010/ ❌ 区分大小写

我们发现，因为正则是全局搜索的，因此不要求必须是前缀匹配。那如果就是要求前缀呢？利用正则语法就行了，比如：

server {
  server_name chenhe.me;
  location ~ '^/img/\d{4}/' { ... }
}

^ 是正则元字符，表示字符串启始位置。

• https://chenhe.me/a/B/img/1111/ ❌

正则（忽略大小写）- ~*

和正则一样，只是不区分大小写了。

🌰 例子：

server {
  server_name chenhe.me;
  location ~* '^/img/\d{4}/' { ... }
}

• https://chenhe.me/IMG/2010/ ✅

命名匹配

命名匹配严格来说已经不能算是匹配了，因为它仅用于内部重定向，并不能直接匹配到任何客户端的请求。

🌰 例子：

location / {
    try_files $uri $uri/ @custom
}
location @custom {
    # do something
}

匹配顺序

优先级

基本匹配优先级如下：

= > ^~ > (~ = ~*) > none

总体上，匹配是从上到下进行的，若某个精准匹配 = 成功，则 立即停止匹配。因此对于访问量特别多的 URI 在配置文件开头进行精准匹配可以提高访问速度。

1. Nginx 首先尝试 所有 的前缀匹配（^~ / none），然后记忆最长的一个匹配结果。

   也就是说，所有的前缀匹配都会走一遍，无论是否成功。除非中间遇到成功的精准匹配而终止。同时也意味着前缀匹配编写的顺序不重要。

2. 若最长前缀匹配带有 ^~ 则停止匹配，并进入对应的配置块。
3. 否则继续 按照编写的顺序 匹配正则。在首次匹配成功时终止，并进入对应的配置块。
4. 若没有成功匹配的正则，则使用前面记忆的最长前缀匹配。

这时候也许有聪明的同学开始杠了，如果有两个一样长的前缀，一个是 ^~ 一个是 none，那怎么算？还要不要进行正则？比如：

location /user/ { }
location ^~ /user/ { [A] }
location ~ /user/\d+/ { [B] }
# 访问 /user/123/ 是进入 A 呢还是 B 呢？

答：不用担心。这种配置会直接报错：

nginx: [emerg] duplicate location ... in ...

最佳实践

总结以上，我们可以得出匹配编写的最佳实践：

• 精准匹配总是写在最前面，这样可以避免无意义的其他匹配。
• 前缀匹配写在一起，因为它们总是全部执行。并且按长度排列。
• 正则按照优先级排列。

这样文件里的顺序和实际顺序基本上是一致的，只需考虑一种情况：最长匹配为 none，此时正则优先适用。

关于结尾斜杠 /

结尾的斜杠分为两种情况：根目录和子目录。

根目录

根目录必须携带斜线。可以试试看浏览器中打开开发者工具，访问 https://chenhe.me，实际发出的请求是 https://chenhe.me/ 斜杠自动补全了（尽管地址栏上不显示）。这一操作是客户端默认执行的，不需要服务器 30x 跳转。

子目录

子目录下，带或不带斜杠是两种完全不同语义。/img 意为请求根目录下文件名为 img 的 文件，而 /img/ 意思为请求根目录下名称为 img 的 文件夹。「请求文件夹」这一操作具体行为视服务器设置而定，常见的默认设置是寻找目录下 index.html / index.php / ... 文件，也可配置为列出目录下的所有文件。

请求文件夹时，对于一个典型配置的服务器，处理流程如下：

1. 判断此文件夹是否存在，不存在返回 404
2. 判断此文件夹下是否有默认文件，例如 index.html 若有则返回。
3. 否则返回 404。

而请求文件，则更直接了当：

1. 判断文件是否存在，存在则返回。
2. 否则返回 404。

🌰 例子：

网站根目录结构如下：

webroot
+-- index.html
+-- user # 这是一个文件
+-- user
|   +-- index.html
+-- admin # 一个空文件夹
    +-- .

• /user 返回 user 文件
• /user/ 返回 user/index.html
• /admin 404 （文件不存在）
• /admin/ 404 （目录下没有默认文件）(假设不允许 list files)

特殊情况

这是子目录下的特殊情况，也是让很多人误以为结尾带不带斜杠没有区别的原因。

如果请求被执行下面任意一个操作：

• proxy_pass
• fastcgi_pass
• uwsgi_pass
• scgi_pass
• memcached_pass
• grpc_pass

如果此时请求路径不包含结尾斜杠，那么服务器将直接返回 301 永久重定向，跳转到带斜杠的路径：/user -301--> /user/

除非使用 location 单独匹配：

location /user/ {
    proxy_pass http://user.example.com;
}
location = /user {
    proxy_pass http://login.example.com;
}

参考

• Nginx docs - http - location
• 一文弄懂 Nginx 的 location 匹配
• 彻底弄懂 Nginx location 匹配