改了 Nginx 配置却不生效的五种情况:add_header 继承、location 顺序与 last/break 的真假差异

上次我从外部那台小鸡打请求过来,看 Nginx 日志里全是 127.0.0.1,一开始以为是客户端的网关问题,后来在站点配置里翻到一个顺手加上的 add_header,问题才对上号。这件事不复杂,但几乎每个第一次把 Nginx 放在业务前面的人都会在一两个星期内撞上一次,而且报错现象往往跟真正的原因八竿子打不着。所以这篇不打算讲全部,只讲五个我自己踩过、也帮别人看过的配置:每一条都写清楚「写下去会发生什么」「怎么复现」「验证命令是什么」,最后把一次完整的排查过程从头走一遍。

先给自己准备一个能看见配置结果的环境

这类问题最难受的地方是:配置改了,服务也 reload 了,现象没变化,你不知道是配置没生效,还是生效了但方向错了。所以我习惯先做一个最小化的验证环境,不要去碰线上。

mkdir -p /tmp/ngx/t/{conf,logs,www}
cat > /tmp/ngx/t/conf/nginx.conf <<'EOF'
worker_processes 1;
error_log /tmp/ngx/t/logs/error.log warn;
pid /tmp/ngx/t/logs/nginx.pid;
events { worker_connections 128; }
http {
    access_log /tmp/ngx/t/logs/access.log;
    client_body_temp_path /tmp/ngx/t/logs/body;
    proxy_temp_path /tmp/ngx/t/logs/proxy;
    fastcgi_temp_path /tmp/ngx/t/logs/fcgi;
    server {
        listen 18080;
        server_name _;
        root /tmp/ngx/t/www;
        location / { return 200 "hit\n"; }
    }
}
EOF
nginx -p /tmp/ngx/t -c conf/nginx.conf -t
nginx -p /tmp/ngx/t -c conf/nginx.conf
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18080/

注意 -p 参数:它决定了相对路径的基准目录,不加的话 Nginx 会去找编译时写死的 /usr/local/nginx/...,日志和 pid 全落到别处,你以为 reload 成功了其实起的是另一个实例。改完配置用 nginx -s reload 时也要带上 -p 和 -c,否则 kill -HUP 打到的是另一个 pid 文件。这个坑我踩过一次,花了二十分钟怀疑配置语法。

有了这个环境,下面每一条都可以先在这里复现,确认行为之后再上生产。

一、add_header 的继承:被「加一条」直接抹掉的父层配置

Nginx 的 add_header 继承规则是:只要当前层级出现任意一条 add_header,父层的所有 add_header 全部失效。它不是合并,是替换。这就是全站安全头「时有时无」最常见的原因。

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

server {
    listen 18080;
    # 这里想加一条 CORS,结果上面两条全没了
    add_header Access-Control-Allow-Origin "*";
    location / { return 200 "hit\n"; }
}

验证方式就是看响应头,不要凭记忆:

curl -sI http://127.0.0.1:18080/ | grep -i x-frame
# 输出为空 = 被吃掉了

解决有两条路。一是在 server 层把需要的头全部重写一遍,简单粗暴但容易漏;二是把公共头抽成 include 文件,在每个有 add_header 的 block 里 include 进来,改一处不会漏另一处。第二种更耐用,代价是每个 location 都多一行。

还有一个细节:add_header ... always。不带 always 时,这个头只在 200、201、204、206、301、302、303、304、307、308 这些码上出现,500 和 429 上是没有的。所以你在浏览器里看安全头齐全,但用 curl -I 打一个会 500 的路径就发现没有 X-Frame-Options。安全头应该一律带 always,否则恰好是出错页最容易被 iframe 嵌套的时候没有防护。

二、location 的匹配顺序:你写的 /api 为什么没生效

Nginx 的 location 不是按书写顺序匹配的,规则大致是这样:先找精确匹配 =,命中即停;然后找前缀匹配,记住最长的那个;如果最长前缀带 ^~,就直接用它;否则再去试正则(~ 和 ~*),按书写顺序第一个命中的正则生效;正则都不命中才回到那个最长前缀。

最容易出事的是「正则优先级高于普通前缀」这一条。看下面这个典型配置:

location /static/ { root /data/www; }
location ~ \.(js|css|png|jpg)$ { root /data/cdn; expires 30d; }

