如何使用Composer安装Hyperf高性能框架

Hyperf不能用composer create-project直接安装成功，因官方已不推荐该方式；主因是hyperf-skeleton要求PHP≥8.1、强制依赖Swoole等扩展，且dev依赖易引发冲突。

如果你打算通过composer require hyperf/hyperf把Hyperf硬塞进一个现有项目，那么最好现在就停下来。这行不通。Hyperf并非一个可以随意安装的插件，它是一套完整的、有严格预设约定的骨架。从目录结构、启动流程到容器加载，都依赖这套初始约定。因此，composer create-project是官方唯一经过CI验证的、正确的项目入口方式。

为什么 composer create-project hyperf/hyperf-skeleton 常失败

安装卡住，很多时候并非网络或权限问题，根源在于官方骨架预设了硬性门槛：PHP >= 8.1、已启用ext-swoole扩展，并且composer >= 2.2。本地环境但凡有一项不达标——比如PHP版本过低，或者Swoole没装、版本不匹配（项目锁定了4.8.x而你装了5.0），都会在依赖解析阶段直接报错，提示类似：

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用户，这里有个明确的结论：官方并不支持在原生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"，这样可以防止Composer自动拉取不稳定的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后缀的开发版本。

启动前最容易被忽略的三件事

环境装好了，项目也创建了，但一启动就报“Class not found”？90%的情况是因为下面这三件事没检查。

• 入口文件路径：bin/hyperf.php文件的第一行必须是require dirname(__DIR__) . '/vendor/autoload.php';。少一个点、错写成../vendor或者使用了其他相对路径，都会导致容器根本无法启动。
• 核心容器绑定：config/autoload/dependencies.php这个文件里，有一行关于Hyperf\Contract\ContainerInterface的实现绑定（默认是Hyperf\Di\Container::class）。绝对不能删除它，这是框架运行的基石。
• 类映射更新：每次修改完配置文件或使用了新的注解（比如@AutoController），都必须手动执行一次composer dump-autoload -o。否则，PSR-4的类映射关系不会更新，注解扫描器就找不到你的类。

总的来说，Hyperf的启动逻辑非常直接和透明：一切从bin/hyperf.php开始，依赖vendor/autoload.php来加载所有类。它不像Lara vel那样有复杂的自动发现机制。这种设计的优点是清晰，但反过来也意味着，任何环节出了问题——路径错误、扩展缺失、类映射未更新——错误都会立刻暴露出来，没有任何缓冲或隐藏的余地。理解并处理好这些关键点，是顺利驾驭Hyperf的第一步。