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