composer安装Hyperf框架教程_微服务架构下的依赖管理【指南】

必须用 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 HyperfContractContainerInterface。

• 必须使用 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，哪怕都 require hyperf/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 的全局状态（如协程上下文、连接池）就会互相污染——这点容易被忽略。