<p>升级 Hyperf 2.2 到 3.0 遇依赖冲突时，应使用 composer-dependency-analyzer 定位隐性跨版本共存问题，重点清理所有 hyperf/* 的 ^2.x 组件、验证 PHP ≥ 8.1 和 Swoole ≥ 5.0 环境，并检查 require-dev 中的测试工具链冲突。</p>
Hyperf 2.2 升级到 3.0 时遇到依赖冲突，不是“版本没对齐”那么简单，而是 Composer 已穷举所有组合后确认无解——composer-dependency-analyzer 可帮你跳过报错表象，直接定位谁在拉旧包、谁在卡新包。
用 composer-dependency-analyzer 替代 composer why-not 查深层隐性冲突
官方 composer why-not 能定位一级阻塞，但很多 v2/v3 混搭问题藏在 require-dev 或私有 SDK 的子依赖里。composer-dependency-analyzer 会扫描整个依赖树，标出所有跨大版本共存的包（比如同时存在 hyperf/utils:^2.2 和 hyperf/utils:^3.1），并高亮“同一包被多个路径以不兼容约束拉入”的节点。
- 安装：运行
composer global require composer-dependency-analyzer/composer-dependency-analyzer - 执行：在项目根目录运行
composer-dependency-analyzer --conflict-only，它只输出冲突路径，不刷无关信息 - 重点关注输出中带
hyperf/前缀却指向^2.x的行——这些就是你手动删过又偷偷回来的 v2 组件
hyperf/* 组件混用是冲突主因，必须全量清理
v3.0 不接受任何 v2.x 的官方组件，哪怕只是 hyperf/testing 或 hyperf/cache 拉了一个 v2 版本，也会让 hyperf/framework 启动失败。这不是警告，是硬性限制。
- 检查当前装了哪些 hyperf 包：
composer show hyperf/*，确认每项都落在^3.0范围内 - 删掉所有非
hyperf/命名空间下却提供相同能力的包（如spatie/laravel-permission若与hyperf/auth功能重叠，优先用后者） - 特别注意
hyperf/engine：v3.0 必须是^2.1.0，不是^1.x；若composer.json里没显式声明，它可能被其他包拖成旧版
PHP 8.1+ 和 Swoole 5.0+ 约束未满足时，composer-dependency-analyzer 会误报“无冲突”
该工具只分析 PHP 包依赖，不校验平台要求。如果 composer.json 里写了 "php": "^8.1"，但本地 php -v 是 8.0，Composer 会静默降级所有需要 8.1+ 的包（比如 hyperf/http-server），导致实际装的是阉割版 v3，后续才爆各种 Attribute 不识别或 ConnectionInterface 找不到。
- 先验证环境：
php -v和php --ri swoole，确保 PHP ≥ 8.1、Swoole ≥ 5.0 - 若环境不达标，
composer-dependency-analyzer输出的“clean”结果不可信——它看到的是降级后的依赖图，不是你想要的 v3 正常图 - 不要加
--ignore-platform-reqs强装，这会让hyperf/db-connection的类型声明失效，运行时报TypeError而非启动失败
最易被忽略的是 require-dev 中的测试工具链：phpunit/phpunit 9.x 会拉 symfony/event-dispatcher 5.x，而 hyperf/v3 默认要 6.x，这种冲突不会出现在 Problem 1 里，但 composer-dependency-analyzer 能把它揪出来——升级前务必清点 dev 依赖，别让测试包拖垮主框架。
