推荐用 composer create-project 安装 Hyperf，因其自带官方脚手架、默认配置和基础服务；手动写 composer.json 易漏 peer 依赖致启动失败；需确保 PHP 8.0+、Composer 2.2+、Swoole 4.8+；组件如 http-server 已预装，新增应选可选组件并用 update 升级。
直接用 composer create-project 装，别手动生成 composer.json
Hyperf 官方不推荐从空项目开始手动配依赖，create-project 会拉取官方维护的脚手架模板，自带合理默认配置、目录结构和基础服务注册。手动写 composer.json 极易漏掉 hyperf/framework 的必需 peer 依赖（比如 psr/container 版本冲突），导致后续 php bin/hyperf.php start 启动失败。
实操建议：
- 确保已安装 PHP 8.0+ 和 Composer 2.2+（低于 2.2 可能因插件兼容问题卡在
hyperf/composer-plugin） - 运行：
composer create-project hyperf/hyperf-skeleton myapp
- 进目录后立刻执行：
cd myapp && php bin/hyperf.php start
，验证是否能跑通 HTTP 服务（默认监听0.0.0.0:9501）
装完发现 bin/hyperf.php 权限不对或报 Class not found
常见于 Windows + WSL 混合环境，或 Git clone 后未触发 Composer 自动加载重生成。Hyperf 的命令入口依赖 autoload_files 和 classmap 两层自动加载，任一缺失都会让 bin/hyperf.php 找不到核心类。
实操建议：
- 先删掉
vendor/autoload.php和vendor/composer/autoload_*.php，再运行composer dump-autoload -o
- 检查
bin/hyperf.php开头是否包含#!/usr/bin/env php，Windows 用户若用 CMD 运行需改用php bin/hyperf.php start
，不能直接bin/hyperf.php start - 确认
composer.json中"autoload"下的"psr-4"映射没被意外注释或改错路径
想换 PHP 版本或切到 Swoole 扩展，但 composer install 一直失败
Hyperf 对 PHP 和 Swoole 有硬性版本要求：PHP 必须 ≥ 8.0（7.4 已彻底弃用），Swoole ≥ 4.8.0（且需启用 sockets 和 openssl）。Composer 安装时会调用 hyperf/composer-plugin 做环境校验，不满足就中断并报类似 Your requirements could not be resolved 的模糊错误。
实操建议：
- 运行
php -v
和php --ri swoole
确认版本和扩展状态 - 如果 Swoole 是源码编译安装，检查
php.ini是否加载了正确路径的swoole.so（尤其注意 CLI 和 FPM 的php.ini可能不同） - 临时绕过校验（仅调试用）：
COMPOSER_IGNORE_PLATFORM_REQS=1 composer install
，但上线前必须修复真实环境，否则运行时崩溃
为什么 composer require hyperf/http-server 不起作用？
因为 hyperf-skeleton 默认已预装 hyperf/http-server 及其所有依赖（包括 hyperf/server、hyperf/contract 等）。单独 require 不仅冗余，还可能触发版本降级或冲突——Composer 会试图匹配你指定的版本号，而骨架里锁的是经过测试的组合版本。
实操建议：
- 新增组件一律查文档确认是否属于「可选组件」，比如
hyperf/database或hyperf/redis才需要require - 升级已有组件用
composer update hyperf/http-server
，而非require - 修改
composer.json后务必运行composer dump-autoload -o，否则新引入的类可能无法被自动加载识别
Hyperf 的组件耦合度比表面看起来高，一个 require 动作背后可能牵扯十几个包的版本对齐，盲目操作容易把 vendor 弄成“依赖沼泽”。最稳的方式永远是跟着骨架模板走，只在明确需要时加可选组件。
