Nginx location 为什么配了不生效:匹配优先级、try_files 交接与 add_header 整组覆盖

为什么"明明写了配置却不生效"总是发生在 location 上

Nginx 的配置里,报错最少但行为最难猜的就是 location。它不会报语法错误,nginx -t 一行绿灯,重启之后某条规则就是不生效:伪静态规则被前面的正则劫持、root 写了却不指向你以为的目录、add_header 在某个块里无声消失、try_files 兜底之后 404 而不是进 PHP。

这些问题的根源是同一个:Nginx 挑选 location 有一套明确的优先级规则,而且不同类型的指令继承方式不同。把这套规则记住,绝大多数"玄学"都会变成可推理的结果。下面分三块讲:优先级、静态文件与动态请求的交接、以及几种无声失效的指令。

一、location 的匹配顺序:先精确,再前缀,再正则

Nginx 收到请求后,在同一个 server 块内按下面的顺序找 location,一旦按规则确定了就不再回头:

  1. = /path:精确匹配。命中即终止,优先级最高。
  2. ^~ /prefix/:前缀匹配且命中后停止搜索正则。它的作用是"这个前缀我不要正则来抢"。
  3. /prefix/:普通前缀匹配。会记录最长的那个匹配,但不立即使用,继续去试正则。
  4. ~ 与 ~*:正则匹配,按配置文件中出现的先后顺序逐个尝试,第一个命中即使用。
  5. 如果所有正则都没命中,才回到第 3 步记录下的最长前缀。

关键在第 3 和第 4 之间:普通前缀匹配是可以被正则覆盖的。这就是全部困惑的来源。

常见的翻车写法

假设你有一个 Typecho 或 WordPress 站,伪静态是这么写的:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~* \.(css|js|png|jpg|webp|svg|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, max-age=2592000";
}

这套配置工作正常。现在有人在中间插了一条"统一给静态资源加防盗链"的正则,或者加了一条 location ~ /archives/ 想做特殊处理,问题就来了:正则按文件顺序匹配,第一条命中的赢,写在后面的那条永远不会被执行。于是你明明写了规则、日志里却看不到它生效——这不是缓存问题,是根本没被选中。

判定技巧:让 Nginx 自己告诉你选了哪一条

不要靠猜。打开 debug 日志,请求一次,看命中的 location:

# nginx.conf 的 main 上下文
error_log /var/log/nginx/error.log debug;

# 只对某一个请求开 debug(推荐,避免日志爆炸)
# 在请求时带上:curl -H 'X-Debug: 1' ...
# 并在 server 块里:
error_log /var/log/nginx/debug_$host.log debug;

debug 日志里会有 test location: "/archives/"、using configuration "/archives/" 这样的行,直接给出答案。查完记得关掉,debug 日志一天能写几十 G。

用 ^~ 抢回控制权

如果某个前缀目录必须由前缀规则处理、不希望被任何正则抢走,就加 ^~:

location ^~ /static/ {
    root /var/www/site;
    expires 30d;
}

这样 /static/foo.png 一定走这个块,即使后面有一堆匹配 \.png$ 的正则。静态目录一律用 ^~,这是我给自己定的规矩,省掉无数排查。

二、try_files 与 PHP 的交接:404 与 502 背后的两条线

try_files 语义是"按顺序试,前面的存在就用,最后一个不存在也当成内部跳转目标"。两个细节决定成败。

最后一个参数不是文件,是跳转目标

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

前两个 $uri 与 $uri/ 是文件与目录检查,第三个 /index.php?$query_string 是内部重定向。漏写 $query_string,所有带参数的请求都会丢参数,页面能打开但搜索结果、分页参数全空。这条我在客户站上见过至少三次。

静态文件必须写 =404 兜底

location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$ {
    root /var/www/site;
    try_files $uri =404;
    expires 30d;
}

不写 try_files $uri =404,一个不存在的 .png 会落到这个 location 的末尾,被交给 PHP 处理(如果后面有 location ~ \.php$ 且被内部重定向命中),表现是图片请求返回 200 加一段 HTML,或者返回 502。日志里会看到大量 .png 的 500/502,其实文件只是丢了。带扩展名的 location 里兜底 =404 是硬性要求:宁可返回正确的 404,也不要返回错误类型的 200。

PHP 块里的 fastcgi_param 不能漏

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_read_timeout 60s;
    fastcgi_index index.php;
}

漏掉 SCRIPT_FILENAME 的典型症状是 FPM 日志里一堆 Primary script unknown,页面返回 404 或空白。include fastcgi_params 只提供通用变量,不提供脚本路径,必须自己写。

另外,fastcgi_index 在 location ~ \.php$ 里其实不起作用(它是给 fastcgi_pass 到目录时用的),写上去不报错但也没用。目录场景应该由 location / 的 try_files $uri $uri/ /index.php 来兜。

三、几种会"无声失效"的指令

add_header:只要当前块里出现了同名指令,上一层的全部丢失

这是最反直觉的一条。Nginx 的 add_header 不是累积的,而是"就近覆盖,整组替换"。如果 server 块里加了三条安全头,某个 location 块里又加了 Cache-Control,那么该 location 的响应里那三条安全头全部消失。

# server 层
add_header X-Frame-Options SAMEORIGIN always;
add_header X-Content-Type-Options nosniff always;

# 这个 location 会丢掉上面两条!
location ^~ /static/ {
    add_header Cache-Control "public, max-age=2592000";
}

解决办法有两个:一是在每个块里重复写全;二是用 include 抽成一个片段文件,在每个需要的块里都 include snippets/security-headers.conf。推荐第二种,改一处全局生效,也不会漏。

