文章

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)

特殊情况

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

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

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

除非使用 location 单独匹配:

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

参考