你以为是 /static/a.png 走第一段,实际上走第二段,因为它命中了正则。于是文件路径变成 /data/cdn/static/a.png,404。很多人会去查权限、查软链,查了半天,问题在匹配顺序上。

修法是把静态目录锁死:location ^~ /static/ { ... }。加了 ^~ 之后,最长前缀匹配命中就不再试正则。

另一个高频问题是末尾斜杠。location /api 和 location /api/ 是不同的两个东西:前者会匹配 /apifoo,后者不会。如果你前面还挂了 proxy_pass http://backend/(带路径),那么 /api/x 会被改写成 /x 再发给后端;如果是 proxy_pass http://backend(不带路径),则原样发 /api/x。这一个斜杠差了整条 URL,排查起来经常要抓包才能看清。

想验证当前请求到底落在哪个 location,最省事的办法是在每个 location 里临时打一个不同的响应头:

location ^~ /static/ { add_header X-Loc static always; root /data/www; }
location ~ \.(js|css|png|jpg)$ { add_header X-Loc regex always; root /data/cdn; }
# curl -sI http://127.0.0.1/static/a.png | grep X-Loc

比读文档快得多。

三、rewrite 后的 last 与 break:一次多跳与地址不变的差别

rewrite 的 flag 有三个常用值,实际差别很大:

  • last:重写后停止当前 server 内的 rewrite 循环,用新 URI 重新走一遍 location 匹配;
  • break:停止 rewrite,但不再重新匹配 location,继续用当前 location 的配置处理;
  • redirect / permanent:直接返回 302 / 301 给浏览器,地址栏会变,多一次请求。

去掉 index.php 这类需求,写 rewrite ^/p/(.*)$ /index.php?cid=$1 last; 是对的,因为要重新进 location 交给 PHP 处理。但如果写成 permanent,浏览器地址栏会跳成 /index.php?cid=12,既暴露了实现细节,又多一跳,还容易被搜索引擎判成重复 URL。前端页面天天跳到 index.php? 上,收录质量会受影响。

反过来 break 的用法是「只改内部路径,不想重走 location」。比如把目录访问改到目录下的文件:

location /down/ {
    rewrite ^/down/(.*)$ /files/$1 break;
    root /data/storage;
}

这里用 last 会重新匹配 location,可能又命中 /down/ 造成循环,日志里会出现 rewrite or internal redirection cycle。error.log 里看到这句话,基本就是 last 用错了。

另外 rewrite 在 server 层是顺序执行的,一条改了 URI,后面的 $uri 就是新值。所以多条 rewrite 的书写顺序有意义,不要以为它们互相独立。

四、proxy 的一组头:真实 IP、协议、端口少一个就出问题

反代后面跑业务,最常见的症状是:日志全是 127.0.0.1、登录跳转跳回 http、生成的绝对链接端口不对、限流把所有人当成一个人。

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
}

几个容易错的点:

  • Host $host 会丢掉端口,如果站点跑在非 80 端口,后端拿到的 Host 不含端口,拼出来的绝对链接就少了端口。$http_host 是原样带端口的。区别在这里,不在别处。
  • X-Forwarded-For 用 $proxy_add_x_forwarded_for 而不是 $remote_addr,才会追加而不是覆盖。但这也带来一个安全前提:后端取「第一个 IP」是可以被伪造的,因为客户端可以自己带一个 XFF 头。正确做法是最外层 Nginx 用 proxy_set_header X-Forwarded-For $remote_addr; 覆盖掉用户传来的值,内层才用追加。链式反代时这一点必须理清楚,否则限流和封 IP 全是假的。
  • X-Forwarded-Proto 不加,后端以为自己是 http,登录成功后跳 http://,浏览器再跳回 https,用户看到两次跳转,有些场景还会丢 cookie。

验证方式:在后端起一个打印请求头的服务(php -S 配个 getallheaders(),或者 python3 -m http.server 加日志),从外部用带自定义 XFF 的 curl 打进来,看后端到底收到了什么。curl -H 'X-Forwarded-For: 9.9.9.9'。如果后端看到的第一个 IP 是 9.9.9.9,说明最外层没覆盖,限流规则就是形同虚设。

顺带提一句 proxy_buffering。默认是 on,Nginx 会先把后端响应攒在缓冲区再发给客户端。这对静态内容好,但对 SSE、长轮询、下载大文件不友好,表现为「后端已经输出完了,浏览器还在转圈」。这类 location 需要 proxy_buffering off; 和 proxy_read_timeout 调大,缺一个就是间歇性失败。

