Nginx 代理 WebSocket 需显式配置升级头、禁用缓冲与超时：设 proxy_http_version 1.1，proxy_set_header Upgrade $http_upgrade 和 Connection "upgrade"，proxy_buffering off，proxy_read_timeout 86400，proxy_send_timeout 86400，并用独立 location 如 /ws 匹配，加 if 判断校验 Upgrade 头。
在 Nginx 中正确代理 WebSocket，关键不是简单转发，而是显式处理升级请求头、禁用缓冲、维持长连接。否则浏览器会报 WebSocket connection to 'ws://...' failed: Error during WebSocket handshake。
必须设置的 WebSocket 升级头
Nginx 默认不透传 Connection 和 Upgrade 请求头，而 WebSocket 握手依赖这两个字段。需在 location 块中显式添加：
-
proxy_http_version 1.1;—— 强制使用 HTTP/1.1（WebSocket 升级仅支持该版本） -
proxy_set_header Upgrade $http_upgrade;—— 将客户端的Upgrade: websocket透传给后端 -
proxy_set_header Connection "upgrade";—— 告诉 Nginx 不关闭连接，执行协议升级
禁用缓冲与超时控制
默认 proxy 缓冲和短超时会中断 WebSocket 的双向持续通信：
-
proxy_buffering off;—— 关闭响应缓冲，避免消息堆积延迟 -
proxy_read_timeout 86400;—— 设置极长读超时（如 24 小时），防止空闲连接被断开 -
proxy_send_timeout 86400;—— 同理，保障服务端主动推送不被中断
注意：proxy_timeout 类指令作用于整个连接生命周期，不是单次请求；值设为 0 表示“不限制”，但部分旧版 Nginx 不支持，建议用大整数更稳妥。
匹配路径与协议校验
推荐用明确路径（如 /ws）隔离 WebSocket 流量，便于维护和日志追踪：
- 不要用
location / { ... }兜底代理 WebSocket，易与静态资源或 API 冲突 - 可加条件判断增强健壮性：
if ($http_upgrade != "websocket") { return 403; }，拒绝非 WebSocket 升级请求 - 确保后端服务监听的是
ws://或wss://，Nginx 本身不处理 TLS 终止后的协议识别，wss 需配合ssl_certificate和proxy_pass https://...（或保持 ws + SSL 终止在 Nginx）
验证与调试技巧
配置生效后，通过 curl 模拟握手可快速定位问题：
- 运行：
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" http://your-domain/ws - 成功响应应含
HTTP/1.1 101 Switching Protocols及对应Upgrade、Connection头 - 检查 Nginx error log，常见错误如
upstream prematurely closed connection多因后端未响应升级，或client sent invalid upgrade request源于头缺失
浏览器开发者工具 Network 标签中，WebSocket 连接状态显示为 “(pending)” 或直接失败，通常说明握手阶段就已中断，优先查 Nginx 的 upgrade 头配置是否完整。
