Hyperf依赖版本冲突本质是Composer无法满足多包对同一扩展库（如psr/http-message）的不同版本要求，解决核心是明确约束、主动升降级、隔离冲突源；需用composer why-not、depends --tree等命令定位冲突，优先采用Hyperf官方推荐版本组合，避免混搭v2/v3组件，谨慎使用replace和--with-all-dependencies。
Hyperf 依赖版本冲突，本质是 Composer 在解析依赖时发现多个包要求同一扩展库（如 psr/http-message、guzzlehttp/psr7、symfony/* 等）的不同版本，无法同时满足，于是报错或安装失败。解决核心在于明确约束、主动降级/升级、隔离冲突源，而非盲目删锁文件或强制更新。
查看真实冲突来源
运行以下命令，让 Composer 显式告诉你哪几个包在“打架”：
-
composer why-not vendor/package:version（例如composer why-not psr/http-message:^2.0）→ 查谁阻止你装这个版本 -
composer depends --tree psr/http-message→ 查哪些包直接或间接依赖它，及其要求的版本范围 -
composer show --tree hyperf/framework→ 看 Hyperf 主包实际拉了哪些子组件及版本
优先使用 Hyperf 官方推荐版本组合
Hyperf 各大版本对 PHP、Swoole、Composer 包有明确兼容矩阵。不要自行混搭：
- v3.1.x 要求
php >=8.1，推荐搭配hyperf/utils ^3.1、hyperf/http-server ^3.1，不建议强行引入 v2.x 的组件 - 所有 Hyperf 官方组件都发布在 Packagist 的 hyperf 命名空间下，优先用它们，少用第三方适配包
- 升级前先查 GitHub Release 页面 的 breaking changes 和 upgrade guide
精准锁定关键依赖版本
若必须引入某个非 Hyperf 官方包（如 spatie/laravel-permission），又和 Hyperf 冲突，可手动指定兼容版本：
- 在
composer.json的require中显式写入稳定且被验证过的版本："psr/http-message": "^1.0 || ^2.0"（如果双方都支持） - 用
replace字段声明替代关系（慎用）："replace": { "guzzlehttp/psr7": "self.version" }，适用于你已用hyperf/http-message替代了原生 PSR7 实现 - 临时禁用冲突检查（仅调试）：
composer update --with-all-dependencies，但上线前务必还原并修复根本问题
清理缓存与重装策略
不是所有冲突都靠删文件解决，但某些场景下这步不可少：
- 删掉
vendor/、composer.lock，再执行composer install（确保composer.json已修正） - 清空 Composer 全局缓存：
composer clear-cache，避免旧包元数据干扰解析 - 检查是否启用了
minimum-stability或prefer-stable配置，不稳定版本容易引发隐性冲突
不复杂但容易忽略：Hyperf 的很多组件（如 hyperf/database）内部已封装了对 doctrine/dbal、eloquent 的适配逻辑，直接 require 同类包反而会打破封装契约。遇到冲突，先想“是不是重复引入了？”而不是“怎么让它妥协”。
