worker_shutdown_timeout 是 Nginx reload 时限制旧 worker 进程等待长连接关闭的最大时长，超时后强制关闭 socket 退出，需配置在 main 块、值覆盖业务最长耗时，并与 proxy_read_timeout 等协同对齐。

worker_shutdown_timeout 是解决 Nginx 长连接（如 WebSocket、SSE、大文件上传、HTTP/2 流）在 reload 时无法及时退出的核心配置。它不保证连接“优雅关闭”，但能防止旧 worker 进程无限期卡在 shutting down 状态，避免内存堆积、句柄泄漏和监控误报。

为什么长连接会让 worker 卡住不退出

默认情况下，Nginx 不设超时：旧 worker 进入 shutdown 状态后，会持续等待所有已建立的 TCP 连接自然断开。而长连接往往由客户端维持（比如心跳间隔 30 秒）、或后端尚未返回响应（如流式接口）、或用户正在上传大文件——这些连接可能存活数分钟甚至数小时。结果就是大量 worker 长期滞留，占用内存与文件描述符，却不再处理新请求。

worker_shutdown_timeout 的真实作用

它不是让连接“慢慢走完”，而是给旧 worker 设定一个最大服务窗口：

• reload 触发后，旧 worker 停止 accept 新连接，开始倒计时
• 倒计时期间继续处理所有活跃连接（含传输中、空闲 keepalive、WebSocket 数据帧）
• 超时一到，Nginx 主动关闭所有未自然结束的 socket，强制进程退出
• 该指令只对 nginx -s reload 生效，对 kill -9 或服务重启无效

怎么配才真正起效

必须满足三个硬性条件，缺一不可：

• 位置正确：只能写在 main 块（即 nginx.conf 最外层），不能放在 http、server、events 或 location 内
• 值要合理：需覆盖业务中最长可控耗时，例如：
  – 普通 REST API（P99 ≤ 1s）：设为 15–30s
  – WebSocket（心跳 25s + RTT ≤ 0.5s）：至少 45s，推荐 90s～2m
  – 大文件上传（2GB / 5MB/s ≈ 400s）：设为 480s 或更高
• 配套超时对齐：proxy_read_timeout 和 proxy_send_timeout 必须 ≥ 该值，否则 Nginx 会在 upstream 响应前主动断连；client_header_timeout 和 client_body_timeout 应 ≤ 该值，防慢请求拖住 worker

常见误区与避坑提醒

别指望它实现“零中断”的 WebSocket 平滑切换——Nginx 不解析帧，超时触发的是 TCP 强制 close，仍可能导致 1006 错误。真正降低影响靠的是协同：

• 确保代理头完整：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";
• 延长空闲容忍：proxy_read_timeout 86400; 防止默认 60s 主动断开 WebSocket
• 严禁手动 kill shutdown 中的 worker：会引发 open socket left in connection 和 aborting 日志，加剧资源泄漏
• 观察 error.log 中 worker process is shutting down 的持续时间，用它反推实际连接生命周期，再微调 timeout 值