Hyperf安装失败90%因环境未对齐，须按四层排查：PHP≥8.1且swoole启用协程；composer镜像三要素齐全并重写lock；runtime/storage/vendor权限匹配进程用户；端口无占用、扩展版本兼容。
Hyperf安装失败，90%不是框架问题，而是环境没对齐——先别重装，按顺序查这四层。
php -v 和 swoole --ri 是否达标
Hyperf 启动依赖 PHP 协程能力，不满足最低要求会直接静默失败或报 Segmentation fault：
- PHP 必须 ≥ 8.1（低于则
swoole协程不可用，Hyperf\Contract\ContainerInterface找不到） - 执行
php --ri swoole，确认输出里有support coroutines: enabled；若没有，说明加载的是旧版swoole.so或系统自带非协程版 - Windows 用户别硬编译，
docker-compose up -d拉官方镜像更稳（避免zlib/openssl缺失导致的无提示失败）
composer 镜像和 install 方式是否正确
卡在 Loading composer repositories 或 Resolving dependencies，基本是镜像配置失效或安装方式错误：
- 全局镜像必须用：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（repo.packagist键名、composertype 值、URL 末尾/三者缺一不可） - 验证是否生效：
composer config -g repo.packagist输出必须是完整 JSON：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"} - 已有项目必须执行
composer update --lock重写composer.lock，否则仍走原始 dist.url - 绝对不要
composer require hyperf/http-server—— Hyerf 必须用composer create-project初始化骨架，否则 DI 容器、注解扫描全跳过
runtime/storage/vendor 目录权限是否匹配进程用户
部署后报 Permission denied，本质是 Swoole 进程用户（如 www-data）没权限写入关键路径：
- 先查进程用户：
ps aux | grep -E "(swoole|hyperf)"，看USER列，不是 root，也不是你本地登录账户 - 确认
runtime/、storage/、vendor/bin/hyperf.php三处归属：ls -ld runtime storage vendor/bin/hyperf.php - 修复命令（以
www-data为例）：sudo chown -R www-data:www-data runtime storage+sudo chmod +x vendor/bin/hyperf.php - 已有权限错误后，必须清空
runtime/*（用目标用户执行：sudo -u www-data rm -rf runtime/*），否则残留只读文件继续报错
端口占用或扩展冲突是否阻塞启动
启动无响应、报 Address already in use [98] 或 Socket is closed(0)，多为资源抢占或扩展误启：
- 查端口占用：
sudo lsof -i :9501（默认端口）或netstat -tulnp | grep :9501；优先用php bin/hyperf.php stop，而非kill -9 -
Socket is closed(0)常因本地开了假 Redis（如 systemd 管理的redisd），但实际 Redis 服务未运行；停掉非标准服务，改用包管理器安装（如yum install redis） - Swow 用户需确认
extension=swow.so已写入php.ini；Swoole 用户注意版本兼容性（如 Hyperf 2.2 不支持 Swoole 5.x）
真正难排查的点，往往藏在“改完权限还报错”或“换源后依然卡住”——这时候不是漏步骤，而是某处路径没用目标用户操作（比如 rm -rf runtime 是 root 执行的，新生成文件又属 root），或者 composer.lock 里某个包的 dist.url 还是原始地址。盯住日志里第一个被拒的路径、第一个报错的类名、第一个没返回的命令，比盲目重装快得多。
