要让Nginx正确代理WebSocket实现稳定实时通信，关键是显式透传升级请求、禁用默认超时、确保后端完成101握手；需配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"，并设proxy_read_timeout和proxy_send_timeout≥86400。
要让 Nginx 正确代理 WebSocket 实现稳定实时通信，关键不是“加功能”，而是**显式透传升级请求、禁用默认超时、确保后端能完成 101 握手**。配置本身不复杂，但漏掉任意一项都可能导致连接秒断或降级为 HTTP。
必须设置的三个核心 Header
WebSocket 握手依赖客户端发起 Upgrade: websocket 和 Connection: Upgrade 请求头，而 Nginx 默认不转发也不处理这些字段。需在 location 块中明确声明：
- proxy_http_version 1.1：强制使用 HTTP/1.1（WebSocket 升级协议的基础）
-
proxy_set_header Upgrade $http_upgrade：把客户端原始的 Upgrade 头（值通常是
websocket）原样传给后端 - proxy_set_header Connection "upgrade"：告诉后端“这不是普通请求，是升级连接”，避免被当作普通长连接处理
超时时间必须调大
WebSocket 是长连接，Nginx 默认 proxy_read_timeout 为 60 秒，空闲时会主动断连。建议设为 3600–86400（1 小时到 24 小时），例如：
- proxy_read_timeout 86400：防止服务端长时间无数据返回时被 Nginx 关闭
- proxy_send_timeout 86400：避免服务端发包间隔稍长（如心跳间隔 30 秒）触发中断
- proxy_connect_timeout 30：保持合理，仅控制初始建连耗时，不影响后续通信
推荐使用 map 指令优化 Connection 头
直接写 "upgrade" 在某些场景下（比如客户端没带 Upgrade 头）可能出错。更健壮的做法是用 map 动态构造 Connection 值：
- 在
http块顶部添加：map $http_upgrade $connection_upgrade { default upgrade; "" close; } - 然后在 location 中写：
proxy_set_header Connection $connection_upgrade; - 这样当客户端未发送 Upgrade 头时，Connection 设为
close，避免协议冲突
验证和排查要点
配置完别急着重启，先确认几个关键点：
- 浏览器 Network 面板里 WebSocket 请求状态码必须是 101，不是 200 或 502
- 用 curl 模拟握手：
curl -i -H "Connection: upgrade" -H "Upgrade: websocket" http://your-domain/ws，看是否返回 101 - Nginx error log 出现
upstream prematurely closed connection？大概率是后端没监听、崩溃，或未正确响应 101 - HTTPS 环境下必须用
wss://，且 Nginx 的listen 443 ssl已启用，证书有效
