Nginx实现WebSocket长连接的核心是显式配置协议升级与连接维持：必须设proxy_http_version 1.1、透传Upgrade和Connection头、禁用proxy_buffering、将proxy_read_timeout和proxy_send_timeout设为86400，并确保后端返回101状态码。
Nginx 实现 WebSocket 长连接实时通信，核心不是“自动支持”，而是**显式配置协议升级与连接维持机制**。WebSocket 握手依赖 HTTP/1.1 的 Upgrade 流程，而 Nginx 默认按短连接处理 HTTP 请求，会主动关闭后端连接——这直接导致 WebSocket 握手失败或连接秒断。必须通过一组关键指令告诉 Nginx：“这不是普通请求，这是要升级协议、保持 TCP 通道的长连接”。
强制启用 HTTP/1.1 并透传升级头
WebSocket 握手本质是一次带特殊头部的 HTTP GET 请求：
- Upgrade: websocket —— 告诉服务器客户端希望切换协议
- Connection: Upgrade —— 配合 Upgrade 头，触发协议切换流程
Nginx 必须原样转发这两个头部，否则后端收不到升级意图，只能返回 200 或 404，前端报错 “Error during WebSocket handshake”。配置如下：
proxy_http_version 1.1;<br>proxy_set_header Upgrade $http_upgrade;<br>proxy_set_header Connection "upgrade";
注意：$http_upgrade 是 Nginx 内置变量，能准确捕获客户端发来的 Upgrade 值（如 websocket）；不能写成 $http_connection，该变量在部分版本中会被自动过滤。
禁用缓冲并延长超时时间
WebSocket 数据是双向、低延迟、无固定边界的字节流，若开启响应缓冲或设置过短超时，会导致消息堆积、延迟甚至连接被 Nginx 主动断开：
- proxy_buffering off; —— 关闭响应缓冲，确保消息实时透传
- proxy_read_timeout 86400; —— 设置读超时为 24 小时，防止空闲时断连
- proxy_send_timeout 86400; —— 同理，避免发送侧因等待 ACK 超时中断
- proxy_cache off; 和 proxy_redirect off; —— 防止缓存干扰或重定向破坏长连接
后端必须正确响应 101 状态码
Nginx 只负责转发和维持连接，不参与协议逻辑。后端服务（如 Spring Boot、Node.js、Go）需明确识别 Upgrade: websocket 请求，并返回标准的 HTTP/1.1 101 Switching Protocols 响应。常见错误包括：
- 后端路由未匹配到 /ws 路径，返回 404
- Web 容器（如 Tomcat）未启用 WebSocket 支持，返回 200
- 反向代理前有 CDN 或 WAF 过滤了 Upgrade 头，导致后端根本收不到
可用 curl 快速验证后端是否就绪：
curl -i -N \<br> -H "Connection: Upgrade" \<br> -H "Upgrade: websocket" \<br> http://your-domain.com/ws
若返回 101 Switching Protocols，说明后端正常；否则问题在应用层。
生产环境补充：负载均衡与 wss 支持
多实例部署时，需在 upstream 中启用 keepalive，并考虑连接粘性：
upstream websocket_backend {<br> server 192.168.1.100:8080;<br> server 192.168.1.101:8080;<br> keepalive 10;<br>}
若走 HTTPS 页面（现代浏览器强制要求），前端必须使用 wss://，Nginx 需配置 SSL 终结，并复用同一套 WebSocket 代理参数。wss 不是新协议，只是 WebSocket over TLS，证书配置与 HTTPS 完全一致，无需额外修改代理逻辑。
