worker_shutdown_timeout 是 nginx 重载时限制旧 worker 进程退出时限的全局参数，需置于 main 块，配合 proxy_timeout、client_timeout 等协同生效，合理取值依业务连接类型而定。
worker_shutdown_timeout 是 Nginx 平滑重载（nginx -s reload）时控制旧 worker 进程退出节奏的核心参数。它不“保连接”，而是给旧进程设一道强制退场时限——超时后主动关闭未结束的连接，避免卡在 shutting down 状态堆积资源。
必须写在 main 块
这个指令只在全局上下文生效，其他位置会被静默忽略：
✅ 正确写法（放在 nginx.conf 最外层，user、worker_processes 同级）：
user nginx;
worker_processes auto;
worker_shutdown_timeout 90s;
events { ... }
http { ... }
❌ 错误写法（任何嵌套块内都不行）：
http {
worker_shutdown_timeout 60s; # ← 完全无效
}
按业务类型设合理值
它不控制新连接，只决定旧 worker 能陪已有连接走多远。值太短会断连，太长会滞留：
- 普通 REST API（P99 ≤ 1s）：15–30s
- Keep-Alive / 长轮询（keepalive_timeout 通常 75s）：45–90s
- WebSocket / SSE / HTTP/2 流（心跳 30s）：≥ 90s，推荐 120–300s
- 大文件上传（如 2GB @ 5MB/s ≈ 400s）：≥ 450s，并同步确认
client_body_timeout ≥ 450
小技巧：起步可设
90s，再根据error.log中"worker process is shutting down"的持续时间微调。
必须闭环上下游超时
单设 worker_shutdown_timeout 几乎没用，需和以下参数对齐：
-
proxy_read_timeout和proxy_send_timeout必须 ≥worker_shutdown_timeout
→ 否则 Nginx 会在后端响应前主动关连接，旧 worker 仍被悬停 -
client_header_timeout和client_body_timeout应 ≤worker_shutdown_timeout
→ 防止慢客户端迟迟不发完头或体，把旧 worker 卡死
WebSocket 场景额外要求：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
缺一不可，否则 reload 后降级为短连接。
验证是否真生效
最直接办法：写个延时接口 + reload 同步触发：
location /slow {
return 200 "done after 25s\n";
}
执行：
nginx -s reload && curl http://localhost/slow
若返回完整内容且无中断，说明配置已起作用；若报错或超时，检查位置、单位、配套 timeout 是否匹配。
