Nginx代理WebSocket需显式透传Upgrade和Connection头、启用HTTP/1.1、关闭缓冲与缓存、调大读写超时，确保协议升级不被截断、连接不被中断、帧流实时透传。
Nginx 本身不执行 WebSocket 协议转换，它只负责正确透传 HTTP 升级请求、维持长连接通道。所谓“自动转换”，本质是让客户端与后端顺利完成 HTTP → WebSocket 握手协商，关键在于 Nginx 不干扰、不降级、不缓冲。
协议升级必须显式放行
WebSocket 握手依赖标准 HTTP/1.1 的 Upgrade 流程，而 Nginx 默认会丢弃 Upgrade 和 Connection 这类 hop-by-hop 头部，并回退到 HTTP/1.0，导致 101 响应失败。
- proxy_http_version 1.1：强制使用 HTTP/1.1，这是 Upgrade 机制的唯一支持版本
-
proxy_set_header Upgrade $http_upgrade：用变量动态转发原始值（如
websocket），兼容 MQTT、STOMP 等其他升级协议 -
proxy_set_header Connection "upgrade"：注意是固定小写字符串
"upgrade"，不是变量；写成$connection_upgrade在非 WebSocket 请求中会变为空，导致普通 HTTP 出现Connection: close异常
超时设置要匹配长连接语义
默认 60 秒的 proxy_read_timeout 会误杀静默但活跃的连接（例如每 30 秒发一次心跳的客户端）。
-
proxy_read_timeout 设为略大于客户端最大心跳间隔（如 45 秒），或保守设为
86400（24 小时） - proxy_send_timeout 同步设为相同值，避免大消息分片发送中途被中断
- proxy_connect_timeout 可保持较短（如 60），仅控制建连阶段，不影响已建立连接
- 不建议设为
0（无限），旧版 Nginx 支持不稳定，且异常连接无法释放，易耗尽资源
关闭缓冲与缓存保障实时性
WebSocket 是流式、低延迟协议，Nginx 默认的响应缓冲和缓存机制会引入不可控延迟、丢帧甚至握手失败。
- proxy_buffering off：禁用响应体缓冲，确保 101 响应毫秒级透传，避免多个 TEXT 帧被合并
- proxy_cache off：显式关闭缓存，防止 Upgrade 请求被错误缓存并返回 200
- proxy_cache_bypass $http_upgrade：兜底策略，确保带 Upgrade 头的请求一定绕过缓存
- 避免启用
gzip或响应重写模块，它们可能截断或修改握手响应头
HTTPS（wss）场景需传递协议一致性
当 Nginx 终止 TLS（即客户端访问 wss://，后端走 ws://），后端需识别真实协议类型，否则可能生成错误链接或校验失败。
-
proxy_set_header X-Forwarded-Proto $scheme：让后端知道原始是
https还是http - 后端框架（如 Spring Boot、Express）需检查该头部，在生成
Sec-WebSocket-Accept或验证Origin时使用 - SSL 基础配置（
listen 443 ssl、证书路径、TLS 版本）必须已就绪，且server_name匹配域名