五、client_max_body_size 与上传路径上的三道关

上传 413 的经典排查:改了一处还是 413,因为限制有好几层。

  • Nginx client_max_body_size,默认 1m;
  • PHP upload_max_filesize 与 post_max_size,后者必须大于前者;
  • PHP max_execution_time 与 Nginx client_body_timeout,大文件慢速上传会被超时掐断;
  • 前面如果有 CDN 或另一台反代,它自己也有体积限制和超时。

诊断顺序应该是从最外层往里走:先绕过 CDN 直连源站试一次,还是 413 就排除 CDN;再 curl -v 看响应头是 Nginx 给的还是 PHP 给的(Nginx 返回的 413 页面通常是它自己的 413 Request Entity Too Large 样式,PHP 的则可能带业务页脚);最后看 PHP 的 error_log,POST Content-Length ... exceeds the limit 这句能直接定位是哪一层。

还有一个隐蔽点:client_body_buffer_size 小于 client_max_body_size 时,请求体会先写到临时文件再转发,client_body_temp_path 所在的分区如果满了,同样表现为 500 或 413,而 df 看的是根分区,看起来还有空间。这就是「磁盘没满却上传失败」的一种成因。

一次完整的排查:首页正常,登录就 502,报错页还一直转圈

说个真实的。现象:打开首页正常,点登录转几十秒后 502;换浏览器仍然一样;同服务器的另一个站点完全正常。

第一步,先看 error.log 的时间点,不要看 access.log 猜:

tail -200 /var/log/nginx/error.log | grep -A3 '502\|upstream'

看到 upstream timed out (110: Connection timed out) while connecting to upstream,说明是连接阶段超时,不是读取阶段。这一步就把范围从「应用慢」缩到「连不上应用」。

第二步,确认后端在不在监听、监听在哪个地址:

ss -ltnp | grep 8080

结果是 127.0.0.1:8080。而 proxy_pass 写的是 http://localhost:8080。这里就是问题:localhost 可能先解析到 ::1(IPv6),而 PHP-FPM 或 Node 只监听在 IPv4 的 127.0.0.1。首页为什么不挂?因为首页是静态文件由 Nginx 直接返回,根本没走 proxy。

为什么是「几十秒」而不是立刻失败?因为 proxy_connect_timeout 默认 60s,连不上会一直等。

第三步修:把 localhost 改成 127.0.0.1,或者让后端同时监听 ::1。改完 reload 验证:

nginx -t && nginx -s reload
curl -s -o /dev/null -w '%{http_code} %{time_total}\n' -X POST http://example.com/login

这里还有一个尾巴:为什么「报错页一直转圈」?因为 502 页面里引用了上一个静态资源路径,那个 location 又被我们加过 add_header 覆盖了缓存头,浏览器拿的是旧缓存和新的 502,来回重试。这一类连环问题,只有先看清日志阶段(connecting / sending / reading)才能顺着走。

把「验证」变成固定动作

上面五条其实都能归到一句话:每个配置写下去,都要有一个命令能立刻看到结果,而不是靠现象反推。我现在的习惯是,每次改完 Nginx 必做四件事:

nginx -t                                   # 语法与路径
curl -sI https://站点/ | head -20           # 安全头是否齐全
curl -sI https://站点/某静态文件 | grep -i cache  # 缓存头
tail -50 /var/log/nginx/error.log          # 有没有新报错

四条加起来不到十秒,但能挡掉八成「改完不知道有没有用」的情况。

最后补一个容易忽略的收尾:nginx -s reload 是热加载,老 worker 会等正在处理的请求跑完才退出。如果某个请求卡在一个长连接上,老 worker 会一直不退,占着端口和内存。改配置频繁的机器上,ps aux | grep 'nginx: worker' 看到 worker 数远超 worker_processes,就要怀疑有长连接挂着。这时候先查业务侧的超时,不要直接 kill,kill 会打断正在下载的文件。

配置这东西,写对不难,难在改错之后能快速知道错在哪。把日志的三个阶段(连接、发送、读取)和 location 的匹配顺序记牢,剩下的基本都是这两条规则的具体形态。

Last modification:November 22nd, 2026 at 01:23 pm

Leave a Comment