【原理揭秘】Nginx 匹配规则优先级详解

【原理揭秘】Nginx 匹配规则优先级详解

Nginx 的匹配机制看似简单，其实暗藏层层优先级：从 =、^~、~ 到普通前缀，谁先谁后？什么时候停止匹配？哪些规则会被跳过？本文带你彻底搞清楚。

🚀 一、四类匹配规则概览

💡 二、四种匹配详解

2.1 精确匹配（=）

location = /index.html {
    root /usr/share/nginx/html;
}

只匹配完全相同路径，如 /index.html。常用于首页、健康检查。

2.2 前缀优先（^~）

location ^~ /static/ {
    root /var/www;
}

匹配 /static/ 开头的请求后，将不再进入正则阶段。常用于静态目录。

2.3 正则匹配（~ / ~*）

location ~* \.(jpg|png)$ {
    root /data;
}

正则按书写顺序匹配，命中即停止。区分大小写与否由 ~ 或 ~* 决定。

2.4 普通前缀匹配

location /api/ { ... }
location /api/v1/ { ... }

在多个匹配中选择“最长前缀”，常用于接口路径。

三、匹配流程图

┌───────────────┐
│ 1️⃣ 精确匹配 (=) │→ 命中即返回
├───────────────┤
│ 2️⃣ 前缀优先 (^~) │→ 命中则跳过正则
├───────────────┤
│ 3️⃣ 正则 (~ / ~*) │→ 按定义顺序匹配
├───────────────┤
│ 4️⃣ 普通前缀匹配 │→ 选最长前缀
└───────────────┘

🧩 四、常见坑点

🧱 五、总结

• =：唯一、最高优先级。
• ^~：静态目录首选，跳过正则。
• ~ / ~*：复杂匹配，按顺序。
• 普通前缀：默认兜底，取最长匹配。

👉 下一篇：《location /js 404？root 拼接才是罪魁祸首！》将带你看最常见的路径拼接坑。

【踩坑实录】location /js 404？root 拼接才是罪魁祸首！

明明文件存在 /usr/local/www/html/js/cc.js，访问 /js/cc.js 却报 404？
原因就在于一个不起眼的“斜杠”。

一、问题重现

location /js {
    root /usr/local/www/html;
}

访问 /js/cc.js → 404。文件确实存在、权限正确。问题出在哪？

二、根因分析：root 拼接机制

Nginx 直接拼接 root 与请求路径：

三、正确写法

四、最佳实践

静态资源加 /，接口转发不加 /，文件匹配用 =。

【细节探秘】/js 与 /jsai 谁赢？Nginx 普通前缀匹配边界分析

当 /js 和 /jsai 并存时，访问 /js 命中谁？是按书写顺序，还是按长度？

一、规则配置

location /js {
    return 200 "JS";
}
location /jsai {
    return 200 "JSAI";
}

请求 /js → 命中 /js。请求 /jsai → 命中 /jsai。

二、匹配原理

普通前缀匹配使用 最长前缀优先 原则：

1. 收集所有能匹配请求路径的前缀。
2. 从中选择匹配长度最长的那个。

/jsai 不会匹配 /js 请求，因为 /js 不是以 /jsai 开头。

三、拓展示例

四、尾斜杠的作用

建议在相似路径时明确区分：

location /js/ { ... }
location /jsai/ { ... }

这样能避免 /jsai 被 /js 模糊命中。

五、对比总结

✅ 一句话总结：“长度优先：普通前缀/^~；顺序优先：正则；唯一匹配：=”

如果这套系列帮你理清了思路，点赞 + 收藏 + 关注 🔥。