要让Nginx代理WebSocket实现高效通信流，关键在于精准匹配协议特性：必须配置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 实现高效通信流，关键不是堆砌参数，而是精准匹配协议特性：它本质是长生命周期的全双工通道，不是短连接 HTTP 请求。Nginx 不处理 WebSocket 帧，只负责可靠透传升级请求、维持连接不中断、并把原始语义完整交给后端。
必须配置的三项协议透传头
WebSocket 握手依赖客户端发起 Upgrade: websocket 和 Connection: upgrade 请求头，而 Nginx 默认不转发或改写这些字段，会导致握手失败（返回 200 而非 101）。需在对应 location 块中明确设置：
- proxy_http_version 1.1：强制使用 HTTP/1.1，因为 WebSocket 升级机制仅定义在该版本中
-
proxy_set_header Upgrade $http_upgrade：将客户端原始 Upgrade 头值（通常是
websocket）原样传递给后端 - proxy_set_header Connection "upgrade"：显式告知后端“这不是普通连接，是升级请求”，避免被当作 keep-alive 处理
防止空闲断连的超时调优
WebSocket 连接可能数小时无数据交互（如待机状态），但连接必须保持活跃。Nginx 默认 proxy_read_timeout 是 60 秒，会主动关闭空闲连接，导致前端报错 WebSocket is closed before the connection is established 或频繁重连。
- 设
proxy_read_timeout 86400（24 小时）或0（不限制），覆盖绝大多数业务场景 - 同步设置
proxy_send_timeout 86400，避免后端发包间隔较长（如心跳间隔 30 秒以上）时被误判为超时 -
keepalive_timeout对 WebSocket 无效，无需调整——它只影响 Nginx 与客户端之间的 HTTP 连接复用
避免缓存与连接复用干扰
WebSocket 是状态化长连接，任何中间缓存或连接池行为都可能破坏帧序或导致连接错乱。
- 添加
proxy_cache_bypass $http_upgrade：确保所有含 Upgrade 头的请求绕过缓存 - 禁用
proxy_buffering off（可选但推荐）：防止 Nginx 缓冲 WebSocket 帧，保证消息实时透传 - 不要在 location 块中启用
proxy_redirect或重写 Host 头以外的响应头——后端需自行控制 WebSocket 响应逻辑
后端与链路验证要点
Nginx 只做桥梁，最终通信是否成立取决于端到端协同：
- 后端服务必须正确响应
101 Switching Protocols，并计算Sec-WebSocket-Accept值；主流框架（ws、websockets、Spring WebSocket）默认支持 - 浏览器 Network 面板中，WebSocket 请求状态码必须是
101，且 Protocol 列显示websocket - 用 curl 模拟握手：
curl -i -H "Connection: upgrade" -H "Upgrade: websocket" http://your-domain/ws，确认返回 101 - SSL 环境下务必用
wss://，且 Nginx listen 必须带ssl参数；HTTP/2 不影响 WebSocket，可共存
