上周帮一个客户做配置变更，nginx 版本 1.24，环境是典型的宝塔 + 手改 mixin 配置。他在 server 块里加了一条 add_header，然后 nginx -s reload，刷新页面，header 死活不出现。第一反应是改错了语法，其实不是后来排查了两个多小时，才发现问题出在 nginx -s reload 这个动作本身：它压根没有重新读取某些配置文件，也没有让老 worker 进程真的退出。这次经历让我决定把这块一直含糊着的东西彻底捋一遍。
说白了，平滑重载只是「换配置 + 换 worker」，不是「重启服务」：zji（独立服务器与裸金属，Tier3 机房） 这类机器上跑多核 nginx 时，一次 reload 会同时拉起一批新 worker，等老 worker 把手上的连接做完再退；如果机器本身的 CPU 和网络带宽吃紧，reload 的瞬间新旧进程一起抢资源，反而会比 restart 更难看。反过来说，如果你需要的是「大流量下换配置不丢连接」，那么机器本身的规格和带宽就得先跟得上，zorocloud（CN2 GIA / 9929 / CMIN2 高端线路云主机） 这类优化线路在大流量场景下做平滑切换会稳得多。配置怎么写、进程怎么退，下面这几段才是重点。
一、reload 到底做了什么：一条 SIGHUP 信号引发的四步
nginx 的进程模型是「一个 master + N 个 worker」。master 只负责读配置、管 worker、自己不干活；真正收发请求的是 worker。执行 nginx -s reload 时，实际发生的是：
1. 客户端进程把 SIGHUP 信号发给 master 进程（通过 pid 文件找到 master）；
2. master 收到信号后，重新解析一遍配置文件，这一步如果语法报错，旧配置继续用，master 记一条 error 日志并放弃本次变更；
3. 解析成功后，master 拉起一批新 worker，用新配置开始接受新连接；
4. 老 worker 收到「请退出」的信号后，停止接受新连接，把手上已有的连接处理完，然后自己退出。
整个过程里 master 从不退出，所以连接不会断。这是「平滑」二字的来源。但正因为 master 不退出、只是「重新解析」，很多盲区就藏在这个前提里。
盲区一：老 worker 赖着不走，配置看着像没生效
这是最常见的一个。reload 之后你 ps -ef | grep nginx 一看，发现老 worker 还在，明细里的启动时间还是老时间戳，于是认定「没生效」。
实际上老 worker 没走是设计使然：它要等手上的长连接、超时未完成的请求、上传下载中的流全部收尾，才会真正退出。默认情况下没有强制的退出时限，如果站点上挂着 WebSocket、大文件下载或者那种故意设置的慢速 keepalive 连接，老 worker 可以挂上几十分钟甚至更久。
想让它快点退，可以给 worker 进程设一个退出超时：
worker_shutdown_timeout 30s;
worker_processes auto;
加上之后，超时到点老 worker 会被强制结束，代价是那些还没传完的连接会被切断。上传下载业务多的站点别设太短，5 秒就够呛。
另外要区分两种「进程还在」：老 worker 还在是正常的；而 master 本身没变，则是另一个信号说明它压根没重新读配置，或者读配置失败了。判断有没有生效，看的不是进程列表，而是 master 的日志：
tail -f /var/log/nginx/error.log | grep -E 'signal|reconfiguring|start worker|gracefully shutting down'
正常的一次 reload，日志里应该能看到 signal process started、reconfiguring、start worker process 和 gracefully shutting down 这几行。如果只看到 signal started 而没有 reconfiguring，那就是配置解析失败或者压根没走到那一步。
盲区二：include 进来的片段没被重新读
如果你的配置是拆开来的：主配置里写 include /etc/nginx/conf.d/*.conf;，每个站点一个文件，那么还有一个很隐蔽的情况：reload 的时候，如果你改的是被 include 的文件，且这个文件里有语法错误，master 会整份配置都不加载，继续用旧配置跑，并且只在 error.log 里留下一行，终端上你根本看不到。
更常见的坑是：有些参数在 nginx 里是「只读」的，reload 改不动。worker_processes、worker_rlimit_nofile、listen 的 backlog、master_process 这些，都需要在启动时确定，reload 只是让新 worker 继承，旧的 worker 依然按老参数在跑。真正想让它们生效，只能 systemctl restart nginx。
所以日常操作最好养成习惯，改完先单独验一遍语法再 reload：
nginx -t -c /etc/nginx/nginx.conf
nginx -s reload
nginx -t 输出的最后一行是 syntax is ok / test is successful 才算过关。我见过不止一次，有人直接 vim 改完就 reload，语法错的地方在第 200 行，而错误日志在另一个目录的某个文件里，reload 之后站点「看起来正常」，其实跑的还是三天前的配置。
盲区三：reload 之后连接没复用，keepalive 白配
第三个盲区跟流量有关。reload 会换掉一批 worker，新 worker 起来之后，客户端与服务器之间的 keepalive 连接需要重新建立。如果你在 upstream 里配了 keepalive，但 proxy_http_version 1.1 和 proxy_set_header Connection "" 没配全，上游的连接池实际上是空转的，每次请求照样新建 TCP 连接。
还有一个和 reload 直接相关的细节：老 worker 里那些已经建立的 upstream 连接，会随着 worker 一起被关闭。也就是说，reload 之后的第一波请求，连接建立成本是全额的，如果这个站点本身对首字节时间很敏感，在流量高峰做 reload 反而会让 p99 抖一下。稳妥的做法是挑低峰，或者干脆用两台机器做滚动发布，让 reload 分散在不同节点上。
upstream backend {
server 127.0.0.1:8080;
keepalive 64;
}
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://backend;
}
配完之后，可以在响应里加一个 add_header X-Upstream-Conn $upstream_connect_time always;，reload 之后对比这个值，就能直观看到连接复用有没有真的生效。
盲区四：reload 是「一次性」，不是「持续生效」
最后这个盲区跟自动化有关。很多人以为 reload 之后配置会一直按新的走，其实有些配置变化是需要额外动作的：
用 certbot 续了证书，nginx 不会自动 reload，得手动触发或挂 hook；
容器里挂载的配置文件更新了，宿主机上的 nginx 不一定能感知到文件变化（尤其是 inotify 跨不过某些挂载边界）；
配置模板是从配置中心（比如某些 CMDB / Consul）拉下来的，拉下来只是写了文件，还得有人记得执行 reload；
include 的通配符在文件被替换（不是修改）时，某些编辑器会先删后建 momentarily 导致匹配不到，这在自动化脚本里用 mv 覆盖时特别常见。
我的做法是把「校验 + reload + 结果确认」写成一个脚本，放在每次变更的末尾，并且把 error.log 里 reload 前后的时间窗口截出来存一份，方便日后回溯：
#!/bin/bash
set -e
if nginx -t; then
nginx -s reload
sleep 2
tail -n 20 /var/log/nginx/error.log | grep -E 'reconfiguring|start worker'
else
echo '配置校验失败，已放弃 reload' >&2
exit 1
fi
配合监控看 nginx stub_status 里的 active/accepting 数字，reload 前后各取一次，能更早发现异常。
最后
把这四个盲区串起来看，nginx 的平滑重载其实就一句话：它换的是 worker，不是服务；它读的是配置，不是运行态。知道这个前提之后，很多「reload 没生效」的玄学问题就都不玄了要么是配置压根没被读到，要么是被读到但那个参数只能重启才生效，要么是生效了但老进程还占着连接不放。
下次再遇到配置改了不起作用，建议按这个顺序查：nginx -t 验语法 → 看 error.log 有没有 reconfiguring → ps 看老 worker 还在不在 → 对比 $upstream_connect_time 判断连接有没有复用。四步下来基本没有查不出来的。
喜欢 
顶
难过
囧
围观
无聊
