Nginx代理WebSocket断连本质是默认按短连接处理长连接协议，需透传Upgrade和Connection头、设proxy_http_version 1.1、proxy_read_timeout与proxy_send_timeout为86400、proxy_buffering off，并在精准location中配置且验证响应码101。
WebSocket 在 Nginx 代理下断连，本质不是“不稳定”，而是 Nginx 默认按短连接 HTTP 处理长连接协议。只要配置对路，断连风险可大幅降低——核心不在前端重连，而在让 Nginx 正确认出、接住、留住 WebSocket 连接。
透传升级头：让握手真正生效
WebSocket 握手依赖两个关键请求头，Nginx 默认不转发，必须显式声明：
- proxy_http_version 1.1; —— HTTP/1.1 是 Upgrade 机制的前提，HTTP/2 不支持 WebSocket 升级
-
proxy_set_header Upgrade $http_upgrade; —— 把客户端发来的
Upgrade: websocket原样传给后端 -
proxy_set_header Connection "upgrade"; —— 注意双引号和小写
upgrade，这是通知后端执行协议切换的强制指令
漏掉任一，后端收不到升级信号，可能返回 200 或 400，连接根本升不起来，后续所有保活都无从谈起。
延长超时并禁用缓冲：守住长连接命脉
默认 proxy_read_timeout 60 是最大元凶——空闲 60 秒，Nginx 就主动 RST 断开 TCP。需同步调整三项：
- proxy_read_timeout 86400; —— 设为 24 小时（或 ≥ 心跳间隔 × 2），防止无数据时静默断连
- proxy_send_timeout 86400; —— 避免服务端推送大消息或分片过程中被中断
- proxy_buffering off; —— 关闭响应缓冲，否则 Nginx 可能缓存 pong 或业务帧，破坏实时性甚至导致粘包
若启用 gzip，还需加 gzip off; 或确保 gzip_types 不含 application/json 等 WebSocket 常用类型，压缩会篡改帧边界。
匹配路径与验证状态：排除配置错位
配置必须落在精准匹配 WebSocket 路径的 location 块内（如 location /ws/ { ... }），不能写在 http 或 server 级，否则不生效。
HTTPS 场景下，还需确认：
- SSL 证书完整有效（
ssl_certificate、ssl_certificate_key） -
ssl_protocols TLSv1.2 TLSv1.3;已启用 - 避免
rewrite或路径重写，防止 Upgrade 头在转发中丢失
验证是否真生效，看三处硬指标：
- 浏览器 Network 面板中 WebSocket 请求响应码必须是 101 Switching Protocols
- 响应头中必须含
Upgrade: websocket和Connection: upgrade - Nginx error.log 中不应出现
upstream prematurely closed connection
应对 reload 和中间设备：减少外部干扰
Nginx reload 会杀死旧 worker 中所有长连接。可启用平滑退出：
- 在
http块中加 worker_shutdown_timeout 60s;，允许旧进程多活 60 秒处理存量连接 - 更彻底方案：用
stream模块做 TCP 层透传（监听 wss 端口直转后端），绕过 HTTP 模块的 upgrade 逻辑和 reload 断连问题
还要考虑云负载均衡、NAT 网关等中间设备的隐形超时（常为 30–90 秒）。建议前端心跳 ≤ 45 秒，服务端必须及时响应 ping，形成闭环保活。
