如何设置ThinkPHP中的WebSocket实时推送功能？

本文共计791个文字，预计阅读时间需要4分钟。

如果您在ThinkPHP项目中启用了WebSocket实时推送功能，但客户端无法建立连接或接收消息，可能是WebSocket服务未正确启用或配置参数不匹配。以下是完成WebSocket推送配置的具体步骤：

一、启用Swoole扩展并安装think-swoole包

ThinkPHP 6需依赖Swoole扩展及think-swoole官方包才能运行WebSocket服务。Swoole必须以PHP扩展形式安装，且版本需与ThinkPHP兼容。

1、确认PHP已加载swoole扩展：执行 php -m | grep swoole，若无输出则需安装。

2、安装swoole扩展（以Linux为例）：pecl install swoole，安装后在php.ini中添加 extension=swoole 并重启PHP服务。

立即学习“PHP免费学习笔记（深入）”；

3、在项目根目录执行命令安装think-swoole：composer require topthink/think-swoole。

二、配置swoole.php启用WebSocket服务

需显式开启WebSocket模块，并指定事件处理器与路由文件路径，否则服务启动后不会响应WebSocket握手请求。

1、打开 config/swoole.php 文件，确保包含以下关键配置项：

2、将 'websocket' => ['enabled' => true] 设置为true；

3、设置 'handler' => \app\listener\WsHandler::class，该类须实现onOpen/onMessage/onClose方法；

4、指定 'route_file' => app_path() . 'websocket.php'，该文件用于定义消息事件路由映射。

三、创建WebSocket事件处理类

事件处理类承担连接生命周期管理与消息分发职责，必须继承\think\swoole\WebSocket或实现对应接口，否则框架无法识别其为合法WebSocket处理器。

1、执行命令生成监听器：php think make:listener WsHandler；

2、在生成的 app/listener/WsHandler.php 中，定义onOpen方法并加入日志输出或用户身份校验逻辑；

3、在onMessage方法中调用 $this->send($fd, $data) 或 $this->broadcast($data) 实现单播/广播；

4、确保onClose方法中执行资源清理，例如从Redis在线用户表移除连接标识。

四、配置WebSocket路由映射文件

websocket.php文件定义客户端发送的消息类型与后端监听器的绑定关系，若缺失或路径错误，自定义事件（如“chat.send”）将无法被触发。

1、在 app/websocket.php 中返回关联数组；

2、键名为客户端emit的第一个参数（如'chat.message'），值为对应的监听器类全限定名；

3、示例内容：return ['chat.message' => \app\listener\ChatMessage::class];；

4、确保该文件存在且可被读取，否则服务启动时抛出 FileNotFoundException 异常。

五、启动WebSocket服务进程

必须通过Swoole方式独立启动服务，不能通过传统PHP-FPM或Apache运行，否则长连接无法维持。

1、修改 public/index.php，注释或删除原有入口逻辑；

2、在项目根目录执行启动命令：php think swoole；

3、观察控制台输出是否含 "Swoole WebSocket server started" 及监听地址端口信息；

4、使用 netstat -tuln | grep :9501 验证端口是否处于LISTEN状态。