Hyperf安装失败多因环境配置问题，需检查PHP版本≥7.4及swoole、redis等扩展是否启用，确认CLI与Web端php.ini路径一致，清除disable_functions中pcntl、proc_open等限制，并调整扩展加载顺序确保redis等前置扩展序号小于swoole。
Hyperf安装失败，多数不是框架本身的问题，而是环境配置或扩展依赖没到位。核心盯住三点：PHP版本与扩展、CLI配置路径一致性、禁用函数限制。
检查PHP环境是否达标
Hyperf 2.2+ 要求 PHP ≥ 7.4，且必须启用以下扩展：
- swoole（v4.5+，注意不是 swoole_async）
- redis（ext-redis，不是 predis 或 phpredis 的纯 PHP 实现）
- openssl、json、mbstring、curl、pcntl、posix 等基础扩展
执行 php -v 和 php -m | grep -E "(swoole|redis|pcntl)" 确认；若 redis 显示缺失，但网页 phpinfo() 里有，说明 CLI 模式没加载对的 php.ini —— 这是高频卡点。
确认 CLI 使用的 php.ini 路径
网页和命令行可能加载不同配置文件：
- 网页端看
phpinfo()中 “Loaded Configuration File” - CLI 端运行
php --ini查看实际加载路径 - 若两者不一致，把 Web 端生效的 php.ini 复制覆盖 CLI 对应路径下的配置文件（例如宝塔用户常需复制到
/www/server/php/74/etc/php.ini）
改完记得重启 PHP 服务（如宝塔面板内“重载配置”或 systemctl restart php-fpm）。
解除 PHP 禁用函数限制
Hyperf 启动依赖 pcntl、proc_open 等函数，常见报错如 pcntl_fork() has been disabled：
- 打开 CLI 对应的 php.ini，找到
disable_functions行 - 删掉其中的
putenv, pcntl_signal, proc_open, pcntl_wait, pcntl_fork - 保存后再次
php --ini验证，再试composer create-project hyperf/hyperf-skeleton
处理扩展加载顺序问题
CentOS 或手动编译环境容易出现 “扩展已装却报 missing” —— 原因是 swoole 加载太早，压住了 redis 等依赖：
- 检查
php.ini或ext/目录下扩展配置文件（如20-redis.ini、30-swoole.ini） - 确保 redis、openssl、json 等前置扩展的 ini 文件名数字序号 小于 swoole 的（例如用
10-redis.ini和40-swoole.ini） - 改完重启 PHP，再用
php -m确认顺序是否生效
不复杂但容易忽略。理清 CLI 配置路径、禁用函数、扩展顺序这三环，90% 的安装失败都能当场解决。
