Hyperf 各版本差异显著：v2.x 稳定成熟，适配 Swoole 4.x/PHP 7.4+，适合传统微服务；v3.x 拥抱 PHP 8+，以 Attributes 替代注解，性能提升15%；v4.x 轻量化、云原生导向，支持 Swoole 5.x/PHP 8.2+，强化 OpenTelemetry 与 K8s 集成。
Hyperf 的版本迭代较快，不同大版本（如 v2.x、v3.x、v4.x）在架构设计、核心组件、开发体验和底层依赖上存在显著差异。选对版本、理解演进逻辑，能避免踩坑、提升开发效率和长期可维护性。
v2.x：稳定成熟，适合传统微服务与中大型项目
v2.x 是 Hyperf 最广泛落地的版本，基于 Swoole 4.x + PHP 7.4+，以“高性能 + 高兼容”为核心定位。其 DI 容器、AOP、注解路由、协程 MySQL/Redis 客户端等已非常成熟。大量企业级项目（尤其电商、IM 后台）仍在使用该版本。升级路径清晰，文档齐全，生态组件（如 hyperf-admin、hyperf-elasticsearch）支持完善。
- 推荐场景：已有 Laravel/Symfony 迁移项目、需强稳定性保障、团队熟悉 Swoole 协程模型
- 注意点：不支持 PHP 8.2+ 的部分新语法；Swoole 5.x 兼容需手动适配；配置方式偏 YAML/PHP 数组，灵活性略低于 v3
v3.x：架构重构，拥抱 PHP 8+ 与现代语言特性
v3.x 是一次重要升级，全面适配 PHP 8.0+（要求最低 PHP 8.0），引入 Attributes 替代传统注解（@GetMapping → #[GetMapping]），重写 DI 容器以支持属性注入、构造函数参数自动解析，并优化协程生命周期管理。配置统一为 PHP 原生返回数组，更易 IDE 支持和类型推导。
- 关键改进：原生 Attributes 提升类型安全与 IDE 友好度；容器性能提升约 15%；HTTP Server 默认启用 HTTP/2 支持
- 迁移建议：新项目首选；老项目升级需批量替换注解语法、检查第三方组件兼容性（如 hyperf/swagger 已同步支持）
v4.x：轻量化与云原生导向，聚焦核心能力收敛
v4.x（当前最新稳定版）进一步精简内核，移除部分历史兼容层（如旧版 JSON-RPC 实现），默认集成 OpenTelemetry、强化 Docker/K8s 友好配置（如自动读取 K8s Downward API），并提供更细粒度的组件开关机制（例如可单独禁用 view 或 translation 组件）。同时正式支持 Swoole 5.x 和 PHP 8.2+，协程调度器更稳定。
- 适用场景：云原生部署、Serverless 环境、需要最小化依赖的边缘服务
- 操作提示：初始化项目推荐使用 hyperf-skeleton v4 脚手架；配置项命名更统一（如 server.settings 替代 v2 的 server.setting）；日志默认接入 PSR-3 标准实现，便于对接 Loki/Promtail
功能演进中的实用技巧
跨版本开发时，几个高频技巧可显著降低适配成本：
- 注解迁移自动化：使用 php-cs-fixer 配合自定义规则，批量将 @xxx 注解转为 #[xxx] 属性（v2→v3）
- 配置兼容桥接：在 v3/v4 中保留 v2 风格配置文件名（如 config/autoload/database.php），通过 ConfigProvider 映射到新结构，渐进式切换
- 协程上下文隔离验证：利用 Co::getUid() + ApplicationContext::getContainer() 在中间件中打印协程 ID 与容器实例哈希，快速定位内存泄漏或上下文污染问题
- 组件按需加载：v4 推荐在 composer.json 中只 require 核心包（hyperf/framework），其他如 hyperf/database 按需安装，减少 autoload 冗余
