WebSocket连接失败怎么办 WebSocket报错101状态码解决方法【指南】-js教程-PHP中文网

没看到101 switching protocols响应，说明websocket握手未走通，根本原因在于协议升级阶段被拦截：https页面必须用wss://、nginx需透传upgrade和connection头、服务端须严格校验sec-websocket-key并返回无污染的101响应。

websocket连接失败怎么办 websocket报错101状态码解决方法【指南】

没看到 101 Switching Protocols 响应，基本可以断定 WebSocket 握手根本没走通——这不是业务逻辑或心跳的问题，而是连接在协议升级阶段就被拦下了。

Network 面板里压根没出现 WS 请求记录

这说明浏览器连握手请求都没发出去，常见于协议/域名不匹配被主动拦截。

检查 URL 协议是否与页面一致：HTTPS 页面不能用 ws://，必须用 wss://；HTTP 页面也不能用 wss://
确认 new WebSocket("...") 中的地址拼写无误，特别是路径部分（如 /ws 末尾斜杠是否多余）
打开 DevTools → Network → 切到 WS 标签页（不是 XHR），刷新页面。若该标签页为空，说明请求未发出，此时看 Console 有没有类似 Mixed Content 或 Blocked loading mixed active content 的报错

Nginx 反向代理没透传 Upgrade 头

这是线上环境最常踩的坑。Nginx 默认把 WebSocket 当普通 HTTP 处理，直接丢掉 Upgrade 和 Connection 头，后端收不到合法握手请求，自然不会返回 101。

WebSocket 8.18.2

WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。

下载

在对应 location 块中必须包含三行（大小写、引号、变量名都不能错）：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";
$http_upgrade 是 Nginx 内置变量，值来自客户端原始请求头，不能写成 $upgrade 或硬编码 "websocket"
务必执行 nginx -t 验证语法，再 nginx -s reload 生效；改完不重载等于没改
如果用了多层代理（如 Cloudflare → Nginx → 后端），每一层都要检查是否透传了这两个头

服务端没正确响应 Sec-WebSocket-Accept

即使 Nginx 配对了，服务端仍可能因校验失败或输出污染导致 101 响应不完整。

服务端收到请求后，必须严格校验 Upgrade: websocket 和 Connection: Upgrade（注意大小写），任一缺失或值错误都会跳过升级流程
Sec-WebSocket-Key 必须原样读取并按 RFC 6455 规则计算 Sec-WebSocket-Accept，不能手动生成或硬编码
任何额外输出都会破坏响应头：PHP 中的 BOM、echo/var_dump、警告信息（Notice）、错误日志开启时的 header 输出，都会让浏览器认为响应非法而静默关闭
PHP-FPM 模式下无法维持长连接，必须使用常驻进程框架（如 Workerman、Swoole），否则即便返回了 101，连接也会立刻断开

看到 101 但连接立刻断开（状态码 1006）

这说明协议升级成功了，但后续通信链路出了问题，和握手无关。

检查 Nginx 的 proxy_read_timeout 和 proxy_send_timeout 是否太短（默认 60s），WebSocket 长连接需设为 0 或足够大（如 proxy_read_timeout 3600;）
确认服务端 WebSocket 连接管理逻辑是否正常：例如未注册 onopen 回调、未处理 ping/pong 帧、连接池满、内存溢出崩溃等
抓包看 TCP 层是否异常中断：用 tcpdump 或 Wireshark 检查 FIN/RST 包来源是客户端、代理还是服务端
某些防火墙或中间设备（如企业网关）会主动 kill 空闲长连接，需配合心跳帧保活，且心跳间隔要小于设备超时阈值

真正卡住排查的，往往不是“怎么配”，而是“哪一层悄悄吃了头”——从浏览器发起请求开始，每经过一个中间节点（CDN、WAF、LB、Nginx、服务网关），都要确认它是否原样透传了 Upgrade 和 Connection 头，少一层，101 就永远不会出现。