Nginx 的强大，很大程度上源于其灵活且高效的路由匹配机制。而这一切的核心，都指向一个配置指令：location。可以说，掌握了 location，你就掌握了 Nginx 的半壁江山。无论是提供静态文件、做反向代理，还是配置复杂的 API 网关，都离不开对 location 的精准运用。

这篇文章，我将带你彻底搞懂 location 的工作原理，从它的匹配规则、修饰符差异，到 root 与 alias 的经典对比，再到 proxy_pass 的常见陷阱，让你在配置 Nginx 时不再迷茫。

Location 语法与修饰符

location 的基本语法很简单：location [modifier] [URI] { ... }。其中的 modifier（修饰符）是可选的，但它直接决定了 Nginx 的匹配行为。

Nginx 如何选择 Location：匹配算法揭秘

当一个请求进来时，Nginx 并不是简单地找到第一个匹配的 location 就完事了。它有一套明确的优先级算法，理解这个算法至关重要，否则你的路由可能会完全偏离预期。

Nginx 的匹配过程可以分为以下几步：

1. 精确匹配 (=) 优先：Nginx 首先查找所有使用 = 修饰符的 location。如果请求的 URI 与某个精确匹配的 location 完全一致，Nginx 会立即选择这个块，并停止所有后续的搜索。这是最高优先级的匹配。

2. 最长前缀匹配 (^~ 和无修饰符)：如果第一步没有找到精确匹配，Nginx 会开始查找所有前缀匹配的 location（即使用 ^~ 和无修饰符的）。在所有匹配的前缀中，Nginx 会记住最长的那一个。

   • 如果这个最长的前缀匹配使用了 ^~ 修饰符，那么 Nginx 会立即选择这个块，并且不再进行后续的正则匹配。
   • 如果这个最长的前缀匹配没有使用 ^~，Nginx 仅仅是暂时记住它，然后进入下一步。

3. 正则表达式匹配 (~ 和 ~*)：接下来，Nginx 会按照配置文件中出现的顺序，从上到下检查所有的正则表达式 location。一旦找到第一个匹配的正则表达式，Nginx 就会选择这个块，并停止搜索。

4. 最终选择：

   • 如果在第 3 步中找到了匹配的正则表达式，Nginx 就使用这个正则 location。
   • 如果没有任何正则表达式匹配成功，Nginx 就会回头使用在第 2 步中记住的那个最长前缀匹配。

举个例子，假设有以下配置：

server {
    listen 80;
    server_name example.com;

    location = /api {
        return 200 "Exact match: /api";
    }

    location ^~ /api/users {
        return 200 "Prefix stop: /api/users";
    }

    location ~ /api/v\d+ {
        return 200 "Regex match: /api/v[digit]";
    }

    location /api/ {
        return 200 "Prefix match: /api/";
    }
}

我们来看几个请求会匹配到哪里：

• GET /api -> Exact match: /api (精确匹配优先级最高)
• GET /api/users/123 -> Prefix stop: /api/users (/api/users 是最长前缀，且有 ^~，直接锁定，不再看正则)
• GET /api/v1/data -> Regex match: /api/v[digit] (最长前缀是 /api/，但没有 ^~，所以继续往下找正则，成功匹配)
• GET /api/other -> Prefix match: /api/ (没有精确匹配，最长前缀是 /api/，没有正则匹配，最终使用此前缀)

核心应用场景

静态文件服务：root vs alias 的较量

root 和 alias 是指定静态文件路径的两个常用指令，但它们的行为差异巨大，是新手最容易混淆的地方。

• root: 将 location 的 URI 追加到 root 指定的路径后。
• alias: 用 alias 指定的路径 替换 location 的 URI。

来看一个对比：

# 使用 root
location /static/ {
    root /var/www/data;
    # 请求 /static/image.png
    # Nginx 寻找的文件路径是: /var/www/data/static/image.png
}

# 使用 alias
location /static/ {
    alias /var/www/assets/;
    # 请求 /static/image.png
    # Nginx 寻找的文件路径是: /var/www/assets/image.png
}

