Workerman 不通过 Composer 安装，因其无 composer.json 且未发布到 Packagist；正确方式是 GitHub 克隆 v4 分支源码，手动引入 Worker.php 并确保 PHP ≥7.2、启用 pcntl/posix 扩展、禁用 OPcache CLI 模式。
Workerman 不通过 Composer 安装 —— 它是纯 PHP 编写的常驻进程框架，没有 composer.json 依赖声明，也不发布到 Packagist。直接用 Composer 安装会失败或拉下错误包（比如有人误装了名字相近的 workerman/workerman 镜像包，但那不是官方版）。
为什么 composer require workerman/workerman 会出错
官方 Workerman 项目从未在 Packagist 注册，workerman/workerman 这个包名实际指向一个非官方、已多年未更新的 fork（最后一次更新在 2018 年），且不兼容 PHP 8+ 和现代 Linux 发行版。运行时大概率报错：Class 'Workerman\Worker' not found 或 Undefined constant SIGUSR1。
正确路径是手动下载源码 + 合理部署，而非依赖管理器注入。
如何正确获取并初始化 Workerman
从 GitHub 官方仓库克隆或下载 ZIP 是唯一可靠方式。注意区分分支：生产环境务必用 v4 分支（PHP 7.2+ 支持，稳定维护），别用 master（含实验性协程特性，需额外装 ext-swoole）。
- 执行
git clone -b v4 https://github.com/walkor/Workerman.git，得到完整源码 - 把
Workerman/目录复制进你的项目，例如放在vendor/workerman/（仅为组织方便，非 Composer 自动加载路径） - 入口文件（如
start.php）里用require_once加载核心：require_once __DIR__ . '/vendor/workerman/Worker.php';
- 不需要
composer dump-autoload，Workerman 所有类都靠Worker.php中的spl_autoload_register动态加载
PHP 环境必须满足的硬性条件
Workerman 对扩展和系统调用很敏感，缺一不可：
- PHP 版本 ≥ 7.2（
v4分支最低要求），推荐 8.0+；禁用safe_mode（已废弃，但某些旧 Docker 镜像仍默认开启） - 必须启用
pcntl（进程控制）和posix（系统接口）扩展 —— Ubuntu/Debian 下装php-pcntl和php-posix，Alpine 用apk add php82-pcntl php82-posix - Linux 系统需允许非 root 用户创建监听 socket（开发机没问题；生产环境若用
80/443，要么加sudo，要么用setcap 'cap_net_bind_service=+ep' /usr/bin/php） - 禁用
opcache.enable_cli=1（CLI 模式下开启 OPcache 可能导致热更新失效）
启动与调试常见卡点
启动后没反应、status 显示 0 个 worker、kill -USR2 无响应 —— 多半是权限或信号配置问题：
- 不要在 Docker 容器里用
--init或tini之外的方式启动，否则pcntl信号会被拦截；建议加ENTRYPOINT ["tini", "--"] -
Worker::$pidFile = __DIR__ . '/workerman.pid';必须可写，否则多实例无法管理 - 调试时加
-d参数：php start.php start -d，它会输出 worker 启动日志到Workerman.log（默认在当前目录） - 检查
netstat -tlnp | grep :2345（假设监听 2345）确认端口是否真被占用；若显示127.0.0.1:2345而不是*:2345，说明$worker->listen = 'tcp://0.0.0.0:2345'写成了127.0.0.1，容器外连不上
Workerman 的“安装”本质是环境校准 + 源码集成，不是包管理流程。很多人卡在以为要 Composer 化，结果浪费半天查 autoload 错误 —— 记住：它不走 PSR-4，不依赖 vendor/autoload.php，所有路径都得自己控。
