彻底掌握 Nginx location 匹配规则 – wiki基地

作者： /

彻底掌握 Nginx location 匹配规则

Nginx 作为高性能的 Web 服务器和反向代理，其核心功能之一就是根据用户请求的 URI (Uniform Resource Identifier) 来确定如何处理该请求。实现这一路由功能的关键指令就是 location。然而，Nginx location 的匹配规则并非简单地按照在配置文件中出现的顺序来判断，它有一套优先级和匹配算法。只有彻底理解并掌握这套规则，才能高效、准确地配置 Nginx，避免出现意想不到的路由错误（例如 404 错误、请求被错误处理等）。

本文将深入剖析 Nginx location 的各种匹配方式及其背后的匹配算法，并通过丰富的示例来帮助读者彻底掌握这一核心概念。

一、理解 location 指令

location 指令主要存在于 http 块或 server 块中，用于根据请求的 URI 来定义特定的配置块。一个 server 块中可以包含多个 location 块，每个块处理匹配特定 URI 的请求。

location 指令的基本语法是：

nginx
location [modifier] uri {
...
}

其中：

  • modifier：用于改变 location 匹配行为的修饰符。这是理解 location 匹配规则的关键。
  • uri：用于与请求 URI 进行匹配的模式。它可以是前缀字符串，也可以是正则表达式。
  • { ... }：匹配成功后要应用的配置指令块，例如设置根目录 (root)、索引文件 (index)、代理目标 (proxy_pass)、重定向 (return) 等。

没有修饰符时，uri 被视为前缀匹配。而不同的修饰符则赋予了 uri 不同的匹配含义和优先级。

二、location 的匹配类型与修饰符

Nginx location 匹配主要分为两大类：前缀匹配 和 正则匹配。每类又有不同的修饰符，影响其优先级和匹配方式。

1. 前缀匹配 (Prefix Matching)

前缀匹配是指判断请求的 URI 是否以指定的 uri 字符串开头。

  • 无修饰符 (No Modifier): location /prefix/ { ... }

    • 含义: 对请求 URI 进行前缀匹配。如果请求 URI 以 /prefix/ 开头，则匹配成功。
    • 特点: 这种匹配方式会优先查找所有前缀匹配中最长的匹配项。但是，找到最长匹配项后并不会立即停止搜索，它会继续检查是否存在正则表达式匹配。如果存在正则匹配且匹配成功，正则匹配的优先级更高；如果不存在正则匹配或正则匹配失败，则最终选用之前找到的最长前缀匹配项。
    • 示例:
      nginx
      location /static/ {
      # 处理 /static/ 下的静态文件
      }
      location /images/ {
      # 处理 /images/ 下的图片
      }

      • 请求 /static/css/style.css 会匹配 /static/。
      • 请求 /images/logo.png 会匹配 /images/。
      • 请求 /about.html 不会匹配上述两者。

  • = 修饰符 (Exact Match): location = /exact/uri { ... }

    • 含义: 对请求 URI 进行精确匹配。只有当请求 URI 完全等于指定的 /exact/uri 时才匹配成功。
    • 特点: 这是所有匹配类型中优先级最高的。如果找到精确匹配，则立即停止搜索，并使用该 location 块的配置。这对于那些需要精确控制的特定 URI 非常有用，例如网站首页 / 或登录页 /login。
    • 示例:
      nginx
      location = / {
      # 精确匹配网站首页 /
      index index.html;
      }
      location = /login {
      # 精确匹配登录页面 /login
      proxy_pass http://auth_service;
      }

      • 请求 / 会精确匹配第一个 location。
      • 请求 /login 会精确匹配第二个 location。
      • 请求 /index.html 不会匹配第一个 location。

  • ^~ 修饰符 (Preferred Prefix Match): location ^~ /prefix/ { ... }

    • 含义: 对请求 URI 进行前缀匹配。如果请求 URI 以 /prefix/ 开头，则匹配成功。
    • 特点: 这是介于无修饰符前缀匹配和正则匹配之间的一种特殊前缀匹配。它的优先级高于正则匹配。如果找到了一个 ^~ 开头的 location 块，并且它是所有匹配到的前缀中最长的那个（或者虽然不是最长，但它是带有 ^~ 修饰符中匹配到的最长的那个，且其优先级在算法中被优先处理，注：官方文档强调 longest matching prefix if it is a ^~ location is preferred over regex），Nginx 会立即停止搜索，并使用该 ^~ 块的配置，不再继续匹配正则表达式。这使得 ^~ 非常适合用于定义不希望被后续正则匹配覆盖的特定路径，例如静态文件目录。
    • 示例:
      nginx
      location ^~ /static/ {
      # 处理 /static/ 下的静态文件，不希望被后面的正则匹配干扰
      root /data/www/static;
      }
      location ~ \.(jpg|png|gif)$ {
      # 匹配所有 .jpg, .png, .gif 文件 (可能会被 ^~ /static/ 阻止)
      expires 30d;
      }

      • 请求 /static/images/logo.png 会匹配 ^~ /static/ 并停止搜索，即使它也匹配了 ~ \.(jpg|png|gif)$。Nginx 会使用 ^~ /static/ 块的配置。
      • 请求 /images/header.jpg 不匹配 ^~ /static/，会继续检查正则匹配，匹配到 ~ \.(jpg|png|gif)$。Nginx 会使用该正则块的配置。

