PHP实现WebSocket聊天室，Workerman搭建实时聊天教程

本文深入解析了使用 PHP 和 Workerman 搭建 WebSocket 聊天室时最常踩的五大“坑”：从启动后无法建立 WebSocket 连接（根源在于协议未启用及 Nginx 头透传缺失），到客户端收不到消息（因广播逻辑未正确管理连接容器）、热更新失效（子进程残留导致代码未真正刷新）、用户断线后 ID 复用引发消息错乱，再到根本性认知误区——Workerman 的 WebSocket 实现极度轻量，不内置会话、心跳和连接池，所有业务状态（如用户身份）必须与底层连接 ID 严格解耦，并通过 token 或 user_id 主动绑定与清理。这些不是配置错误，而是对 Workerman 网络模型本质的理解偏差，掌握它们，才能真正构建稳定、可维护的实时聊天系统。

Workerman 启动后连接不上 ws://localhost:2346 怎么办

绝大多数人卡在这一步：浏览器连不上，控制台报 WebSocket connection to 'ws://localhost:2346/' failed。根本原因不是代码写错了，而是 Workerman 默认只监听 0.0.0.0:2346，但没开 WebSocket 协议支持——它本身不解析 ws://，得靠 WebServer 或反向代理兜底。

实操建议：

• 别直接用 php start.php start 启动裸 Worker，改用 WebServer 模式，让 Workerman 兼容 HTTP 升级到 WebSocket 的握手流程
• 确保启动脚本里用了 Worker::setProtocol('websocket')（注意是单引号，不是字符串变量）
• 如果走 Nginx，必须透传 Upgrade 和 Connection 头，否则握手失败，Nginx 配置里漏掉这两行就白搭
• 浏览器测试时，确认 URL 是 ws://（不是 http://），且端口和启动端口一致；Chrome 控制台 Network → WS 标签页能看见连接状态

客户端 onmessage 收不到服务端发来的消息

常见现象：发消息成功，但别人收不到，或者自己也收不到回显。问题往往出在「广播逻辑」没写对，或连接未正确加入全局容器。

实操建议：

• $worker->connections 是所有 TCP 连接对象的集合，但 WebSocket 连接需要手动存进一个数组（比如 $clients = []），否则 foreach ($worker->connections as $conn) 会遍历到非 WebSocket 的管理连接，导致 send() 报错
• 每次 onConnect 时，记得把 $connection 存进自定义数组，并设唯一 key（如 $clients[$connection->id] = $connection）
• 发送广播时，别用 $connection->send() 直接发给当前连接，要遍历 $clients，跳过自己（if ($conn !== $connection)），不然会出现重复回显
• 注意 send() 参数必须是字符串，传数组会静默失败；JSON 编码要用 json_encode($data, JSON_UNESCAPED_UNICODE)，否则中文变 \uXXXX

Workerman 热更新失效，改了代码没反应

Workerman 不像 Laravel Swoole 那样自带 reload 命令，start.php restart 表面重启，实际可能只是杀掉了主进程，子进程还挂着——旧连接继续跑老代码，新连接才加载新逻辑，造成“改了但没完全改”的错觉。

实操建议：

• 强制终止所有相关进程：php start.php stop && ps aux | grep workerman | grep -v grep | awk '{print $2}' | xargs kill -9
• 启动时加 -d 参数看调试日志：php start.php start -d，观察是否真加载了新文件
• 避免在 onMessage 里 require 其他 PHP 文件，Workerman 不会自动重载这些依赖；需用 include_once + 文件时间戳判断，或统一放在主文件里
• 开发阶段建议用 php start.php start -d，生产环境再切 -d 关闭调试，否则日志刷屏影响排查

用户断线后消息还在发，连接 ID 复用导致混乱

Workerman 的 $connection->id 在连接断开后不会立即回收，新连接可能拿到相同 ID；如果用它做用户标识、存 session 或查数据库，就会串号——A 用户下线了，B 用户连上来，结果收到 A 的私信。

实操建议：

• 别拿 $connection->id 当用户 ID，它只是内存连接编号，生命周期只在本次 TCP 连接内有效
• 登录成功后，必须由客户端传一个稳定标识（如 JWT token 或后端生成的 user_id），服务端验证后绑定到 $connection 上：$connection->user_id = $uid
• 断开时清掉绑定：onClose 里 unset 对应的 $clients_by_user_id[$connection->user_id]，并从全局数组中移除该连接
• 广播前检查 isset($connection->user_id)，防止未登录连接参与聊天逻辑

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP实现WebSocket聊天室，Workerman搭建实时聊天教程》文章吧，也可关注golang学习网公众号了解相关技术文章。