Nginx location匹配顺序与优先级如何确定？

Question

常见技术问题： 为什么在Nginx配置中，明明写了 `location /api/` 和 `location ~ \.php$`，但访问 `/api/user.php` 时却命中了正则匹配而非前缀匹配，导致PHP脚本被错误代理或返回404？这是否违背“先到先得”原则？实际生产中，常因混淆location匹配的**严格优先级规则**（精确匹配 > 最长前缀匹配 > 正则匹配（按配置文件出现顺序）> 普通前缀兜底），导致路由行为与预期不符。例如，`location = /`、`location ^~ /static/` 与 `location ~* \.(js|css)$` 共存时，如何确保静态资源不被低优先级正则劫持？更棘手的是，当使用`alias`与`root`混搭、或嵌套`location`（如`location /app { location ~ \.php$ { ... } }`）时，匹配逻辑是否仍遵循全局顺序？理解Nginx不回溯、不继承、仅单次匹配的核心机制，是精准控制流量路由的关键前提。

Answer 1

```html

一、现象还原：为什么 /api/user.php 命中了 location ~ \.php$？

这是Nginx最典型的「认知陷阱」：开发者误以为“路径越长越优先”，或“先写的location先匹配”。但Nginx的匹配机制根本不是线性扫描——它将所有 location 分为三类，**严格分阶段决策**：

1. 阶段1（精确/前缀预筛）：收集所有前缀型 location（=、^~、普通前缀），找出最长匹配前缀；
2. 阶段2（正则决胜）：若存在 ^~ 且最长前缀匹配成功，则跳过所有正则；否则，按配置文件中出现顺序依次尝试正则，首个成功即终止；
3. 阶段3（兜底）：无正则命中时，采用阶段1选出的最长前缀匹配项。

因此，location /api/ 是普通前缀（最长前缀候选），而 location ~ \.php$ 是正则——当请求 /api/user.php 时，虽然 /api/ 是更长前缀，但因未加 ^~ 修饰，Nginx仍会进入阶段2并执行正则匹配。只要该正则在配置中出现在 /api/ 之后（或之前但未被跳过），就可能命中。

二、优先级真相：Nginx location 匹配的四层权威模型

优先级	语法示例	匹配逻辑	是否受顺序影响
① 最高（精确）	location = /	完全相等才匹配	否
② 次高（最长前缀+阻断）	location ^~ /static/	最长前缀匹配 → 立即终止，不查正则	否（仅比长度）
③ 中等（正则）	location ~* \.(js|css)$	按配置文本顺序逐条尝试，首个成功即用	是（关键！）
④ 最低（普通前缀）	location /api/	仅当无①②③命中时启用	否（仅比长度）

⚠️ 注意：^~ 不是“禁止正则”，而是“一旦此最长前缀匹配成功，立刻放弃所有正则检查”——这才是避免静态资源被 ~* \.php$ 劫持的核心手段。

三、嵌套 location 的本质：不存在“继承”，只有“重匹配”

Nginx 不支持嵌套 location 的作用域继承。以下配置是常见误解：

location /app {
    alias /var/www/app/;
    location ~ \.php$ {
        fastcgi_pass php-fpm;
    }
}

实际上，Nginx 解析时会将内层 location ~ \.php$ 提升至**全局 scope**，与外层平级。请求 /app/index.php 的匹配流程如下：

1. 先对完整 URI /app/index.php 执行全局 location 匹配；
2. 发现 location ~ \.php$ 正则匹配成功（因 URI 以 .php 结尾）；
3. 直接进入该块，完全忽略外层 /app 的 alias 或 root 设置；
4. 若该块内未定义 root 或 alias，则使用 server 级默认 root，导致文件路径错误（如访问 /var/www/html/index.php 而非 /var/www/app/index.php）。

四、实战解决方案矩阵

针对不同场景，提供可直接落地的加固模式：

• API + PHP 共存：用 ^~ 锁定 API 前缀，阻断正则干扰
  location ^~ /api/ { proxy_pass http://backend; }
location ~ \.php$ { fastcgi_pass php-fpm; }
• 静态资源防劫持：对静态目录强制 ^~，再在其下用正则细化处理
  location ^~ /static/ { alias /var/www/static/; }
location ~* ^/static/.*\.(js|css|png|jpg)$ { expires 1y; add_header Cache-Control "public"; }
• 安全兜底：末尾添加通用拒绝规则防止路径遍历
  location ~ /\. { deny all; }

五、可视化匹配决策流（Mermaid 流程图）

flowchart TD A[接收请求 URI] --> B{是否存在 = 匹配？} B -->|是| C[立即执行该 location 块] B -->|否| D[收集所有前缀 location
计算最长匹配] D --> E{最长匹配是否带 ^~？} E -->|是| F[执行该前缀块
STOP - 不查正则] E -->|否| G[按文本顺序遍历所有 ~ / ~*] G --> H{某正则匹配成功？} H -->|是| I[执行该正则块] H -->|否| J[执行最长前缀块]

该流程图揭示了 Nginx “单次、不可回溯、阶段化”的硬性约束——理解此图，等于掌握 80% 的 location 故障根因。

六、高级陷阱：alias 与 root 在正则 location 中的语义鸿沟

在正则 location 中混用 alias 极易出错：

location ~ ^/assets/(.+\.js)$ {
    alias /var/www/js/$1;   # ❌ 错误：$1 包含完整路径，alias 会拼接两次
}
location ~ ^/assets/(.+\.js)$ {
    root /var/www;          # ✅ 正确：root + URI 剩余部分 = 完整路径
    # /assets/foo.js → /var/www/assets/foo.js
}

alias 在正则中要求捕获组必须精确对应“替换后路径”，而 root 总是追加整个 URI。生产环境强烈建议：正则 location 统一用 root，前缀 location 再谨慎使用 alias。

```