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。
WebSocket 代理在 Nginx 中不能用普通 HTTP 反向代理方式处理，必须显式支持协议升级和长连接维持。配置核心是让 Nginx 正确透传 Upgrade 请求、保持 TCP 连接不中断，并禁用干扰实时通信的默认行为。
关键请求转发规则必须包含的指令
以下四条是 WebSocket 代理生效的硬性前提，缺一不可：
- proxy_http_version 1.1：启用 HTTP/1.1 协议，这是 WebSocket 升级机制的基础；设为 1.0 或省略会导致握手失败
- proxy_set_header Upgrade $http_upgrade：原样传递客户端的 Upgrade 头（可能是 websocket、mqtt 等），不能写死为 "websocket"
- proxy_set_header Connection "upgrade"：固定字符串 upgrade，不是变量；若误用 $connection_upgrade 且未配合 map 指令，可能触发 close 导致断连
- proxy_read_timeout 86400（24 小时）：防止空闲期超时断开；默认 60 秒会静默关闭连接，尤其影响聊天、监控类应用
避免缓冲与延迟的必要设置
WebSocket 数据以帧流形式实时传输，Nginx 默认缓冲策略会引入延迟或粘包：
- proxy_buffering off：禁用响应缓冲，确保后端发送的每个 TEXT/BINARY 帧立即透传给客户端
- tcp_nodelay on：绕过 Nagle 算法，小数据包（如心跳、光标更新）无需等待合并，立刻发出
- 不必配置 proxy_buffer_size、proxy_cache 等参数——WebSocket 不走缓存路径，设了无效还占内存
适配不同部署场景的转发路径写法
路径匹配需注意尾部斜杠和重写逻辑，直接影响后端接收的 URI：
- 若前端连接地址是 ws://example.com/ws，location 应写为
location /ws { ... }，proxy_pass 后不加 /，后端收到路径为 /ws - 若希望把 ws://example.com/api/ws 映射到后端 http://127.0.0.1:3000/ws，则 proxy_pass 写成
proxy_pass http://127.0.0.1:3000/;（末尾带 /），Nginx 会自动剥离 /api/ws 前缀 - 基于端口代理（如监听 8080）时，server_name 可设为
_，但必须保留proxy_set_header Host $host，否则后端依赖 Host 头做租户路由会出错
HTTPS（WSS）环境下的补充要点
使用 wss:// 时，SSL 终止在 Nginx，需额外传递协议信息并确保证书有效：
- proxy_set_header X-Forwarded-Proto $scheme：让后端知道原始请求是 https，避免生成错误的 http 链接
- listen 指令需含 ssl 和 http2（如
listen 443 ssl http2），并正确配置 ssl_certificate 和 ssl_certificate_key - 若后端需真实客户端 IP，X-Real-IP 和 X-Forwarded-For 仍需保留，它们不受协议类型影响
