Nginx代理WebSocket高频断连主因是proxy_read_timeout默认60秒，需在location块中配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade与Connection "upgrade"、proxy_read_timeout 3600，并关闭缓冲和gzip，验证101状态码及错误日志无upstream prematurely closed connection。
前端 WebSocket 连接在 Nginx 反向代理下高频断开，90%以上是因 Nginx 默认将空闲连接视为“失效”并主动切断——核心问题不是代码或网络，而是 proxy_read_timeout 仍为默认的 60 秒。只要后端无数据持续推送，Nginx 就会在 60 秒后单方面关闭 TCP 连接，前端收到 close 事件，表现为“突然断连、频繁重连”。解决的关键是让 Nginx 明白：这不是普通 HTTP 请求，而是一个需要长期存活的双向通道。
必须加在 location 块里的三项基础配置
这些不能写在 http 或 server 级，必须精准落在匹配 WebSocket 路径（如 /ws/、/api/socket）的 location 块内：
- 启用 HTTP/1.1 协议支持：添加 proxy_http_version 1.1; —— WebSocket 升级机制依赖 HTTP/1.1 的 Connection 控制能力，HTTP/1.0 不支持 Upgrade
- 透传协议升级头：添加 proxy_set_header Upgrade $http_upgrade; 和 proxy_set_header Connection "upgrade"; —— 缺一不可，否则后端收不到握手信号，返回 400 或 200 而非 101
- 延长读超时时间：显式设置 proxy_read_timeout 3600;（建议至少 3600，即 1 小时）—— 它控制 Nginx 等待后端数据的最长时间，空闲保活全靠它
配套优化：防止缓冲、压缩和中间设备干扰
只调超时还不够。Nginx 的默认行为（如缓存响应、启用 gzip）会破坏 WebSocket 帧结构或延迟心跳，导致连接被防火墙、云 LB 等中间设备静默断开：
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 关闭响应缓冲：加上 proxy_buffering off; —— 避免 Nginx 缓存后端推送的消息，造成粘包或 pong 延迟
- 同步发送超时：设 proxy_send_timeout 3600; —— 与 read 超时一致，防止服务端发大消息时被中断
- 禁用 gzip 压缩：加入 gzip off; 或确保 gzip_types 不含 application/json、text/plain 等 WebSocket 常用类型 —— 压缩会改变帧边界，引发解析错误
验证是否真正生效的三个硬指标
重启 Nginx 后，别只看“能连上”，要确认底层握手和链路行为完全正确：
立即学习“前端免费学习笔记（深入）”；
- 浏览器 Network 面板查状态码：WebSocket 请求响应状态必须是 101 Switching Protocols，出现 200、403、502 或 504 说明升级失败
- 检查请求/响应头：请求头中应有 Upgrade: websocket 和 Connection: Upgrade；响应头中应含 Upgrade: websocket 和 Connection: upgrade
- 盯紧 Nginx 错误日志：执行 tail -f /var/log/nginx/error.log，搜索 upstream prematurely closed connection —— 出现即代表配置未生效，连接仍被提前终止
前后端协同：心跳节奏要穿透所有中间层
Nginx 层配置只是起点。真实网络中，云负载均衡器、企业防火墙、NAT 网关等常设 30–90 秒静默超时，比 Nginx 更激进：
- 客户端心跳建议每 25 秒发一次 ping —— 必须小于最短中间设备超时（如阿里云 SLB 默认 60 秒，但部分区域为 30 秒）
- 服务端需注册 ping 处理器并快速 pong 回复 —— 例如 Gorilla WebSocket 中调用 conn.SetPingHandler(...)，且 pong 必须在 3 秒内发出
- HTTPS 场景额外注意：若前端用 wss://，Nginx server 块必须完整配置 SSL（证书、密钥、ssl_protocols TLSv1.2+），否则浏览器直接拒绝建立连接
