WebSocket握手失败101状态码没返回是为什么？-常见问题-PHP中文网

协议升级失败时未出现101响应，主因是反向代理未透传upgrade头、服务端未正确处理upgrade请求、sec-websocket-key校验失败、tls证书问题或origin校验拦截。

websocket握手失败101状态码没返回是为什么？

如果您在浏览器中发起 WebSocket 连接请求，但 Network 面板中未看到 HTTP/1.1 101 Switching Protocols 响应，则说明协议升级过程在某一层被中断。该问题通常表现为静默失败——无 JavaScript 报错、onerror 不触发或延迟触发，仅连接状态长期停留在 CONNECTING（0）或直接跳转为 CLOSED（3）。以下是定位与修复此问题的多种途径：

一、检查反向代理（如 Nginx）是否透传 Upgrade 头部

Nginx 等网关默认不识别 WebSocket 协议升级机制，若未显式配置，会将 Upgrade 和 Connection 头过滤或改写，导致后端服务收不到合法握手请求，因而无法生成 101 响应。

1、打开 Nginx 配置文件，定位到对应 location 块（例如 location /ws/ 或 location /api/socket/）。

2、确认已添加以下三行且拼写准确（注意大小写与引号）：
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

3、检查 proxy_pass 指向地址是否可达，且后端服务监听地址与端口匹配（例如 http://127.0.0.1:8080）。

4、执行 nginx -t 验证语法，再运行 nginx -s reload 重载配置。

二、验证服务端是否正确处理 Upgrade 请求头

WebSocket 握手依赖客户端发送的两个关键请求头：Upgrade: websocket 和 Connection: Upgrade。若服务端框架（如 Workerman、Swoole、Ratchet 或自研 HTTP 服务器）未校验或忽略这两个字段，将直接返回 400 或 500，跳过 101 响应流程。

1、在服务端入口逻辑中插入日志，打印原始请求头：var_dump($request->getHeader('Upgrade'), $request->getHeader('Connection'));

2、确认输出中 Upgrade 值为 websocket（全小写，无空格），Connection 值包含 Upgrade（大小写敏感）。

3、若任一头缺失或值错误，需检查中间件、路由匹配逻辑或 HTTPS 重定向是否提前终止了原始请求。

4、对基于 PHP-FPM 的部署，确保服务端未运行于 CGI/FastCGI 模式——因进程生命周期极短，无法维持升级后的长连接，必须使用常驻进程模型（如 php start.php start -d）。

三、排查 Sec-WebSocket-Key 校验与响应头污染

服务端收到有效 Upgrade 请求后，必须依据 Sec-WebSocket-Key 计算 Sec-WebSocket-Accept 值，并返回完整响应头。任何计算错误、额外输出（BOM、echo、错误警告、var_dump）都会污染响应体，使浏览器拒绝升级，即便状态码为 101 也无法完成握手。

1、在服务端生成 Sec-WebSocket-Accept 前，调用 ob_end_clean() 清除所有输出缓冲区。

WebSocket 8.18.2

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

下载

2、Sec-WebSocket-Accept 必须严格按规范计算：对客户端 Sec-WebSocket-Key 字符串拼接固定 GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11，进行 SHA-1 哈希后 Base64 编码。

3、响应中必须包含且仅包含以下必需头：HTTP/1.1 101 Switching Protocols、Upgrade: websocket、Connection: Upgrade、Sec-WebSocket-Accept: [base64-sha1-value]。

4、使用 curl 手动模拟握手请求，观察原始响应字节流：curl -i -N -H "Upgrade: websocket" -H "Connection: Upgrade" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" -H "Sec-WebSocket-Version: 13" http://localhost:8080/ws。