alias 与 root:路径拼接规则完全不同

# root:把 location 前缀保留下来拼接到目录后
location /static/ {
    root /var/www/site;          # 实际读 /var/www/site/static/xxx
}

# alias:把 location 前缀替换掉
location /static/ {
    alias /var/www/assets/;      # 实际读 /var/www/assets/xxx
}

alias 结尾的斜杠极易漏写。漏了之后 Nginx 拼出 /var/www/assetsxxx 这种路径,返回 404 或 403,而且你看着配置觉得完全没问题。经验:非必要不用 alias,用 root 加对应目录结构,可读性和容错都更好。

expires 与 add_header Cache-Control 混用

expires 30d 会自动加成 Cache-Control: max-age=2592000。如果同时手写 add_header Cache-Control,响应头里会出现两条 Cache-Control,浏览器行为取决于实现,CDN 更是各家不同。选一种就好,或者手写时用 add_header Cache-Control "public, max-age=2592000, immutable" 并把 expires 去掉。

四、几个只有踩过才知道的细节

rewrite 的 last 与 break:加了就换了一层规则集

rewrite ... last 会停止当前阶段、重新走一遍 location 匹配;rewrite ... break 则留在当前 location 继续执行后面的指令。区别看着抽象,实际表现是:用 last 时重写后的 URI 可能被另一条正则再抓一遍,形成跳转链甚至循环(Nginx 报 rewrite or internal redirection cycle);用 break 时 URI 变了但 location 不变,try_files 用的还是老路径。

经验规则:只改 URI、不换处理逻辑(比如老 URL 规则化)用 last;只是在当前块内换文件路径用 break。永不在 location / 里写一个无条件的 rewrite ^ /xxx last,那是最容易出循环的写法。

return 与 rewrite 的取舍

整站 301 用 return 301 而不是 rewrite ... permanent。return 是直接返回,不参与后续正则;rewrite 会进入重写阶段,可能被别的规则插队。而且 return 301 https://$host$request_uri 明确带上了原始路径与参数,比 rewrite ^/(.*)$ ... 安全得多——后者忘了加 $is_args$args 就会丢参数。

嵌套 location 几乎没用

Nginx 允许 location 里再写 location,但规则是:嵌套块从属于外层的前缀块,且只能在前缀块里嵌套正则。location ~ \.php$ 里面写 location ^~ /admin/ 是无效的,Nginx 会在启动时报"nested location can only be specified in a prefix location"或者直接忽略。遇到需要"某个目录下的 PHP 特殊处理",正确做法是拆成两条并列的规则:

location ^~ /admin/ {
    # 管理目录的静态部分
    try_files $uri $uri/ /admin/index.php?$query_string;
}

location ~ ^/admin/.*\.php$ {
    # 管理目录的 PHP 专属参数
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_read_timeout 120s;
}

用正则前缀 ^/admin/ 保证只匹配管理目录,又用了正则的优先级,比嵌套清晰得多。

map 比一堆 if 靠谱

需要根据条件设置变量时,很多教程教你用 if。Nginx 官方文档有一句著名的"sIf is Evil",原因不是 if 有 bug,而是 if 在一个 location 内产生了一个隐形的嵌套层级,里面的 try_files、return、rewrite 行为都会变。正确的工具是 map:

map $http_user_agent $is_bot {
    default        0;
    ~*(googlebot|bingbot|baiduspider)  1;
}

server {
    if ($is_bot) {
        set $cache_bypass "1";
    }
    # 或者在 proxy_cache_bypass / fastcgi_cache_bypass 里直接用 $is_bot
}

map 定义在 http 上下文,做的是纯变量映射,不产生嵌套、不改变配置结构,性能也更好。经验:能 map 就不 if,能 if 就不嵌套。

五、验证:三条命令把配置实测一遍

1) 语法与配置展开

nginx -t                              # 语法检查
nginx -T | less                       # 打印完整展开后的配置,含所有 include
nginx -T | grep -n "location" | head -50

nginx -T 比看源码文件有用得多——它把所有 include 展开,你能看到完整的、真正的生效配置。conf.d/ 和 sites-enabled/ 重复定义同一个 server_name 的经典事故,用它可以一眼发现。

2) 看响应头,而不是看页面

curl -sI https://example.com/static/app.css
curl -sI https://example.com/no-such-file.png   # 应该 404,不是 200

第一条验证 expires 和 add_header 是否真的出现;第二条验证静态兜底是否生效。这两个请求能覆盖上面说的大部分坑。

3) 抓一次真实请求的命中规则

临时把 error_log ... debug 打开,curl 一次,然后 grep "using configuration",看到的是最终选中的 location。查完关掉,别忘。

一张速查表

  • 精确 = > 前缀 ^~ > 正则 ~ > 普通前缀(正则优先于普通前缀,这是唯一需要记的"反常识");
  • 静态后缀一律 ^~ 或独立正则块 + try_files $uri =404;
  • 伪静态兜底必须带 $query_string;
  • PHP 块必须写 SCRIPT_FILENAME;
  • add_header 不累积,用 include 统一;
  • 能用 root 就别用 alias,用 alias 结尾必须带斜杠;
  • 不确定就 nginx -T + debug 日志,别猜。

Nginx 的配置不是魔法,只是优先级规则没被讲清楚。把上面前提记住之后,"配置不生效"这件事就只剩两种可能:写错了,或者被别的文件覆盖了。nginx -T 能同时排除这两种。

Last modification:November 18th, 2026 at 10:25 pm

Leave a Comment