nginx 代理 websocket 频繁断开的主因是未正确配置长连接支持。需透传 upgrade 和 connection 头、延长 proxy_read_timeout 等超时至 86400、禁用缓冲、强制 http/1.1、精准路径匹配及完整 https 配置。
WebSocket 连接在 Nginx 代理下频繁断开，90% 以上的情况不是后端或前端问题，而是 Nginx 把长连接当成了普通 HTTP 短连接来处理——它默认不维持空闲连接、不透传升级头、60 秒就主动切断。解决的核心是让 Nginx 明白：这不是一次请求，而是一条持续双向通道。
必须透传的两个协议升级头
WebSocket 握手依赖 Upgrade 和 Connection 两个请求头，Nginx 默认不转发，必须显式配置：
-
proxy_set_header Upgrade $http_upgrade; —— 将客户端发来的
Upgrade: websocket原样透传，不能写死为"websocket"，否则无法兼容其他升级类型 -
proxy_set_header Connection "upgrade"; —— 注意双引号，这是强制通知后端执行协议切换的指令，不是变量引用；若写成
$http_connection或漏掉，后端收不到信号，可能返回 400、200 或静默断连
超时设置必须大幅延长
WebSocket 是空闲时仍保持活跃的长连接，Nginx 默认 proxy_read_timeout 60 是主因。需同步调整三项超时，且值应 ≥ 后端心跳间隔（如后端每 30 秒 ping，timeout 至少设为 60 秒以上）：
- proxy_read_timeout 86400; —— 控制 Nginx 等待后端推送数据的最大时间，适用于心跳较长场景
- proxy_send_timeout 86400; —— 防止大消息分片发送中途被中断
- keepalive_timeout 86400; —— 维持客户端与 Nginx 之间的 keep-alive 连接时长
禁用缓冲并确保协议版本正确
WebSocket 是流式通信，缓冲和协议错配会直接破坏实时性：
- proxy_buffering off; —— 禁用响应缓冲，否则 Nginx 可能缓存后端推送帧，导致消息延迟或丢失
- proxy_http_version 1.1; —— HTTP/1.1 是 Upgrade 机制前提；HTTP/2 不支持 WebSocket 升级，即使启用 http_v2，也必须保留此行
路径匹配与 HTTPS 配置要严丝合缝
配置错位会导致头丢失或握手失败：
- 使用精确或前缀匹配的
location /ws/ { }，避免rewrite改写路径或 header - 若走 WSS，server 块中必须有完整 HTTPS 配置：
ssl_certificate、ssl_certificate_key、ssl_protocols TLSv1.2 TLSv1.3 - 不要在 location 内重复写
proxy_pass到带路径的 URL（如http://backend/ws/），易引发路径拼接错误
