Hyperf v3.x 升级需满足PHP≥8.1、Swoole≥5.0，注解全面迁移至PHP 8 Attributes，核心类签名强制类型化，配置路径与依赖结构按新规范调整。
Hyperf 架构升级不是简单改个版本号，核心在于兼容性控制、代码适配和运行环境对齐。v2.x 到 v3.x 是一次重大演进，PHP 8 Attributes 替代 Doctrine 注解、类型系统强化、中间件与监听器签名变更等都直接影响现有项目能否平稳过渡。
PHP 与 Swoole 环境必须提前达标
Hyperf v3.x 强制要求 PHP ≥ 8.1，Swoole ≥ 5.0（官方推荐 5.1+）。低于此版本会直接启动失败或触发未定义行为。
- 执行
php -v和php --ri swoole确认当前版本 - 若需升级 Swoole，建议通过源码编译（避免 PECL 安装的版本混乱），并确保启用
openssl、http2等生产必需扩展 - 入口文件
bin/hyperf.php中必须定义SWOOLE_HOOK_FLAGS，且值为SWOOLE_HOOK_ALL
注解全面迁移到 PHP 8 Attributes
v3.0 起彻底移除 Doctrine Annotations 支持，所有控制器、路由、中间件、事件监听等注解必须转为原生 Attributes。
- 批量替换示例：
/** @Controller(prefix="/api") */→#[Controller(prefix: '/api')]/** @GetMapping(path="info") */→#[GetMapping(path: 'info')] - 推荐使用官方工具自动转换：
composer require hyperf/code-generatorphp bin/hyperf.php code:generate -D app - 自定义注解需重写为 Attribute 类，并继承
Attribute，注意#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]的目标声明
关键类与方法签名强制类型化
v3.x 对框架核心接口做了严格类型约束，不补全将导致 DI 失败或运行时报错。
-
Context命名空间从Hyperf\Utils\Context变更为Hyperf\Context\Context - 所有事件监听器的
process()方法必须声明返回类型void：public function process(object $event): void - AMQP 消费者从 v3.1 起，
consumeMessage()返回类型必须为Result枚举（Result::ACK/Result::NACK/Result::REQUEUE） - 数据库模型若使用 Eloquent，建议配合
regenerate-models.php工具重生成，确保属性类型与注解同步
配置与依赖结构需按新版规范调整
v3.x 统一了配置加载路径和依赖注入注册方式，旧版结构会引发容器无法解析等问题。
-
config/dependencies.php必须移至config/autoload/dependencies.php，且去掉外层'dependencies' =>键 -
config/container.php需使用DefinitionSourceFactory初始化，不再手动构造Container -
composer.json中 Hyperf 包约束改为："hyperf/*": "^3.0"，并显式声明"hyperf/engine": "^2.1" - 移除已废弃组件如
hyperf/async-queue（由hyperf/amqp或hyperf/kafka替代）
