Nginx 反向代理 WebSocket 连接失败报错 1006 怎么解决

Nginx 反向代理 WebSocket 报错 1006 通常是因为连接被意外中断，最常见原因是 Nginx 缺少 Upgrade 头配置或代理超时时间过短。解决方向是修正 Nginx location 配置并延长超时阈值，注意修改后需重载配置且不影响现有长连接。

先说结论：1006 错误表示 WebSocket 连接异常关闭，需在 Nginx 中显式启用协议升级并调整超时设置。

先确认：检查 Nginx 配置是否包含 Upgrade 和 Connection 头转发。
先处理：将 proxy_read_timeout 从默认 60 秒调大以适应业务心跳。
再验证：通过浏览器控制台观察 WebSocket 状态码及 Nginx 错误日志。

命令速用版

在 Nginx 配置文件的 location 块中加入以下标准 WebSocket 代理参数，保存后执行重载命令。

location /ws/ {
    proxy_pass http://backend_server;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

nginx -t && nginx -s reload

为什么会这样

WebSocket 基于 HTTP 协议升级机制建立连接，Nginx 默认按 HTTP 短连接处理，会导致握手失败或连接被提前切断。

HTTP 协议升级到 WebSocket 需要客户端发送 Upgrade: websocket 头，Nginx 必须透传该头给后端，否则后端无法识别协议切换。此外，Nginx 默认 proxy_read_timeout 为 60 秒，若 WebSocket 空闲超过此时间，Nginx 会主动断开连接，触发前端 1006 错误。

分步处理

按顺序检查配置、超时设置和后端状态，每步完成后记录结果以便回滚。

步骤 1：检查协议头配置
打开 Nginx 配置文件，确认 location 块中存在 proxy_set_header Upgrade 和 Connection 设置。若缺失，补全后保存。风险边界：修改配置前务必备份原文件，防止语法错误导致服务启动失败。

步骤 2：调整超时时间
根据业务心跳间隔设置 proxy_read_timeout，若业务无心跳，建议设置为大于 60 秒的值。公开资料中没有看到可靠的量化数据表明具体秒数，需根据实际业务空闲容忍度设定。

步骤 3：检查后端服务
确认后端 WebSocket 服务正常运行且未崩溃。若后端主动断开连接，Nginx 日志会记录 upstream closed 相关信息。

怎么验证是否生效

通过浏览器开发者工具和 Nginx 日志双向确认连接状态。

前端验证：打开浏览器开发者工具 Network 面板，筛选 WS 请求，观察状态码是否为 101 Switching Protocols，且连接未频繁断开。

日志验证：查看 Nginx 错误日志（通常位于 /var/log/nginx/error.log），确认不再有 upstream timed out 或 client closed connection 相关报错。

常见坑

以下场景容易导致配置生效但连接仍不稳定，需针对性排查。

负载均衡会话保持：若 Nginx 后端有多台服务器，未配置 ip_hash 可能导致 WebSocket 握手与后续数据请求落到不同机器，造成连接失败。

SSL 终止问题：若 Nginx 配置了 HTTPS，确保后端服务支持 wss 或 Nginx 正确转发加密流量，避免协议混合内容报错。

防火墙拦截：部分云服务商安全组或防火墙可能拦截长连接，需确认端口放行策略包含 WebSocket 使用的端口。

常见问题

1006 错误和 1005 错误有什么区别？

1006 表示连接异常关闭，未收到关闭帧；1005 表示未收到状态码，通常由客户端库内部产生。

Nginx 代理 WSS 需要额外配置吗？

需要，Nginx 监听 443 端口并配置 SSL 证书，proxy_pass 目标地址需改为 wss 或 https 协议头。

proxy_read_timeout 设置越大越好吗？

不是，过大的超时可能占用过多服务器资源，应根据业务心跳机制设定合理值。

参考来源

Nginx Official Blog, "WebSocket proxying", https://www.nginx.com/blog/websocket-nginx/
MDN Web Docs, "CloseEvent: code property", https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent
Nginx Documentation, "ngx_http_proxy_module", http://nginx.org/en/docs/http/ngx_http_proxy_module.html