2. 正则表达式匹配 (Regular Expression Matching)

正则表达式匹配允许使用更灵活的模式来匹配 URI。

  • ~ 修饰符 (Case-sensitive Regex): location ~ pattern { ... }

    • 含义: 对请求 URI 进行区分大小写的正则表达式匹配。
    • 特点: Nginx 会按照配置文件中 ~ 和 ~* location 块出现的顺序进行匹配。一旦找到第一个匹配成功的正则块，就会停止搜索，并使用该块的配置。
    • 示例:
      nginx
      location ~ \.(php|html)$ {
      # 区分大小写匹配 .php 或 .html 结尾的 URI
      fastcgi_pass ...;
      }
      location ~ ^/user/[0-9]+$ {
      # 匹配以 /user/ 开头，后面跟着一个或多个数字的 URI
      proxy_pass ...;
      }

      • 请求 /index.html 匹配第一个 location。
      • 请求 /Index.HTML 不匹配第一个 location。
      • 请求 /user/123 匹配第二个 location。

  • ~* 修饰符 (Case-insensitive Regex): location ~* pattern { ... }

    • 含义: 对请求 URI 进行不区分大小写的正则表达式匹配。
    • 特点: 与 ~ 类似，也是按照配置文件中出现的顺序匹配，找到第一个成功匹配的就停止。
    • 示例:
      nginx
      location ~* \.(jpg|png|gif|bmp)$ {
      # 不区分大小写匹配图片文件
      expires 30d;
      add_header Cache-Control "public";
      }

      • 请求 /images/logo.JPG 会匹配。
      • 请求 /images/PHOTO.png 也会匹配。

3. 通用匹配 (General Match)

  • / 修饰符 (Catch-all): location / { ... }
    • 含义: 匹配所有 URI。
    • 特点: 这是优先级最低的匹配项。它会捕获所有未能被更具体、更高优先级（例如精确匹配、^~ 匹配、正则匹配）的 location 规则匹配到的请求。通常用于设置网站的默认行为，例如指定网站根目录、默认首页文件等。
    • 示例:
      nginx
      location / {
      # 网站的默认处理
      root /usr/share/nginx/html;
      index index.html index.htm;
      }

      • 所有不匹配其他 location 块的请求都会由这个块处理。

三、location 匹配算法详解

理解了各种匹配类型的含义和特点后，最关键的是理解 Nginx 如何在有多个 location 块时，决定使用哪一个来处理特定的请求 URI。Nginx 遵循一套明确的多阶段匹配算法。

