必须用 composer create-project 初始化全新项目，因 Hyperf 依赖预设骨架、Swoole 扩展（≥4.8）、PHP ≥8.0 及严格 autoload 规则；直接 require 会导致类找不到或启动失败。
用 composer create-project 安装 Hyperf 时为什么总卡在 autoload？
Hyperf 不是靠 composer require hyperf/hyperf 直接加进现有项目就能跑的框架——它依赖特定的项目骨架、PHP 扩展（如 swoole）、以及严格对齐的 autoload 规则。直接 require 会导致 Class not found 或启动时报 Cannot use Hyperf\Contract\ContainerInterface。
- 必须使用
composer create-project初始化全新项目，官方骨架已预设好psr-4映射和bin/hyperf.php入口 - 安装前确认 PHP 版本 ≥ 8.0，且已启用
swoole（需 4.8+）和openssl、json、mbstring - 若国内网络慢，先执行
composer config -g repo.packagist composer https://packagist.phpcomposer.com（或切换为阿里云镜像）
hyperf-skeleton 的版本怎么选？dev-main 还是 v3.1.x？
Hyperf 当前稳定主线是 v3.1.x（截至 2024 年中），dev-main 是开发分支，含未验证的协程组件变更与 Swoole 5 兼容尝试，不建议生产环境使用。
- 装稳定版：运行
composer create-project hyperf/hyperf-skeleton project-name ^3.1 - 想试新特性（如 HTTP/3 支持）才用
dev-main，但要同步改php.ini开启swoole.enable_coroutine=Off避免死锁 -
hyperf-skeleton默认不含数据库组件，需手动composer require hyperf/database并配置config/autoload/databases.php
安装后启动报错 swoole extension not loaded 怎么办？
这不是 Composer 的问题，而是 PHP 环境缺失 Swoole 扩展。Hyperf 启动时会强制检测 extension_loaded('swoole')，失败直接退出，不会降级到 FPM 模式。
- Linux/macOS 下优先用
pecl install swoole（注意 PHP CLI 和 Web Server 使用的php.ini可能不同） - Windows 用户只能用 WSL2，原生 Windows 不支持 Swoole
- 验证是否生效：运行
php --ri swoole，输出中要有Version => 4.10.0类似行；若提示Extension 'swoole' not present，检查php.ini是否漏加extension=swoole
微服务场景下，多个 Hyperf 服务共用一套 Composer 依赖合理吗？
不合理。Hyperf 服务间应保持独立 vendor 目录。强行共享会导致 composer.lock 冲突、版本漂移、调试时无法定位真实调用栈。
- 每个服务单独
composer install，哪怕都 requirehyperf/rpc，也要各自解析依赖树 - 公共逻辑抽成私有包（如
company/common-contract），发布到私有 Packagist（如 Satis 或 Toran Proxy），再由各服务composer require - CI/CD 中禁用
composer update，只允许composer install --no-dev --prefer-dist，避免构建环境差异
composer create-project hyperf/hyperf-skeleton order-service ^3.1 cd order-service composer require hyperf/rpc hyperf/consul
Hyperf 的依赖边界很清晰，但一旦跨服务共享 vendor，Swoole 的全局状态（如协程上下文、连接池）就会互相污染——这点容易被忽略。
