Nginx代理WebSocket必须显式配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"、proxy_read_timeout≥86400、proxy_buffering off及tcp_nodelay on，缺一不可。
Nginx 默认不转发 WebSocket 升级请求，直接 proxy_pass 会卡在 400 或 502，必须显式配置协议透传和超时参数，否则连接建立即断。
proxy_http_version 1.1 和 Upgrade 头必须同时存在
WebSocket 握手依赖 HTTP/1.1 的 Upgrade 机制，Nginx 若用默认的 HTTP/1.0 或漏掉头字段，后端根本收不到升级意图：
- proxy_http_version 1.1 是硬性前提，设成 1.0 或不写都会导致握手失败
- proxy_set_header Upgrade $http_upgrade 必须用变量，不能写死为 "websocket"；某些 IoT 客户端可能发 "mqtt" 或其他值，硬编码会截断
- proxy_set_header Connection "upgrade" 注意是字符串 "upgrade"，不是 $connection_upgrade；后者在非 upgrade 请求时为空，Nginx 会发 Connection: close 主动断连
proxy_read_timeout 设太小会导致静默掉线
WebSocket 是长连接，Nginx 默认 proxy_read_timeout 是 60 秒，只要后端 60 秒没发数据，它就单方面关闭 TCP 连接，客户端看到的是“突然断开”，无错误日志：
- 聊天类应用允许用户长时间不发言？建议设为 proxy_read_timeout 86400（24 小时）
- 若后端有 ping/pong 心跳（如每 30 秒一次），可设为 proxy_read_timeout 45，但绝不能 ≤30
- proxy_send_timeout 也要同步调大，否则大消息分片发送中途可能被切断
- proxy_connect_timeout 影响建连阶段，一般 30 秒足够，不必盲目拉长
location 块里要关缓冲、开 tcp_nodelay
WebSocket 数据是实时帧流，Nginx 默认行为会引入延迟或粘包：
- proxy_buffering off：禁用响应缓冲，避免 Nginx 暂存后端发来的多个 TEXT 帧再合并吐出
- tcp_nodelay on：绕过 Nagle 算法，小数据包（如心跳、光标位置更新）立即发出，对协同编辑、实时游戏很关键
- 不用配 proxy_buffer_size 或 proxy_cache，WebSocket 不走缓存路径，设了无效还占内存
- 若用 HTTPS（wss://），记得加 proxy_set_header X-Forwarded-Proto $scheme，否则后端可能误判协议生成 http 链接
基于端口的 server 块容易漏掉 Host 头
监听非标准端口（如 8080、8081）时，server_name _ 虽能兜底，但后端若依赖 Host 头做路由或租户识别，就会出错：
- 必须保留 proxy_set_header Host $host，哪怕只配一个 server 块
- 若前端用域名访问（如 wss://myapp.example.com:8080），$host 就是该域名；若用 IP（如 wss://192.168.1.100:8080），$host 就是 IP，后端需兼容
- 多端口映射时（8080→3000、8081→3001），每个 server 块的 proxy_pass 和超时值要单独核对，复制粘贴容易漏改
实际生效前别忘了 nginx -t 检查语法，然后 nginx -s reload。最常被忽略的是 Connection 头写成变量、proxy_read_timeout 没随业务心跳调整、以及 HTTPS 场景下漏传 X-Forwarded-Proto —— 这三个点占了线上 WebSocket 掉线问题的七成以上。
