Hyperf版本升级需按x/y/z版分级处理：x版重构需严格按指南操作，y版检查API变更，z版可直接更新但需回归测试；跨大版本须确认环境、修改依赖、转换注解、调整命名空间与方法签名、同步配置变动，并完成功能、性能、错误三类验证。
Hyperf版本升级不是简单执行composer update就能完事的，关键要看升级跨度——是小修小补（z版），还是功能迭代（y版），抑或架构重构（x版）。不同情况对应完全不同的处理逻辑和风险等级。
先判断版本类型再动手
Hyperf用x.y.z命名规则：
- x版（如v2→v3）：核心重构、API大量不兼容，必须严格按官方升级指南逐项操作，不能跳步
- y版（如v2.2→v2.3）：有公开API变更或删除，需检查监听器、中间件、AMQP消费者等是否受影响
-
z版（如v3.0.1→v3.0.5）：纯Bug修复或安全补丁，可直接运行
composer update hyperf/*，但建议仍做基础回归测试
跨大版本（x/y级）必须做的几件事
以v2.x升v3.x为例，这些动作缺一不可：
- 确认PHP版本≥8.1，Swoole≥5.0（v3.0起强制要求）
- 修改
composer.json中所有hyperf/*依赖为"3.0.*"，并加入"hyperf/engine": "^2.1.0" - 用
hyperf/code-generator批量转换Doctrine注解为PHP8 Attributes：php bin/hyperf.php code:generate -D app - 全局替换命名空间：
use Hyperf\Utils\Context→use Hyperf\Context\Context - 为所有事件监听器
process()方法显式声明:void返回类型 - AMQP消费者方法签名改为
consumeMessage(mixed $data, AMQPMessage $message): Result，返回Result::ACK或Result::REJECT
配置与结构变动要同步调整
新版常伴随目录或配置格式变化，容易遗漏：
- v3.0起
config/dependencies.php已移至config/autoload/dependencies.php，且去掉外层'dependencies' =>键名 - v2.0开始入口文件
bin/hyperf.php需在匿名函数第一行添加Hyperf\Di\ClassLoader::init(); - v1.1起
SWOOLE_HOOK_FLAGS常量必须定义，推荐设为SWOOLE_HOOK_ALL - v3.0不再自动加载
config/autoload下所有PHP文件，需确保关键配置（如cache.php）被正确引入
升级后验证不能只靠“能跑”
上线前必须覆盖三类验证：
- 功能回归：重点测RPC调用、数据库事务、队列消费、中间件链路、事件分发
-
性能基线：用
ab或wrk对比QPS、平均响应时间、内存占用，尤其关注协程上下文切换开销变化 - 错误捕获：触发已知异常路径（如数据库连接失败、Redis超时），确认错误页面、日志格式、监控上报仍正常
