Hyperf 必须通过 composer create-project hyperf/hyperf-skeleton 安装，因其预置兼容组件与锁定 Swoole 版本；直接 require hyperf/hyperf 易导致版本错配、缺核心包或启动失败。
Hyperf 不能通过 composer create-project 一键安装成功，因为官方不提供带完整运行环境的 starter 模板；直接 composer require hyperf/hyperf 会装错版本、缺核心组件、启动报错——这是最常卡住的起点。
为什么 composer create-project hyperf/hyperf-skeleton 是唯一可靠入口
Hyperf 官方只维护 hyperf-skeleton 这个最小可运行骨架，它预置了 hyperf/framework、hyperf/server、hyperf/config 等必需包，且锁定了兼容的 Swoole 版本（如 v5.1.x 对应 Swoole 4.8+）。跳过它直接 require hyperf/hyperf 会拉取 dev-main 或高版本，而这些版本默认依赖 Swoole 5.0+，但多数生产环境还跑在 4.8 上。
- 必须用
composer create-project hyperf/hyperf-skeleton，别手贱删掉composer.json里"hyperf/framework"这行再重 require - 如果要指定 PHP 版本（如 8.1），加
--stability=stable --prefer-dist，否则可能装到 alpha 版本 - 执行后立刻跑
php bin/hyperf.php start，看到Swoole http server started才算真正通了
composer require 增加组件时，哪些包必须配对安装
Hyperf 的模块高度解耦，但很多功能不是装一个包就完事。比如加 Redis 支持，只装 hyperf/redis 不行，还得配 hyperf/cache 和 hyperf/config 的对应配置段；漏掉 hyperf/utils，连 Coroutine::create() 都会报 undefined function。
- 加数据库：必须同时装
hyperf/db+hyperf/database+ 对应驱动（如hyperf/mysql），缺任一都会在Db::query()时报Class not found - 加注解路由：装
hyperf/http-server后，还得确认config/autoload/annotations.php里'scan' => ['paths' => ['app'] ]已启用，否则@GetMapping完全不生效 - 加协程 HttpClient：
hyperf/http-client要求hyperf/utils≥ 3.1，旧项目升级时容易因utils版本低导致HttpClientFactory构造失败
常见报错：Swoole 扩展未加载 / 版本不匹配
Composer 装完，php bin/hyperf.php start 报 Class 'Swoole\Http\Server' not found 或 SWOOLE_VERSION mismatch，说明 PHP CLI 环境没加载 Swoole，或版本和 Hyperf 锁定的不一致。
- 先运行
php --ri swoole，确认输出里有Version => 4.8.12这类信息；没有就去编译安装 Swoole，别指望pecl install swoole默认装对版本 - 检查
php.ini是否包含extension=swoole.so，且该文件被 CLI 加载（php -i | grep 'Loaded Configuration File'） - Hyperf v3.1 锁死 Swoole 4.8.x，若已装 5.0.x，要么降级 Swoole，要么改
composer.json中hyperf/framework为^3.2.0（需同步验证其他包兼容性）
Hyperf 的“高性能”前提是 Swoole 扩展稳定、配置项没被覆盖、协程上下文没泄露——这些没法靠 Composer 自动搞定，装完骨架后第一件事，是看 var/log/hyperf.log 里有没有 Coroutine context lost 或 Connection refused 这类线索，而不是急着写业务代码。
