Hyperf 版本计划与生命周期管理指南：版本规则、支持策略与升级实践

后端Web框架微服务RPC框架异步编程【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/hyperf/hyperf点击查看免费下载Hyperf 作为一个以协程为核心的高性能 PHP 框架其版本迭代遵循一套公开、可预期的计划每周固定节奏发布版本、以 x.y.z 语义化规则划分兼容性边界、并通过主流支持—安全维护—停止维护三级状态管理每个版本的生命周期。本文基于仓库中 版本计划文档结合 版本说明、各版本 升级指南 与 变更记录 等仓库资料完整讲解 Hyperf 的版本生命周期、迭代节奏、版本号语义以及实际项目中如何根据这些规则制定升级计划。版本生命周期总览Hyperf 官方在 docs/zh-tw/release-planning.md 中公开了从 1.0 到 3.2 全系版本的生命周期状态每个版本包含四项关键信息当前状态、主流支持截止时间、安全维护截止时间、以及发布或预计发布时间。版本状态主流支持截止时间安全维护截止时间发布或预计发布时间3.2主流支持2027-06-072028-01-012026-06-073.1 (LTS)安全维护2026-06-072027-06-072023-12-013.0停止维护2023-11-302024-06-302023-01-032.2停止维护2022-06-202023-11-302021-07-192.1停止维护2021-06-302021-12-312020-12-282.0停止维护2020-12-282021-06-302020-06-221.1停止维护2020-06-232020-12-312019-10-081.0停止维护2019-10-082019-12-312019-06-20从这张表可以读出 Hyperf 版本管理的几个关键事实3.2 是当前活跃迭代版本于 2026-06-07 发布处于主流支持阶段其主流支持期将持续到 2027-06-07安全维护期则到 2028-01-01。3.1 是当前唯一的 LTS长期支持版本主流支持于 2026-06-07 结束此后转入安全维护阶段直至 2027-06-07。这意味着 3.1 与 3.2 的安全维护截止时间恰好衔接为从 3.1 向 3.2 迁移留出了充足的时间窗口。3.0 及更早版本均已停止维护这些版本不会再有任何代码变更官方建议尽快根据对应升级指南升级。三级支持状态的含义版本计划文档对三种状态给出了明确的定义理解这些定义是制定升级策略的前提主流支持Mainstream support在常规迭代周期内提供完整的维护服务包括 BUG 修复、安全问题修复、功能迭代和功能新增。处于此状态的版本会随每周迭代持续获得更新。安全维护Security fixes support仅包含安全问题的修复不再进行常规 BUG 修复与功能迭代。安全维护期通常是在主流支持期结束后额外提供的一段宽限期用于保障仍在使用旧版本的用户有足够时间完成升级。停止维护Deprecated不会再进行任何代码变更。停留在该状态的版本意味着已知问题不会得到修复新的安全漏洞也不会被打补丁存在运行风险应尽快升级。从源码仓库的实际迭代节奏也可以印证这一机制当前 3.2 分支的 变更记录 持续记录着每周的功能新增、优化与修复例如 v3.2.5 中对Hyperf\Memory\LockManager、AMQP 消费者并发限制的优化而 3.1 分支的 变更记录 在转入安全维护后仅保留安全相关的修复条目。版本迭代周期与发布节奏Hyperf 采用敏捷开发模式迭代计划以周为单位推进具体节奏如下每个迭代周期为一周每周会产出一个新的版本。发布时间固定在每周的星期一UTC/GMT08:00即北京时间。常规迭代通常发布一个z 版本补丁版本偶尔也可能是y 版本功能版本。x 版本主版本不遵循固定周期而是根据实际的研究成果和核心重构进度决定具体的迭代计划与发布时间。这一周更节奏与版本号规则紧密配合z 版本的周更保证了框架的 BUG 修复和功能增强能够以极短的周期触达用户而 x/y 版本由于可能引入破坏性变更需要更审慎的节奏。关于版本号规则的完整说明可参见 版本说明 一章。版本号规则x.y.z 语义Hyperf 采用x.y.z三段式版本号规则例如1.2.3中 1 为 x、2 为 y、3 为 z。三段数字分别代表不同的变更语义与兼容性边界x主版本号表示一个重大版本。当核心发生大量重构变动或存在大量破坏性 API 变更时会以 x 版本发布。x 版本变更通常无法与之前的 x 版本完全兼容但也不代表绝对不兼容具体差异需要根据对应版本的升级指南逐一甄别。y次版本号表示一个主要功能迭代版本。当部分公开 API 发生破坏性变更包括 API 的修改和删除导致旧版本无法兼容时以 y 版本发布。z补丁版本号表示一个完全兼容的修复版本。当对各组件已有功能进行 BUG 修复或安全修复时以 z 版本发布。z 版本默认保证向后兼容但存在一个特例如果某个 BUG 导致某个功能完全无法使用则可能在该 z 版本内通过破坏性变更来修复由于该功能此前已完全不可用此类变更不会升级为 y 版本发布。此外z 版本也可能包含一些新增的功能或组件这些新增内容不会影响此前的代码使用。以实际版本为例3.1 到 3.2 的跨越属于y 版本升级其 3.2 升级指南 中列出了明确的破坏性变更如async-queue组件将JobInterface::getQueueName()重命名为getPoolName()、logger与cache的配置结构变更等而从 3.2.0 到 3.2.5 的连续发布则属于z 版本升级每次只包含修复与小幅优化。升级路径与各版本升级指南针对不同版本间的迁移Hyperf 在docs/zh-tw/upgrade/目录下为每个大版本提供了独立的升级指南这是 x/y 版本升级的权威依据1.1 升级指南2.0 升级指南2.1 升级指南2.2 升级指南3.0 升级指南3.1 升级指南3.2 升级指南各版本升级指南的核心要点从源码仓库确认如下3.2PHP 8.2 与组件重构将 PHP 最低版本提升至8.2symfony/*组件升级至^6.0 || ^7.0phpunit/phpunit升级至^11.0。async-queue的JobInterface::getQueueName()重命名为getPoolName()自定义任务类需要同步改名?php // 变更前 class CustomJob extends \Hyperf\AsyncQueue\Job { public function getQueueName(): string { return custom; } } // 变更后 class CustomJob extends \Hyperf\AsyncQueue\Job { public function getPoolName(): string { return custom; } }logger、cache配置结构变更分别对应 PR #7563、PR #7594。使用swow引擎时需在config/autoload/dependencies.php中新增 response emitter 依赖?php // config/autoload/dependencies.php use Hyperf\Contract\ResponseEmitterInterface; use Hyperf\Engine\ResponseEmitter; return [ ResponseEmitterInterface::class ResponseEmitter::class, ];3.1PHP 8.1、Swoole 5.0 与配置加载方式变化PHP 最低版本提升至 8.1Swoole 最低版本提升至 5.0。新增hyperf/helper包原Hyperf\Utils中不带命名空间的助手函数迁移至hyperf/helper以避免与其他 Composer 包的函数冲突。hyperf/config多层配置文件的加载方式变更由配置文件名作为键改为相对目录.配置文件名作为键支持.语法如config(a.c)。原来config/autoload/sub/a.php的读取方式从config(a)改为config(sub.a)。metric组件不再默认安装prometheus依赖需要prometheus引擎时需手动执行composer require promphp/prometheus_client_php。Request/Response的withHeaders行为变更v3.1 之后直接整体替换所有 headers而非合并原数据。AMQP消费者consumeMessage()方法返回值类型调整为Result枚举。3.0PHP 8 Attributes 全面取代 Doctrine AnnotationsPHP 最低版本提升至 8.0框架移除Doctrine Annotations改为使用 PHP 8 Attributes。需要在 2.2 版本下先执行composer require hyperf/code-generator与php bin/hyperf.php code:generate -D app将全部注解转化为原生注解再将composer.json中的hyperf/*统一修改为3.0.*后执行composer update -o。模型基类增加了成员变量类型支持需用php vendor/bin/regenerate-models.php $PWD/app/Model重新生成模型类。2.2PHP 8 适配支持原生注解需安装pcntl扩展开启 grpc 时还需在php.ini中添加grpc.enable_fork_support 1;。单测脚本需增加--prepend test/bootstrap.php选项。2.0AOP 底层逻辑变更Swoole 最低版本提升至 4.5。入口文件bin/hyperf.php需要新增Hyperf\Di\ClassLoader::init();初始化代码tests/bootstrap.php同样处理。变更记录追溯每个版本的演进细节每个版本的详细变更条目保存在docs/zh-tw/changelog/目录仓库根目录另有 CHANGELOG.md、CHANGELOG-3.2.md 等汇总文件。以 3.2 分支为例变更记录 覆盖了从 v3.2.0 到 v3.2.5 的每次发布v3.2.52026-09-15优化 AMQP 消费者在concurrent.limit小于qos.prefetch_count时自动扩大并发限制避免AMQPInvalidFrameException异常。v3.2.42026-08-10新增Hyperf\Support\assert_instanceof()支持 Nacos v1/v2/v3 从实例列表读取主机地址。v3.2.32026-07-29新增Hyperf\Support\existent函数修复模型生成时property类型错误等。v3.2.22026-07-26移除已废弃的兼容代码修复gen:migration-from-database、ProcScanHandler等问题。这些变更记录与版本计划配合使用版本计划回答这个版本什么时候发布、维护到什么时候变更记录回答每个具体版本改了什么、引入了哪些破坏性变更两者共同构成版本管理的事实基础。制定升级计划实操建议结合版本计划文档、版本规则与升级指南实际项目可以按以下步骤制定升级计划确认当前版本所处状态对照生命周期表找到自己所用版本的状态。若处于停止维护应尽快规划升级因为该版本不会再有任何代码变更包括安全修复。区分升级类型z 版本升级如 3.2.0 → 3.2.5直接兼容无需查阅升级指南执行composer update hyperf即可。官方不建议单独升级某一个组件的版本而是统一升级所有组件以获得一致的体验。x/y 版本升级如 3.1 → 3.2必须先阅读对应版本的 升级指南按其中的破坏性变更清单逐一改造代码再升级依赖。关注环境依赖约束当前 composer.json 中hyperf/hyperf要求 PHP8.2、ext-swoole 5.0因此在跨版本升级前应先确认运行环境满足新版本的最低要求3.2 要求 PHP 8.23.1 要求 PHP 8.1 与 Swoole 5.0。利用 LTS 版本过渡3.1 作为 LTS 版本其安全维护期与 3.2 的主流支持期部分重叠如果暂时无法完成大版本升级可先停留在 3.1 并持续获得安全修复同时规划向 3.2 迁移。关注每周发布由于 Hyperf 每周一UTC/GMT08:00发布新版本建议定期关注 3.2 变更记录 与根目录的 CHANGELOG-3.2.md及时评估修复与功能新增对业务的影响。综上Hyperf 的版本计划是一套公开、透明且可执行的治理机制以周为单位的敏捷迭代保证版本新鲜度x.y.z 语义化规则明确兼容性边界三级生命周期状态主流支持 / 安全维护 / 停止维护为用户提供清晰的升级时间表。结合 版本说明、各版本 升级指南 与 变更记录开发者可以据此制定稳妥、可持续的版本跟进与升级策略。赞分享后端Web框架微服务RPC框架异步编程【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/hyperf/hyperf点击查看免费下载相关推荐Hyperf 版本发布规划与生命周期管理指南从支持期限到升级策略Hyperf 版本发布规划与生命周期管理指南从支持期限到升级策略 Hyperf 作为一款基于 Swoole 的协程框架通过一套清晰的版本生命周期制度来平衡功后端Web框架微服务RPC框架异步编程Hyperf 版本计划与版本生命周期全解析版本规则、发布节奏与升级维护策略Hyperf 版本计划与版本生命周期全解析版本规则、发布节奏与升级维护策略 本文档 docs/zh cn/release planning.md 面向所有后端微服务Hyperf 版本计划与升级策略全解读生命周期、迭代节奏与 x.y.z 版本规则实战指南Hyperf 版本计划与升级策略全解读生命周期、迭代节奏与 x.y.z 版本规则实战指南 本篇技术指南以 Hyperf 官方《版本计划》文档为核心系统梳理后端Web框架微服务RPC框架异步编程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考