ThinkPHP处理Websocket协议版本兼容_握手协议适配方案-ThinkPHP-PHP中文网

websocket握手失败因thinkphp默认丢弃upgrade头，需用swoole websocket server显式配置并接管tcp连接；sec-websocket-key大小写敏感、二进制帧opcode误判、ping/pong未透传是常见根源。

thinkphp处理websocket协议版本兼容_握手协议适配方案

WebSocket握手失败：ThinkPHP默认不处理Upgrade头

ThinkPHP原生HTTP服务器（如内置的think-swoole或workerman集成）默认把Connection: upgrade和Upgrade: websocket当普通请求丢弃，根本不会进入路由或控制器——所以你写的onOpen、onMessage压根不会触发。

关键不是“怎么写业务逻辑”，而是“怎么让请求先被识别为WebSocket”。必须在底层中间件或服务启动时拦截并接管原始TCP连接，跳过HTTP解析流程。

用think-swoole时，需显式配置'websocket' => true并启用Swoole\WebSocket\Server实例，不能只靠HttpServer
若自行集成Workerman，必须监听onConnect后手动检查$_SERVER['HTTP_UPGRADE'] === 'websocket'，再调用$connection->upgrade()
常见错误现象：ERR_CONNECTION_REFUSED或400 Bad Request且日志里无任何WebSocket相关输出

Sec-WebSocket-Key校验失败：Swoole版本与协议字段大小写敏感

WebSocket握手要求服务端返回Sec-WebSocket-Accept，值由客户端Sec-WebSocket-Key拼接固定字符串后base64-sha1生成。Swoole 4.8+默认严格校验Sec-WebSocket-Key是否全小写；而部分前端库（如早期socket.io-client）发的是sec-websocket-key，导致握手被拒绝。

这不是ThinkPHP的问题，是底层Swoole对RFC 6455的实现收紧了。绕过方式不是改前端，而是适配服务端接收逻辑。

在onRequest回调中手动提取$_SERVER['HTTP_SEC_WEBSOCKET_KEY']（Swoole会自动转下划线为大写，但旧版可能丢失）
若用think-swoole v4.x，升级到v5.0+，它已内置兼容大小写变体的Key提取逻辑
避免自己手算Sec-WebSocket-Accept——Swoole的$server->push()或$connection->upgrade()已封装完整握手流程

消息收发乱码/中断：二进制帧未正确标记

WebSocket支持文本帧（opcode=1）和二进制帧（opcode=2）。ThinkPHP生态里多数示例只处理onMessage文本数据，但实际项目中前端可能发ArrayBuffer或Blob，此时$frame->data是string类型二进制内容，直接json_decode()会失败或截断。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

真正要区分的是$frame->opcode，而不是靠is_string($frame->data)判断。

$frame->opcode === WEBSOCKET_OPCODE_TEXT → 可安全json_decode($frame->data, true)
$frame->opcode === WEBSOCKET_OPCODE_BINARY → 需按业务协议解析，例如unpack('Nlen/a*body', $frame->data)
常见错误：前端用ws.send(new Uint8Array([1,2,3]))，服务端没检查opcode就强转JSON，结果json_last_error()返回JSON_ERROR_UTF8
注意Swoole版本差异：WEBSOCKET_OPCODE_BINARY常量在Swoole 4.4+才稳定，低版本需用数字2

连接保活失效：ping/pong未透传或超时未清理

浏览器WebSocket默认30秒无通信会关闭连接，但ThinkPHP+Swoole默认不自动响应ping帧，也不主动发pong，导致连接被中间代理（如Nginx、CDN）静默断开。

这不是心跳逻辑没写，而是Swoole的onPing/onPong事件需要显式开启，并确保没有被中间件阻断。

在Swoole\WebSocket\Server构造时传入['heartbeat_check_interval' => 30, 'heartbeat_idle_time' => 60]
务必监听onPing并调用$server->push($fd, '')（空包即pong），否则Swoole不会自动回复
若用think-swoole，确认config/swoole.php中'websocket' => ['enable_ping_pong' => true]已开启
容易忽略的点：Swoole的heartbeat_idle_time是连接空闲上限，超过即close，但ThinkPHP的onClose回调未必能捕获——需在onClose里清数据库连接记录，否则用户重连时看到“已在线”却无法通信