Nginx 的 location 匹配算法步骤如下：

  1. 处理精确匹配 (=):

    • 首先，Nginx 会检查所有带有 = 修饰符的 location 块。
    • 如果找到了一个与请求 URI 完全相等的 location = uri 块，则立即停止搜索，并使用该块的配置。

  2. 处理带有 ^~ 修饰符的前缀匹配:

    • 如果第 1 步没有找到精确匹配，Nginx 会接着查找所有带有 ^~ 修饰符的 location 块。
    • 在所有匹配到的 ^~ 块中，Nginx 会选择最长匹配的那个。
    • 如果找到了一个匹配的 ^~ 块（即使它不是所有前缀中最长的，但因为其 ^~ 修饰符的特性，它被优先考虑），Nginx 会停止搜索（不再检查正则匹配），并使用该 ^~ 块的配置。

  3. 处理无修饰符的前缀匹配:

    • 如果第 1 步和第 2 步都没有停止搜索，Nginx 会检查所有没有修饰符的 location 块。
    • Nginx 会在这些无修饰符的前缀匹配项中找到与请求 URI 最长匹配的那个块。
    • Nginx 会记住这个最长匹配的无修饰符前缀块，但不会立即停止搜索，而是继续进行下一步的正则匹配。

  4. 处理正则表达式匹配 (~ 和 ~*):

    • 如果第 1 步和第 2 步都没有停止搜索，Nginx 会按照配置文件中出现的顺序，依次检查所有带有 ~ 或 ~* 修饰符的 location 块。
    • 一旦找到第一个匹配成功的正则表达式块，Nginx 会停止搜索，并使用该正则块的配置。此时，在第 3 步中记住的最长无修饰符前缀匹配块将被丢弃。

  5. 使用记住的最长无修饰符前缀匹配 (如果未被正则覆盖):

    • 如果经过第 4 步检查后，没有找到任何匹配成功的正则表达式块，Nginx 才会回过头来，使用在第 3 步中记住的那个最长匹配的无修饰符前缀块的配置。

  6. 使用通用 / 匹配:

    • 如果以上所有步骤都没有找到匹配的 location 块（这通常发生在第 3 步和第 4 步都没有匹配，或者根本没有无修饰符和正则的 location 块时），则最终会使用 location / { ... } 块的配置。这个块总是会匹配任何 URI，作为最终的 fallback。

简化的优先级总结（从高到低，遇到能立即停止搜索的则停止）：

  1. = 精确匹配 (Exact) – 匹配到即停止。
  2. ^~ 特殊前缀匹配 (Preferred Prefix) – 匹配到最长者即停止（相对于正则）。
  3. ~ 和 ~* 正则表达式匹配 (Regex) – 按顺序匹配，第一个匹配到即停止（如果第 2 步未停止）。
  4. 无修饰符前缀匹配 (Prefix) – 找到最长者，但如果正则匹配失败才会最终使用。
  5. / 通用匹配 (Catch-all) – 优先级最低，用于处理所有未被其他规则匹配的请求。

四、通过示例理解匹配算法

理论结合实践是掌握知识的最佳方式。下面通过几个具体的示例来演示 location 匹配算法的工作过程。

示例 1: 静态文件与动态请求

“`nginx
server {
listen 80;
server_name example.com;

# Rule 1: 精确匹配首页
location = / {
    index index.html;
}

# Rule 2: 优先处理 /static/ 下的文件，不进行正则检查
location ^~ /static/ {
    alias /data/static/;
    expires 30d;
}

# Rule 3: 处理所有 .php 文件 (正则匹配)
location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

# Rule 4: 处理所有 .jpg 或 .png 文件 (正则匹配，不区分大小写)
location ~* \.(jpg|png)$ {
    expires 7d;
    add_header Cache-Control "public";
}

# Rule 5: 所有其他请求 (通用匹配)
location / {
    proxy_pass http://backend_server;
}

}
“`

