为什么"明明写了配置却不生效"总是发生在 location 上
Nginx 的配置里,报错最少但行为最难猜的就是 location。它不会报语法错误,nginx -t 一行绿灯,重启之后某条规则就是不生效:伪静态规则被前面的正则劫持、root 写了却不指向你以为的目录、add_header 在某个块里无声消失、try_files 兜底之后 404 而不是进 PHP。
这些问题的根源是同一个:Nginx 挑选 location 有一套明确的优先级规则,而且不同类型的指令继承方式不同。把这套规则记住,绝大多数"玄学"都会变成可推理的结果。下面分三块讲:优先级、静态文件与动态请求的交接、以及几种无声失效的指令。
一、location 的匹配顺序:先精确,再前缀,再正则
Nginx 收到请求后,在同一个 server 块内按下面的顺序找 location,一旦按规则确定了就不再回头:
= /path:精确匹配。命中即终止,优先级最高。^~ /prefix/:前缀匹配且命中后停止搜索正则。它的作用是"这个前缀我不要正则来抢"。/prefix/:普通前缀匹配。会记录最长的那个匹配,但不立即使用,继续去试正则。~与~*:正则匹配,按配置文件中出现的先后顺序逐个尝试,第一个命中即使用。- 如果所有正则都没命中,才回到第 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 -50nginx -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 能同时排除这两种。