需安装hyperf/websocket-server组件、配置server_websocket服务器、创建websocketcontroller控制器并注解事件方法、可选路由绑定与中间件、最后启动服务验证连接。
如果您希望在Hyperf框架中启用实时双向通信能力，但WebSocket服务未正常启动或无法响应客户端连接，则可能是由于服务配置缺失、组件未安装或控制器未正确声明所致。以下是实现Hyperf WebSocket服务的多种方法：
一、安装WebSocket服务组件
Hyperf默认不包含WebSocket运行时支持，需显式引入官方扩展包以激活底层Swoole WebSocket能力。该步骤是所有后续配置的前提。
1、执行Composer命令安装核心依赖：composer require hyperf/websocket-server
2、确认Swoole扩展已启用且版本兼容（推荐Swoole ≥ 4.8.0）
3、检查php.ini中extension=swoole.so是否已加载，可通过php --ri swoole验证
二、配置WebSocket服务器实例
需在服务启动配置中注册一个类型为SERVER_WEBSOCKET的独立服务器，明确绑定监听地址与端口，并关联标准事件回调，确保握手、消息、断开等生命周期可被框架捕获。
1、打开config/autoload/server.php文件
2、在'servers'数组中添加以下配置块：
'name' => 'ws', 'type' => \Hyperf\Server\Server::SERVER_WEBSOCKET, 'host' => '0.0.0.0', 'port' => 9502, 'sock_type' => SWOOLE_SOCK_TCP
3、在'callbacks'中映射关键事件：
Event::ON_HAND_SHAKE => [\Hyperf\WebSocketServer\Server::class, 'onHandShake'], Event::ON_MESSAGE => [\Hyperf\WebSocketServer\Server::class, 'onMessage'], Event::ON_CLOSE => [\Hyperf\WebSocketServer\Server::class, 'onClose']
三、创建WebSocket消息处理器
通过注解驱动或接口实现方式定义控制器，使框架能在连接建立、消息到达、连接关闭时自动调用对应方法。此步骤决定业务逻辑如何响应实时事件。
1、新建类App\Controller\WebSocketController，继承\Hyperf\WebSocketServer\Annotation\WebSocketController
2、使用@OnOpen注解标记连接初始化方法，接收Request $request参数获取fd及查询参数
3、使用@OnMessage注解标记消息接收方法，参数为Frame $frame，从中提取$frame->data
4、使用@OnClose注解标记连接终止方法，传入int $fd用于资源清理
5、在方法内调用$this->sender->send($fd, $data)向指定客户端推送字符串数据
四、启用路由绑定与中间件（可选）
当需要对WebSocket连接路径进行语义化管理或统一鉴权时，可通过路由机制将特定URI路径映射到控制器，并插入全局中间件拦截非法请求。
1、编辑config/routes.php文件
2、调用Router::addServer('ws', function () { ... })，其中'ws'必须与server配置中的name一致
3、在闭包内注册路由：Router::get('/', 'App\Controller\WebSocketController')
4、如需中间件，在config/autoload/middlewares.php中为'ws'键添加中间件类数组
五、启动服务并验证连接
完成配置后，需重新启动服务进程以加载新服务器实例；前端可通过原生WebSocket API发起连接测试，确认握手成功及消息往返是否正常。
1、执行php bin/hyperf.php start启动服务
2、在浏览器控制台输入：const ws = new WebSocket('ws://127.0.0.1:9502')
3、监听ws.onopen事件确认连接建立
4、调用ws.send(JSON.stringify({ content: 'hello' }))发送测试消息
5、观察服务端日志输出及ws.onmessage是否收到响应