关键陷阱：使用 alias 时，如果 location 的路径以 / 结尾，那么 alias 的路径也必须以 / 结尾。否则，路径拼接会出错。如果你不注意，这亇问题可能会浪费你几个小时。

反向代理核心：proxy_pass 的正确姿势

proxy_pass 用于将请求转发给后端的应用服务器。这里同样存在一个关于末尾斜杠 / 的经典问题，它直接影响转发给后端的 URI。

• proxy_pass 目标地址不带 /：Nginx 会将完整的原始 URI ($request_uri) 转发给后端。
• proxy_pass 目标地址带 /：Nginx 会将 location 匹配后的那部分 URI 去掉，再转发。

# 场景一：proxy_pass 不带 /
location /api/v1/ {
    proxy_pass http://127.0.0.1:8000;
    # 请求 /api/v1/users 会被转发到 http://127.0.0.1:8000/api/v1/users
}

# 场景二：proxy_pass 带 /
location /api/v1/ {
    proxy_pass http://127.0.0.1:8000/;
    # 请求 /api/v1/users 会被转发到 http://127.0.0.1:8000/users
}

这个细节非常重要，你需要根据后端服务的路由设计来决定是否加这个 /。

单页应用（SPA）路由救星：try_files

对于像 Vue 或 React 这样的单页应用，前端路由是在浏览器端处理的。当用户直接访问一个深层链接（如 example.com/dashboard/settings）并刷新时，Nginx 默认会去服务器上找这个文件，结果自然是 404。

try_files 就是为了解决这个问题。

location / {
    root /var/www/html;
    index index.html;
    try_files $uri $uri/ /index.html;
}

这行配置的意思是：

1. 首先尝试按请求的 $uri 寻找文件（如 /dashboard/settings）。
2. 如果找不到，尝试把它当成目录寻找（如 /dashboard/settings/）。
3. 如果还找不到，就内部重定向到 /index.html，把路由控制权交还给前端框架。

常见陷阱与排错技巧

陷阱 1：贪婪的正则表达式

一个不够精确的正则表达式可能会匹配到你不希望它匹配的请求。

# 错误的配置
location ~ /api { # 意图匹配 /api/ 开头的路径
    # ...
}
# 这个正则不仅会匹配 /api/users，还会匹配 /some-other/api 或 /api-backup

修正：使用锚点 ^ 来确保从 URI 的开头进行匹配。

# 正确的配置
location ~ ^/api/ {
    # ...
}

# 更好的选择：如果不需要正则，用优先前缀匹配，性能更好
location ^~ /api/ {
    # ...
}

排错技巧：如何确定哪个 Location 生效了？

当你有多个 location 块，又不确定某个请求到底匹配了哪一个时，有个非常好用的调试技巧：使用 add_header。

临时给每个 location 块加上一个自定义的 HTTP 响应头：

location ^~ /api/users {
    add_header X-Location-Matched "Prefix Stop: /api/users" always;
    # ... 其他配置
}

location ~ /api/v\d+ {
    add_header X-Location-Matched "Regex: /api/v[digit]" always;
    # ... 其他配置
}

然后用 curl -I http://example.com/api/users/123 发送请求，查看响应头中的 X-Location-Matched 字段，就能一目了然地知道是哪个 location 处理了这个请求。调试完记得删除这些 add_header 指令。在次检查你的配置是否正确。

性能优化建议

1. 优先使用前缀匹配：= 和 ^~ 的匹配效率远高于正则表达式。在能用前缀匹配解决问题的情况下，尽量避免使用正则。
2. 合理安排正则顺序：如果必须使用多个正则表达式 location，把最常用、最可能匹配到的放在前面，因为 Nginx 是按顺序检查的。
3. 减少不必要的正则：对于静态文件，比如图片、CSS、JS，使用 ^~ 来匹配目录通常比用正则匹配文件后缀（如 ~\.(jpg|png)$）更高效。

掌握 location 是精通 Nginx 的必经之路。希望这篇文章能帮你理清思路，写出更健壮、更高效的 Nginx 配置。

关于

关注我获取更多资讯

📢 公众号

💬 个人号