Composer require workerman/workerman 失败或卡住主因是 Workerman 依赖 pcntl/posix 等系统扩展而非纯 PHP 包，安装成功但运行时报错如 undefined function pcntl_fork() 或 Autoloader.php 找不到；需先启用 PHP CLI 扩展、用 Linux/WSL2 环境、优先 create-project、配国内镜像源并检查端口与权限。
为什么 composer require workerman/workerman 会失败或卡住
Workerman 不是纯 PHP 包，它依赖系统级扩展（如 pcntl、posix）和命令行环境，而 Composer 只负责下载代码、处理 autoload —— 它不检查扩展是否启用、不启动守护进程、也不管你有没有权限执行 php start.php start -d。常见报错其实是“安装成功但运行报错”，比如：Call to undefined function pcntl_fork()，或者 require(): Failed opening required 'Workerman/Autoloader.php'（路径没加载对）。
实操建议：
- 先确认 PHP CLI 模式已启用关键扩展：
php -m | grep -E "pcntl|posix|event|openssl"；缺哪个就去php.ini解开对应extension=行注释 - 别用 Windows CMD 直接跑 Workerman（尤其旧版），优先用 WSL2 或 Linux 服务器；Windows 用户必须用 Git Bash / PowerShell + 确保
pcntl在 PHP 8.1+ 上通过pecl install pcntl编译安装（官方不提供 Windows DLL） -
composer create-project workerman/workerman比require更稳妥——它自带完整骨架和start.php入口，避免 autoload 配置遗漏
workerman/workerman 和 workerman/websocket 的区别与选型
很多人装完 workerman/workerman 发现没法直接写 WebSocket 服务，是因为核心包只提供底层事件循环和 Worker 进程管理，WebSocket 协议支持是独立实现的。
实操建议：
- 要纯 TCP/UDP 长连接（如 IM、游戏网关）：只装
workerman/workerman就够了 - 要标准 WebSocket 通信（浏览器直连）：必须额外
composer require workerman/websocket，它提供Websocket\Connection和握手解析逻辑 - 注意版本对齐：
workerman/websocket v4.x只兼容workerman/workerman v4.x；混用 v3/v4 会导致class not found或onMessage不触发 - 别试图用
workerman/thinkphp这类封装包替代原生集成——它们常锁死 Workerman 版本且隐藏进程模型细节，出问题更难定位
如何让 Composer 安装更快、更稳定（针对国内环境）
Workerman 的 GitHub 仓库在海外，composer install 默认走 packagist.org → GitHub，国内 DNS 污染和连接不稳定会导致超时、重试、甚至退回到 zip 下载模式（更慢）。
实操建议：
- 全局换镜像源：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（已停用）→ 改用https://mirrors.aliyun.com/composer/或https://packagist.laravel-china.org - 加
--prefer-dist强制走压缩包而非 git clone：composer require workerman/workerman --prefer-dist，减少网络交互次数 - 删掉
vendor后手动执行git clone https://github.com/walkor/Workerman.git vendor/workerman/workerman再composer dump-autoload，适合反复调试时跳过 Composer 解析环节 - 禁用插件加速：
composer config -g disable-tls true（仅内网可信环境）可省掉证书验证耗时
安装后运行报 Permission denied 或 Address already in use
Workerman 启动时默认监听 0.0.0.0:2346，失败通常不是 Composer 的锅，而是端口、权限或残留进程问题。
实操建议：
-
sudo lsof -i :2346或netstat -tuln | grep :2346查端口占用；别盲目改端口，先杀掉残留php start.php进程 - 开发机上避免用
root启动，改用非特权端口（如8080）：php start.php start -d -p 8080 - Linux 下如果提示
Permission denied且确定没被占，检查 SELinux 是否启用：getenforce，临时关闭用setenforce 0（生产环境需配策略） - Workerman v4 要求 PHP >= 7.2.5，但某些 CentOS 自带 PHP 7.2.24 仍可能因
stream_socket_server权限限制失败——换用php -v显示为 “cli” 模式的二进制路径，别用 Apache 模块的 php
Workerman 的“高性能”不来自 Composer 配置，而来自进程模型和事件驱动设计；装得再快，没开 pcntl 或用错启动方式，照样单进程阻塞。真正卡点永远在 PHP 扩展、系统权限、端口生命周期这三个地方。
