worker_shutdown_timeout用于reload时约束旧worker退出时限，确保其处理完已有连接再退出，避免中断和资源堆积；必须置于main块，不设则无限等待。

worker_shutdown_timeout 本身不参与“全局块配置变更”的逻辑判断，它只在执行 nginx -s reload（或发送 HUP 信号）时生效，作用于旧 worker 进程的退出阶段。它不能保证配置变更本身平滑，但能确保旧 worker 处理完已有连接再退出，从而避免请求中断、连接异常关闭或资源堆积——这才是所谓“平滑过渡”的核心。

该指令必须放在 main 块（即 nginx.conf 最外层），否则无效。它不控制新 worker 启动行为，也不影响配置解析过程，只约束旧进程的生命周期。

它如何支撑 reload 时的平滑过渡

• reload 触发后，Master 进程启动新 worker，并向旧 worker 发送 QUIT 信号
• 旧 worker 立即停止 accept 新连接，但继续服务所有已建立的连接（包括 keepalive 连接、长轮询、上传中段、WebSocket TCP 流等）
• worker_shutdown_timeout 启动倒计时，超时后强制终止所有未自然关闭的连接并退出进程
• 新 worker 从 reload 完成起就接管全部新连接，实现流量无缝切换

若不设此值，旧 worker 可能无限等待连接关闭，导致：

• 进程数虚高、内存持续占用
• 监控显示 Active connections 不降反升
• 日志中频繁出现 open socket left in connection 或 aborting
• 在高频率发布场景下易触发 OOM 或连接耗尽

配置要点与常见误区

• 位置唯一：只能写在 main 块，不能嵌套在 events、http、stream 或任何 server 块内
• 语法简洁：worker_shutdown_timeout 60s;（支持 s/m/h 单位，如 2m、1h）
• 默认无值：Nginx 1.19.10+ 引入，但不设即为“无限等待”，不是 0s
• 非万能开关：它不解决协议降级、心跳丢失、帧截断等问题，仅控制进程退出节奏

如何设一个合理值

需匹配业务连接特征，而非统一填 30s：

• 纯短连接 API（无 keepalive）：10s～20s 足够覆盖 P99 响应时间 + 网络抖动
• 启用 keepalive（浏览器默认 5–75s）：建议 45s～90s，略大于最大空闲容忍窗口
• 长轮询 / SSE：按最长轮询间隔 × 2，例如轮询周期 30s → 设 60s
• WebSocket / HTTP/2 流：不靠它保平滑，但可设 90s～300s 防止旧进程滞留过久；真正依赖 proxy_read_timeout 和客户端重连

配合它才能真正落地平滑

单设 worker_shutdown_timeout 不足以应对复杂场景，还需同步检查：

• keepalive_timeout 是否过短（如默认 75s），建议调至 600s 减少重建开销
• proxy_read_timeout 和 proxy_send_timeout 是否覆盖业务最长空闲期（尤其 WebSocket）
• proxy_buffering off; 避免 Nginx 缓存未转发数据，造成延迟断连感知
• reload 前务必 nginx -t 验证语法，避免配置错误导致新 worker 启动失败、旧 worker 卡死

它不是让配置变更“自动变平滑”的魔法参数，而是给优雅退出加一道可控的时间边界。