worker_shutdown_timeout 是 Nginx 1.19.10+ 引入的优雅重载机制，用于在 reload 时允许工作进程继续处理已建立连接最多指定时间（如30s），避免长连接被强制中断，需配置在 events 块中，与 keepalive_timeout 职责不同。
worker_shutdown_timeout 是 Nginx 1.19.10+ 引入的关键配置项，专为解决热重载（nginx -s reload）时旧连接被粗暴中断的问题而设计。它不控制新请求接入，而是决定：当主进程发出 shutdown 指令后，工作进程最多还能继续处理已建立连接多久，之后才真正退出。合理设置它，才能实现“旧连接跑完、新连接无缝接管”的真正优雅重载。
它解决什么问题？
默认情况下，Nginx reload 时，旧 worker 进程收到信号后会立即停止接受新连接，并尽快退出。但此时已在处理的长连接（如 WebSocket、HTTP/2 流、大文件下载、慢速客户端上传）可能被强制关闭，导致用户看到连接重置、传输中断或超时错误。
worker_shutdown_timeout 就是给这些“正在路上”的连接留出缓冲时间，让它们自然完成，而不是被一刀切。
怎么配置才有效？
该指令必须放在 events 块中，单位是秒（支持小数），全局生效：
events {
worker_connections 1024;
worker_shutdown_timeout 30s;
}
- 值设为
0表示禁用此机制（退回到传统快速退出） - 典型值推荐
10s～60s，具体取决于你最长的业务响应或传输耗时 - 它只影响 reload 或升级（
nginx -s upgrade）场景，对stop或崩溃无作用 - 需搭配
worker_processes auto;或明确数字使用，单 worker 时效果不明显
和 keepalive_timeout 的区别是什么？
这是最容易混淆的点：
keepalive_timeout 控制的是空闲 HTTP Keep-Alive 连接的最大等待时间——即客户端发完请求后，连接空着多久没新请求就关掉它。
worker_shutdown_timeout 控制的是 worker 进程在 reload 期间，对所有已建立连接（无论是否空闲、是否在传数据）的“最大容忍存活时间”。
前者管“静默”，后者管“善终”；两者可共存，互不替代。
验证是否生效？
最直接的方式是模拟一个长响应接口（如返回 20 秒后的内容），reload Nginx 同时用 curl 或浏览器发起请求，观察是否成功返回而非报错：
# 在 server 块中加个测试 location
location /slow {
return 200 "done after 25s\n";
add_header X-Worker-Pid $pid;
# 实际可用 echo 模块或 proxy_pass 到 sleep 脚本
}
执行 nginx -s reload，如果该请求仍能完整返回，说明 worker_shutdown_timeout 正在起作用。
