ThinkPHP6.x实现WebSocket即时聊天需五步：一、安装启用Swoole扩展及think-swoole包；二、配置swoole.php开启WebSocket并指定处理器与路由文件；三、创建WsHandler类处理连接、消息与关闭事件；四、定义websocket.php映射消息类型到事件类；五、CLI启动独立服务并前端连接。
如果您在ThinkPHP6.x项目中尝试构建即时聊天室或实现消息实时推送功能，但客户端无法建立WebSocket连接、消息无法双向收发或服务启动后无响应，则可能是由于Swoole扩展未启用、事件处理器配置缺失或路由映射未定义。以下是完成该功能的具体步骤：
一、安装并启用Swoole扩展及think-swoole包
Swoole是PHP实现WebSocket长连接的核心扩展，think-swoole为ThinkPHP6提供官方集成支持；缺少任一组件将导致WebSocket服务无法初始化。
1、执行命令检查Swoole是否已加载：php -m | grep swoole，若无输出需手动安装。
2、使用PECL安装Swoole（Linux）：pecl install swoole，安装完成后在php.ini中添加extension=swoole并重启PHP服务。
立即学习“PHP免费学习笔记（深入）”；
3、在项目根目录执行：composer require topthink/think-swoole，确保版本与ThinkPHP6.x兼容（推荐v4.0+）。
二、配置swoole.php启用WebSocket模块
该配置文件控制Swoole服务的启动行为，必须显式开启WebSocket协议支持，并绑定事件处理器类与路由文件路径，否则握手请求会被拒绝。
1、打开config/swoole.php，确认存在以下结构化配置：
2、设置'websocket' => ['enabled' => true]；
3、指定'handler' => \app\listener\WsHandler::class，该类须继承\think\swoole\WebSocket；
4、声明'route_file' => app_path() . 'websocket.php'，路径必须真实存在且可读。
三、创建WebSocket事件处理类
该类负责管理连接生命周期、解析入站消息、执行广播逻辑及清理资源；若方法签名错误或未实现关键接口，连接将被立即断开。
1、运行命令生成监听器：php think make:listener WsHandler；
2、编辑app/listener/WsHandler.php，在onOpen方法中加入连接日志与用户身份校验逻辑；
3、在onMessage方法中调用$this->broadcast($data)向所有在线用户推送消息，或使用$this->send($fd, $data)定向发送；
4、在onClose方法中执行Redis键删除操作，例如redis()->del('user:online:' . $fd)。
四、定义websocket.php路由映射文件
该文件将客户端发送的JSON消息类型（如{"type":"chat","content":"hi"}）映射至对应业务逻辑，缺失此文件将导致所有自定义消息类型无法触发处理函数。
1、在app/目录下新建websocket.php文件；
2、返回关联数组，格式为：['chat' => \app\event\ChatEvent::class]；
3、确保每个映射类均实现handle($data, $fd)方法；
4、在ChatEvent::handle中调用$this->broadcast(...)完成群聊分发。
五、启动独立WebSocket服务进程
WebSocket服务不可通过Apache/Nginx + PHP-FPM方式运行，必须以CLI模式启动独立常驻进程，否则连接会因HTTP超时而中断。
1、执行启动命令：php think swoole；
2、验证服务端口监听状态：netstat -tuln | grep 9502（默认端口为9502）；
3、前端JavaScript使用new WebSocket('ws://127.0.0.1:9502')建立连接；
4、连接成功后调用ws.send(JSON.stringify({type:'chat', content:'hello'}))触发后端路由分发。
