必须立即干预hyperf异步队列任务堆积:先用async-queue:info确认pending/failed异常,再通过flush命令清空pending任务,导出并筛选重试failed任务,最后注释代码、禁用监听器或关闭队列投递以切断源头。

Hyperf异步队列任务堆积导致接口响应变慢、监控告警频发、失败任务持续积压,必须立即干预,不能等自动重试或重启服务来缓解。
确认堆积是否真实存在
执行命令查看当前待处理任务总数:php bin/hyperf.php async-queue:info。若显示 【pending】 数值远高于日常基线(如平时 5~10,现达 200+),且 【failed】 持续增长,说明已发生实质性堆积。
注意:仅看 Redis 中的 list 长度(如 LLEN queue:default)不可靠——部分任务可能已在消费中但未 ack,需以 async-queue:info 输出为准。
紧急清理 pending 任务(不执行,直接丢弃)
方法一:使用内置清空命令(推荐,安全可控)
运行:php bin/hyperf.php async-queue:flush --queue=default。该命令会清空指定队列所有 pending 任务,不触发任何 handle() 执行,适用于已确认无需重试的临时堆积场景。
方法二:直连 Redis 强制清空(仅限开发/测试环境)
连接 Redis CLI,执行 DEL queue:default。⚠️【生产环境禁用此操作】——它会同时清除正在被消费但尚未 ack 的任务,造成任务丢失且无日志可查。
批量重置 failed 任务并选择性重试
第一步:导出全部失败任务 ID 到文件
php bin/hyperf.php async-queue:failed --format=json > failed_tasks.json
第二步:筛选出可重试的任务(例如仅重试 5 分钟内失败、且错误类型为网络超时的)
用 jq 或 Python 快速过滤:jq -r '.[] | select(.failed_at > (now - 300) and .exception | contains("cURL error")) | .id' failed_tasks.json
第三步:对筛选出的 ID 批量重试
xargs -I {} php bin/hyperf.php async-queue:retry {}
这一步避免全量重试引发二次雪崩,只让真正可恢复的任务回归队列。
停止新任务入队,切断堆积源头
① 立即注释或删除触发高频异步任务的业务代码段,例如订单创建后自动推送消息的 dispatch(new PushMessageJob(...)) 调用;
② 若使用了事件监听器(如 OrderPaid::class 监听器),临时禁用对应监听器配置;
③ 在 config/autoload/async_queue.php 中将 'enable' => false,彻底关闭队列投递能力——【这是最彻底的断流方式,务必在确认无关键任务依赖时启用】。











