Workerman与Swoole搭建WebSocket教程

本文深入对比了PHP生态中两大主流WebSocket解决方案——高性能C扩展Swoole与纯PHP实现的Workerman，清晰指出Swoole更适合中高并发生产环境（需注意版本≥4.8、心跳配置及Nginx反向代理关键Header透传），而Workerman凭借零扩展依赖、部署轻量和调试直观等优势，更适用于快速验证与中小负载场景；同时系统梳理了环境检查要点、服务启动规范、广播实现策略及高频连接失败的精准排查路径，为开发者提供了一站式、可落地的WebSocket服务搭建指南。

PHP 本身不支持原生 WebSocket 服务端，必须依赖扩展或框架实现长连接。Swoole 和 Workerman 是当前最主流的两个方案，但定位不同：Swoole 是高性能 C 扩展，适合中高并发生产环境；Workerman 是纯 PHP 实现，部署轻量、兼容性广，适合快速验证或中小负载场景。

确认基础环境是否就绪

无论选哪个方案，第一步都是检查 PHP 运行环境：

• 执行 php -v 确认 PHP 版本（Swoole 推荐 PHP 7.4–8.5，Workerman 4.1.0+ 支持 PHP 8.5）
• 运行 php -m | grep swoole 或 php -m | grep pcntl，分别确认 Swoole 扩展已安装，或 pcntl/posix 可用（Workerman 必需）
• 若用宝塔等面板，需在「PHP 设置 → 安装扩展」中启用对应模块，并重启 PHP 服务（不只是 Web 服务器）
• 禁用 CLI 模式下的 Opcache：opcache.enable_cli=0（Workerman 启动时动态加载类，开启会出错）

Swoole 方案：推荐用于生产环境

Swoole ≥4.8 是硬性门槛，低于该版本缺少协程广播、自动心跳管理等关键能力，易出现连接堆积、假死问题。

• 监听地址必须写成 '0.0.0.0:9501'，不能只绑 127.0.0.1，否则外部无法访问
• 务必配置心跳：'heartbeat_check_interval' => 60 和 'heartbeat_idle_time' => 600，避免断连后连接残留
• Nginx 反向代理时，必须透传两个关键 Header：Upgrade: websocket 和 Connection: upgrade
• 前端连接 URL 要带端口：new WebSocket('ws://your-domain.com:9501')；HTTPS 站点必须用 wss:// + Nginx 终止 SSL
• 广播消息要用协程处理：go(function () use ($server, $data) { foreach ($server->connections as $fd) { $server->push($fd, $data); } });，避免阻塞 worker 进程

Workerman 方案：适合快速落地与低维护成本

它不依赖扩展，靠多进程 + 事件循环工作，启动快、调试直观，但默认无心跳保活、连接数上限较低，不适合万级并发。

• 通过 Composer 安装：composer require workerman/workerman
• 入口文件中必须设置 $worker->count（如 4）和 $worker->name（便于进程管理）
• 启动命令为：php start.php start -d（-d 表示守护进程模式，前台运行会阻塞）
• WebSocket 协议由框架自动处理，你只需关注 onConnect、onMessage、onClose 回调
• 若需广播，可遍历 $worker->connections，但高并发下建议结合 Redis 存储连接映射，再用 HTTP API 或 Pub/Sub 触发推送

常见连接失败排查要点

前端报 “Connection closed before receiving a handshake response”，90% 不是网络问题，而是服务端握手未响应成功：

• 服务没启动，或端口被占用（用 lsof -i :9501 检查）
• 监听地址写错（如 127.0.0.1），或云服务器安全组未放行端口（如 9501）
• Nginx 未配置 Upgrade 头，或 HTTPS 页面尝试连 ws://（浏览器直接拦截）
• 手写握手逻辑——强烈不建议。Swoole 和 Workerman 都已封装完整协议，自己实现极易出错

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