hyperf不能用composer create-project直接安装成功，因官方已不推荐该方式；主因是hyperf-skeleton要求php≥8.1、强制依赖swoole等扩展，且dev依赖易引发冲突。
composer create-project 是唯一被 CI 验证过的入口，别用 composer require hyperf/hyperf 往已有项目里硬塞——Hyperf 不是插件，是骨架，目录结构、启动流程、容器加载全依赖预设约定。
为什么 composer create-project hyperf/hyperf-skeleton 常失败
不是网络问题，也不是权限问题，而是官方骨架默认要求：PHP >= 8.1、已启用 ext-swoole、且 composer >= 2.2。本地 PHP 版本低、Swoole 没装或版本不匹配（比如装了 Swoole 5.0 但项目锁死在 4.8.x），都会卡在依赖解析阶段，报错类似：
Your requirements could not be resolved to an installable set of packages.
- 运行
php -v确认 ≥ 8.1（Hyperf v3.x 生产环境最低要求） - 运行
php --ri swoole查看输出中support async_redis => enabled是否为enabled；若为disabled，说明 php.ini 里漏了extension=swoole.so或被disable_functions拦截 - Windows 用户直接放弃 CLI 安装：官方不支持 Windows 下的
ext-swoole，必须用 WSL2 或 Docker
安装时必须加的关键参数
跳过 dev 依赖和测试链能大幅降低冲突概率，尤其适合首次验证能否跑起来：
- 用
--no-dev --prefer-dist减少依赖树深度：composer create-project hyperf/hyperf-skeleton my-app --no-dev --prefer-dist - 进项目后删掉
docker/和test/目录（它们带一堆 require-dev） - 改
composer.json中的"minimum-stability": "stable"，防止自动拉dev-main分支 - 再执行一次
composer install，成功率明显提升
生产环境必须锁版本，不能信默认 latest
官方 hyperf-skeleton 默认拉的是最新 stable tag，但 CI 流水线可能还没覆盖所有 patch 版本。线上部署必须显式指定稳定小版本：
- 一步到位：用
composer create-project hyperf/hyperf-skeleton:3.2.0 my-app --prefer-dist -n - 或先创建再锁定：
composer create-project hyperf/hyperf-skeleton my-app→ 进入目录执行composer require hyperf/hyperf:v3.2.0 - 验证是否生效：
composer show hyperf/hyperf输出中versions行应显示3.2.0，而非dev-main或带-dev后缀的版本
启动前最容易被忽略的三件事
90% 的 “Class not found” 报错都源于这三点没检查：
-
bin/hyperf.php第一行必须是require dirname(__DIR__) . '/vendor/autoload.php';—— 少一个点、路径写成../vendor或用了相对路径，容器就起不来 -
config/autoload/dependencies.php里不能删掉Hyperf\Contract\ContainerInterface对应的实现绑定（默认是Hyperf\Di\Container::class） - 每次改完配置或注解，必须手动执行
composer dump-autoload -o，否则 PSR-4 映射失效，@AutoController注解根本不会被扫描到
Hyperf 的启动逻辑非常“直给”：从 bin/hyperf.php 开始，靠 vendor/autoload.php 加载一切，不走 Laravel 那套自动发现。任何环节路径错、扩展缺、类映射没刷，错误就立刻暴露，没有隐藏缓冲。
