hyperf 3.0 异步队列高并发落地需避开五大陷阱：① redis 配置加载顺序错误导致静默失败；② processes 值过小引发任务堆积；③ concurrent.limit 与任务类型不匹配致协程阻塞；④ timeout/handle_timeout 设置不合理造成任务丢弃；⑤ 混用 asynctask 注解与 job 类引发执行混乱。
Hyperf 3.0 异步队列在高并发场景下常出现任务堆积、执行失败、数据丢失等问题，必须避开配置错位、协程阻塞、重试失控等关键陷阱，否则上线后接口卡顿、订单超时、邮件不发将成为常态。
确认异步队列组件已正确安装并启用
执行 composer require hyperf/async-queue 安装组件，注意不要遗漏 hyperf/redis（Redis驱动依赖）或 hyperf/database（数据库驱动依赖）；若使用 Redis，还需确保 hyperf/redis 已安装且配置加载顺序正确——【config/autoload/redis.php 必须早于 async_queue.php 加载】，否则队列启动时会因 Redis 连接未就绪而静默失败，无任何报错日志。
运行 php bin/hyperf.php gen:publish hyperf/async-queue 发布配置文件，检查 config/autoload/async_queue.php 是否存在且可读。
配置 async_queue.php 的核心参数避坑
打开 config/autoload/async_queue.php，重点调整以下三项：
① 'processes' => 1 改为 'processes' => (int)env('ASYNC_QUEUE_PROCESSES', 2)：Hyperf 3.0 默认只启 1 个消费者进程，单进程无法应对并发任务，务必按 CPU 核数 × 1～2 设置，4 核机器建议设为 4～8；【processes 值过小会导致任务持续堆积，CPU 却空闲】。
② 'concurrent' => ['limit' => 10]：该值控制单个消费者内并发执行的任务数。若任务含 HTTP 调用或数据库查询，设为 10 是安全起点；若任务纯 CPU 计算（如加密、压缩），必须降至 1～3，否则协程无法切换，线程卡死。
③ 'timeout' => 2 和 'handle_timeout' => 10：前者是任务从队列取出到开始执行的等待超时，后者是任务 handle() 方法执行的最大时长。若任务常调第三方 API，handle_timeout 至少设为 30，否则超时后任务被丢弃且不重试。
创建 Job 类时的致命写法规避
方法一：继承 Hyperf\AsyncQueue\Job 是唯一推荐方式，禁止使用 #[AsyncTask] 注解类混入队列逻辑——AsyncTask 是 task_worker 模式，与 async-queue 的 consumer 进程模型冲突，混合使用会导致任务重复执行或完全不触发。
方法二：Job 构造函数中只赋值属性，禁止在此发起 DB 查询或 Redis 操作。所有耗时操作必须放在 handle() 内，否则构造阶段阻塞会拖慢整个消费者进程。
方法三：在 handle() 中主动捕获异常并记录日志，例如：try { $this->doHeavyWork(); } catch (\Throwable $e) { \Hyperf\Logger\LoggerFactory::get('queue')->error('Job failed', ['job' => get_class($this), 'error' => $e->getMessage()]); throw $e; } ——不抛出异常会导致任务被标记为成功，错误被吞掉，排查无门。
延时任务投递前必校验时间精度
若使用延时队列（如订单 30 分钟后关闭），先确认 config/autoload/delay_queue.php 中 'score_precision' => 0.001 已设置。这个值决定了 $delay 参数单位：设为 0.001 时，$delay = 1800 表示 1800 毫秒（1.8 秒），不是 1800 秒。
投递时调用 DelayQueue::push(new OrderCloseJob($orderId), 1800) ——这里 1800 是毫秒，必须与 score_precision 对齐；【若 precision=1（默认秒级）却传毫秒值，任务将延迟 1800 秒而非 1.8 秒】。
验证方式：用 redis-cli 查看 Zset key（如 order:delay:close）中的 score 值是否符合预期，例如 ZRANGE order:delay:close 0 -1 WITHSCORES。
启动消费者进程的正确姿势
第一步：确保 server.settings.task_worker_num 已在 config/autoload/server.php 中配置，推荐值为 cpu_count * 2；【Hyperf 3.0 中 worker_num 已废弃，task_worker_num 才决定异步任务承载能力】。
第二步：启用协程 Task Worker，在同一文件中设置 'task_enable_coroutine' => true，否则消费者进程内无法使用协程客户端（如 Co\Http\Client），HTTP 请求会阻塞整个进程。
第三步：启动命令必须带 --watch 或使用 supervisor 管理，执行 php bin/hyperf.php start 后，再单独运行 php bin/hyperf.php async-queue:consume ——不能省略 consume 命令，Hyperf 不会自动拉起消费者进程。
