Workerman 不应通过 Composer 安装,因其官方未发布 Packagist 包;唯一可靠方式是克隆 GitHub v4 分支源码并手动引入 Worker.php,同时确保启用 pcntl/posix、禁用 OPcache CLI 及满足 PHP ≥ 7.2 等硬性条件。
Workerman 不能(也不该)用安装 —— 那个包不是官方版,PHP 8+ 下必报错,且已多年未维护。
为什么
会失败
你执行这条命令后,Composer 实际拉下来的是一个叫
的第三方 fork 包,最后一次更新是 2018 年,不兼容 PHP 8.0+、不支持现代 Linux 信号(比如
)、类加载路径错乱。常见错误包括:
、
、
。
根本原因:官方 Workerman 项目没有
,也从未提交到 Packagist,它压根就不是为 Composer 设计的依赖包 —— 它是纯 PHP 编写的常驻进程框架,靠
动态加载,不走 PSR-4 自动加载流程。
别信“教程里写了就能跑”,很多旧文章没更新,照着做只会卡在启动阶段
哪怕
成功了,
也大概率不执行,status 显示
ThinkPHP/Laravel 项目里看似能装上,其实是靠
或
这类封装层间接引入,底层仍走手动加载逻辑
正确获取 Workerman 的唯一可靠方式
直接从 GitHub 官方仓库下载源码,只认
分支(稳定、PHP 7.2+ 支持、无协程强依赖);
分支含实验性协程特性,需额外装
,不适合生产环境。
Composer 2.9.6
Composer 2.9.6 是 PHP 生态中高效、稳定的依赖管理工具。此版本在性能与兼容性上进一步优化,改进了依赖解析算法,提升大型项目中的安装与更新速度。它支持并行下载任务,显著减少等待时间,并增强了与私有仓库及镜像源的交互稳定性。同时修复了多项命令行交互与内存使用相关的缺陷,确保在复杂依赖关系下依然可靠运行。无论是新项目初始化还是现有系统维护,Composer 2.9.6 都能为开发者提供流畅、精准的依赖管理体验。
下载
运行:
把整个
目录放进你的项目,例如放在
(仅为路径组织,非 Composer autoload 路径)
入口文件(如
)中写:
不需要
,也不需要
—— 所有类由
内部的自动加载器按需载入
PHP 环境必须满足的硬性条件
缺一不可,否则 worker 启动即退出、
显示空列表、
完全无响应。
PHP ≥ 7.2(推荐 8.0+),确认禁用
(某些 Docker 镜像默认开)
CLI 模式下必须启用
和
扩展:
,Ubuntu 用
,Alpine 用
关闭 CLI 模式 OPcache:
(否则热更新失效、代码改了不生效)
监听 1024 以下端口(如 80/443)时,要么加
,要么给 PHP 二进制文件授权:
长连接环境配置的关键点
Workerman 本身不提供“长连接配置项”,长连接能力来自协议选择和连接生命周期管理逻辑 —— 比如 WebSocket 协议天然支持,而普通 TCP 需手动保活。
WebSocket 服务只需初始化
时指定
协议,客户端用
即可维持长连
TCP 长连接要自己处理心跳:
发送 ping、
主动断连、监听
清理资源
数据库长连接不能靠
,要用
类封装复用连接,避免每个请求新建 MySQL 连接
别在
里做阻塞操作(如
、同步 HTTP 请求),会卡死整个进程;异步请用
或协程方案(需额外扩展)
最常被忽略的其实是信号权限和 OPcache CLI 设置 —— 很多人反复重装、换 PHP 版本,却没检查
是否真在 CLI 下生效,或者忘了关掉
。这些地方一错,整个框架就静默失败,连日志都不打。
composer require workerman/workermancomposer require workerman/workermanworkerman/workermanSIGUSR1Class 'Workerman\Worker' not foundUndefined constant SIGUSR1require_once(): Failed opening required 'vendor/autoload.php'composer.jsonspl_autoload_registercomposer installWorker::runAll()0 workerstopthink/think-workerworkerman/gateway-workerv4masterext-swoolegit clone -b v4 https://github.com/walkor/Workerman.gitWorkerman/vendor/workerman/start.phprequire_once __DIR__ . '/vendor/workerman/Worker.php';composer dump-autoloaduse Workerman\WorkerWorker.phpphp start.php statuskill -USR2safe_modepcntlposixphp -m | grep -E "pcntl|posix"sudo apt install php-pcntl php-posixapk add php82-pcntl php82-posixopcache.enable_cli=0sudosudo setcap 'cap_net_bind_service=+ep' /usr/bin/phpWorkerwebsocket://0.0.0.0:2000new WebSocket('ws://...')$connection->send()$connection->close()onClosemysql_connect()Workerman\MySQL\ConnectiononMessagesleep()Workerman\Lib\Timerpcntlopcache.enable_cli