WebSocket在Nginx下稳定长连的关键是覆盖HTTP短连接默认行为：必须在location块内同时配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"；设proxy_read_timeout与proxy_send_timeout≥心跳间隔×2（如86400s）；关闭proxy_buffering off和proxy_cache off；HTTPS下需禁用HTTP/2并确保TLS配置完整。
WebSocket 在 Nginx 下能稳定长连，关键不是“打开开关”，而是覆盖 Nginx 对 HTTP 短连接的默认行为。很多断连问题（比如 60 秒准时断、code 1006、握手返回 200）其实都源于几个参数没配齐、或没放在对的位置。
必须同时生效的协议升级三要素
这三个配置缺一不可，且必须写在同一个 location 块内：
- proxy_http_version 1.1; —— 否则 Nginx 用 HTTP/1.0 转发，Upgrade 机制根本不会触发
- proxy_set_header Upgrade $http_upgrade; —— 必须用变量，硬写 "websocket" 会失效（客户端可能发其他协议）
- proxy_set_header Connection "upgrade"; —— 注意是固定字符串 "upgrade"，不是变量，也不是 "keep-alive"
超时参数不能只调一个
WebSocket 连接建立后，Nginx 仍会用 proxy_read_timeout 和 proxy_send_timeout 控制连接生命周期。默认都是 60 秒，这就是“准时断连”的根源。
- proxy_read_timeout：控制 Nginx 等待后端发数据的空闲时间。设为 86400（24 小时）较稳妥，至少 ≥ 后端心跳间隔 × 2
- proxy_send_timeout：控制 Nginx 往客户端写数据的连续等待时间。大消息、分片帧、网络抖动时容易触发，建议与 read_timeout 设为相同值
- 这两个参数必须写在 location 块里才对 WebSocket 生效；写在 server 或 http 块里无效
缓冲与缓存必须关闭
WebSocket 数据是帧流，不是完整响应体。Nginx 默认开启缓冲，会导致消息延迟、粘包甚至静默丢帧。
- proxy_buffering off; —— 强制禁用缓冲，确保帧实时透传
- proxy_cache off; —— WebSocket 消息不可缓存，加了会报错或静默失败
- 禁用缓冲后，proxy_buffer_size、proxy_buffers 等参数自动失效，无需额外配置
HTTPS 场景下的特别注意点
wss 连接失败，常常不是后端问题，而是 Nginx 的 TLS 配置不完整：
- server 块中必须配置有效的 SSL 证书和私钥
- 启用 TLSv1.2 和 TLSv1.3，禁用 TLSv1.0 / TLSv1.1
- 显式关闭 HTTP/2：http_v2 off; —— 因为 HTTP/2 不支持 Upgrade 机制
- location 路径要直接匹配，避免 rewrite 改写请求头，否则 Upgrade 头可能丢失