让我们分析几个请求 URI 会被哪个 location 块处理：

  1. 请求: /

    • Step 1: 检查 =。匹配 location = /。
    • 结果: 使用 Rule 1。Nginx 停止搜索。

  2. 请求: /static/css/style.css

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。匹配 location ^~ /static/。这是唯一的 ^~ 匹配。
    • 结果: 使用 Rule 2。Nginx 停止搜索。即使 /static/css/style.css 也包含 .css，但 Rule 2 阻止了正则匹配的进行。

  3. 请求: /images/logo.png

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。不匹配 /static/。
    • Step 3: 检查无修饰符前缀。没有无修饰符的前缀 location (除了 Rule 5 的 /)。记住 Rule 5 location / 作为最长前缀（实际上是唯一的）。
    • Step 4: 检查正则匹配 (~ 和 ~*)。
      • location ~ \.php$ (Rule 3) 不匹配。
      • location ~* \.(jpg|png)$ (Rule 4) 匹配 /images/logo.png。
    • 结果: 使用 Rule 4。Nginx 找到正则匹配并停止搜索，忽略了 Rule 5 的无修饰符前缀匹配。

  4. 请求: /index.php

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。不匹配 /static/。
    • Step 3: 检查无修饰符前缀。记住 Rule 5 location / 作为最长前缀。
    • Step 4: 检查正则匹配 (~ 和 ~*)。
      • location ~ \.php$ (Rule 3) 匹配 /index.php。
    • 结果: 使用 Rule 3。Nginx 找到正则匹配并停止搜索，忽略了 Rule 5 的无修饰符前缀匹配。

  5. 请求: /about

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。不匹配 /static/。
    • Step 3: 检查无修饰符前缀。记住 Rule 5 location / 作为最长前缀。
    • Step 4: 检查正则匹配 (~ 和 ~*)。Rule 3 和 Rule 4 都不匹配 /about。
    • Step 5: 没有找到正则匹配。使用 Step 3 记住的最长无修饰符前缀匹配。
    • 结果: 使用 Rule 5。

示例 2: 多个前缀匹配和正则匹配的混合

“`nginx
server {
listen 80;
server_name test.com;

# Rule 1: 精确匹配 /test/
location = /test/ {
    return 200 "Exact match for /test/";
}

# Rule 2: 无修饰符前缀匹配 /test/
location /test/ {
    return 200 "Prefix match for /test/";
}

# Rule 3: 无修饰符前缀匹配 /test/abc/
location /test/abc/ {
    return 200 "Prefix match for /test/abc/";
}

# Rule 4: 正则匹配包含 test 的路径
location ~ /.*test.* {
    return 200 "Regex match containing test";
}

# Rule 5: 所有其他请求 (通用匹配)
location / {
    return 200 "General match /";
}

}
“`

分析请求 URI：

  1. 请求: /test/

    • Step 1: 检查 =。匹配 location = /test/ (Rule 1)。
    • 结果: 使用 Rule 1。Nginx 停止搜索。

  2. 请求: /test/page.html

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。没有 ^~ location。
    • Step 3: 检查无修饰符前缀。
      • location /test/ (Rule 2) 匹配。
      • location /test/abc/ (Rule 3) 不匹配。
      • location / (Rule 5) 匹配。
      • 最长前缀匹配是 location /test/ (Rule 2)。记住 Rule 2。
    • Step 4: 检查正则匹配 (~ 和 ~*)。
      • location ~ /.*test.* (Rule 4) 匹配 /test/page.html。
    • 结果: 使用 Rule 4。Nginx 找到正则匹配并停止搜索，忽略了 Rule 2。

  3. 请求: /test/abc/def.html

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。没有 ^~ location。
    • Step 3: 检查无修饰符前缀。
      • location /test/ (Rule 2) 匹配。
      • location /test/abc/ (Rule 3) 匹配。
      • location / (Rule 5) 匹配。
      • 最长前缀匹配是 location /test/abc/ (Rule 3)。记住 Rule 3。
    • Step 4: 检查正则匹配 (~ 和 ~*)。
      • location ~ /.*test.* (Rule 4) 匹配 /test/abc/def.html。
    • 结果: 使用 Rule 4。Nginx 找到正则匹配并停止搜索，忽略了 Rule 3。

  4. 请求: /about/page

    • Step 1: 检查 =。不匹配。
    • Step 2: 检查 ^~。没有 ^~ location.
    • Step 3: 检查无修饰符前缀。只有 location / (Rule 5) 匹配。记住 Rule 5。
    • Step 4: 检查正则匹配 (~ 和 ~*)。location ~ /.*test.* (Rule 4) 不匹配 /about/page。
    • Step 5: 没有找到正则匹配。使用 Step 3 记住的最长无修饰符前缀匹配。
    • 结果: 使用 Rule 5。

这些示例清楚地展示了 Nginx 如何权衡不同类型的 location 匹配，以及 ^~ 和正则匹配如何影响最终的选择。特别要注意无修饰符前缀匹配虽然会找到最长匹配，但其最终使用优先级低于正则匹配（除非没有正则匹配成功）。

五、常见陷阱与最佳实践

掌握了匹配规则，还需要注意一些常见的陷阱，并遵循一些最佳实践来编写清晰、高效的 Nginx 配置。

