hyperf 3.1.68 是聚焦稳定性与生产细节修复的补丁版本，修复协程上下文污染、连接池空闲泄漏、队列重试计数错误等问题，需同步升级 db-connection 和 async-queue 至 ^3.1.68，并确保 swoole ≥5.1.4。
Hyperf 3.1.68 不是 LTS 版本的增量更新，而是 3.1.x 系列中一个**聚焦稳定性与生产细节修复**的补丁版本。它没有引入新特性，但解决了若干在高负载、长周期运行场景下暴露的隐蔽问题——如果你正在用 Hyperf 3.1（尤其是 3.1.51 及之后版本）跑线上服务，这个更新值得立即评估。
升级前必须确认 PHP 和 Swoole 版本兼容性
该版本仍要求 PHP >= 8.1、Swoole >= 5.0（且禁用 short_name），但新增了对 Swoole 5.1.4+ 的显式适配优化。若你使用的是 Swoole 5.1.3 或更早版本，升级后可能触发 coroutine context lost 错误，尤其在高频 parallel() 调用或嵌套协程调度时。
- 检查当前版本：
php --ri swoole | grep "version" - 若低于
5.1.4，建议先升级 Swoole 再升级 Hyperf -
hyperf/polyfill-coroutine组件在本版中修复了与pcntl_fork()混用时的协程上下文污染问题，但仅限于未启用daemonize的子进程场景
数据库组件修复了连接池空闲连接泄漏
此前版本中，当 hyperf/database 配置了 max_idle_time 且应用存在突发流量后回落，部分连接会卡在 idle 状态无法被回收，导致连接数缓慢上涨直至耗尽。这个问题在 3.1.68 中通过重构 ConnectionPool::release() 的判定逻辑解决。
- 现象：监控显示
mysql_pool_used_connections持续增长，但mysql_pool_idle_connections不下降 - 验证方式：升级后观察
hyperf:monitor命令输出的 pool stats 是否稳定波动 - 注意：该修复不改变配置项，但要求
hyperf/db-connection必须同步升级至^3.1.68，否则无效
hyperf/async-queue 的 Job::setMaxAttempts() 行为修正
在 3.1.51 引入的 Job::setMaxAttempts() 方法，在重试过程中若遇到异常（如序列化失败、反序列化超时），会错误地将失败计数累加两次，导致任务提前被丢弃到 failed_jobs 表。此行为已在 3.1.68 中修正为仅在真正执行失败时计数。
- 影响范围：所有使用
setMaxAttempts()且依赖精确失败次数控制的队列任务 - 典型表现：
max_attempts=3的任务在第 2 次失败后即进入 failed 状态 - 无需修改代码，但需确认
hyperf/async-queue组件版本已更新，且failed_jobs表结构与hyperf/migration-generator输出一致
日志与调试支持增强，但默认关闭
本版悄悄加入了 HYPERF_DEBUG_COROUTINE_STACK 环境变量开关，启用后可在 Worker 进程崩溃时输出完整协程栈（而非仅主线程），这对排查死锁、协程挂起类问题极有价值。但它会显著增加日志体积和性能开销，**生产环境严禁开启**。
- 启用方式：
export HYPERF_DEBUG_COROUTINE_STACK=1，然后重启服务 - 输出位置：
runtime/logs/hyperf.log中以[COROUTINE STACK]开头的块 - 注意：该功能依赖
swow引擎的debug_info支持，若使用swoole引擎则无效果
hyperf/db-connection 和 hyperf/async-queue 这两个组件的**子版本必须严格对齐主框架版本**。它们不随 hyperf/hyperf 自动升级，需手动 composer update hyperf/db-connection hyperf/async-queue，否则看似升级成功，实际关键修复并未生效。