常见陷阱：

  1. 混淆匹配顺序: 最常见的错误是想当然地认为 Nginx 会按照配置文件中 location 块的顺序从上到下依次匹配并停止。这与 Nginx 的实际算法（特别是正则匹配）是相悖的。
  2. 过度依赖正则匹配: 正则表达式虽然灵活，但匹配过程相对耗时。而且如果多个正则匹配都能命中同一个 URI，只有第一个会生效，这可能导致配置难以理解和维护。对于可以通过前缀匹配解决的场景，优先使用前缀匹配（尤其是 ^~）。
  3. 忽略 / 的作用: location / 是兜底规则，非常重要。没有它，不匹配其他规则的请求将无法处理（可能导致 404）。同时，也要清楚它是优先级最低的，不会干扰更具体的规则。
  4. ^~ 的误解: 认为 ^~ 会匹配所有前缀中最长的。实际上，^~ 的作用是如果它匹配成功，就优先于 所有 正则表达式匹配，并立即停止搜索。无修饰符的前缀匹配才需要找到所有匹配项中最长的那个。

最佳实践：

  1. 优先使用精确匹配 (=): 对于固定的、少数的特定 URI (如 /, /login, /favicon.ico 等)，使用 = 可以提高效率并确保这些请求被精确处理。
  2. 利用 ^~ 阻止不必要的正则匹配: 对于静态文件目录 (/static/, /images/ 等)，使用 location ^~ /path/ 是非常好的做法。这能确保这些静态资源的请求不会继续进行正则匹配，提高了处理速度，也避免了复杂的正则规则可能意外地匹配到静态文件。
  3. 组织好正则匹配: 如果必须使用正则匹配，尽量将相关的正则规则放在一起，并考虑它们的顺序。记住 Nginx 会使用第一个匹配成功的正则规则。
  4. 使用注释: 在复杂的 location 配置中，添加注释解释每个块的目的和预期的匹配 URI，可以极大地提高配置的可读性和可维护性。
  5. 使用 nginx -t 测试配置: 在重载或重启 Nginx 服务之前，务必使用 sudo nginx -t 命令来检查配置文件的语法是否正确，以及是否有潜在的逻辑错误提示。虽然它不能检测出所有逻辑问题，但能发现大部分语法错误。
  6. 简洁性: 尽量保持 location 块及其内部配置的简洁性。如果一个 location 块变得过于复杂，考虑是否可以拆分或使用更简洁的逻辑。
  7. 理解 root 和 alias 的区别: 在 location 块中指定文件路径时，root 会将 root 指定的路径与 location 匹配到的 URI 的剩余部分拼接；而 alias 会将 alias 指定的路径替换掉 location 匹配到的 URI 部分。理解它们的区别是正确配置静态文件和路径别名的关键。例如：
    nginx
    # 请求 /static/css/style.css
    location /static/ {
    root /data/www/; # 实际访问路径: /data/www/static/css/style.css
    }
    location /static/ {
    alias /data/www/static/; # 实际访问路径: /data/www/static/css/style.css (这里uri的/static/被替换了)
    }
    # 请求 /files/mydoc.pdf
    location /files/ {
    alias /var/docs/; # 实际访问路径: /var/docs/mydoc.pdf
    }
    # 如果这里用 root，实际路径会是 /var/docs/files/mydoc.pdf，可能导致文件找不到
    在使用 alias 时，location 的 URI 必须以 / 结尾，alias 的路径也最好以 / 结尾。

六、总结

Nginx 的 location 匹配规则是其灵活性的基石，但也因为其多阶段的匹配算法而显得有些复杂。核心在于理解不同修饰符 (=, ^~, ~, ~*, 无修饰符, /) 所代表的匹配类型和优先级，以及 Nginx 如何在这些规则之间进行选择。

通过本文的详细解析，特别是对匹配算法步骤和示例的深入理解，相信读者已经能够彻底掌握 Nginx 的 location 匹配规则。在实际配置中，多加练习，结合 nginx -t 和对日志的观察，将能更 confidently 地构建出高效、正确的 Nginx 路由配置。记住，清晰、有条理的配置不仅能减少错误，也使得后续的维护工作变得更加容易。

现在，你可以满怀信心地去配置你的 Nginx 服务器了！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部