hyperf延时队列本质是延迟投递，基于redis zset实现，通过zrangebyscore+zrem原子操作由专用消费者进程持续拉取到期任务，非定时轮询或swoole timer硬扛；关键配置包括queue_name、毫秒级score_precision（如0.001）、合理retry_seconds与max_attempts，且$delay单位须与score_precision对齐。
延时队列不是定时任务，别用 crontab 或 Swoole\Timer 硬扛
Hyperf 的延时队列本质是「延迟投递」，不是「到点执行」。Zset 实现的核心逻辑是把任务按执行时间戳存进有序集合，由一个常驻的消费者进程持续 pop 最早到期的任务。如果误用 crontab 每秒扫一遍 Redis，会引发大量无效 IO 和时序漂移；用 Swoole\Timer 定时触发也撑不住高并发场景——每个定时器都得单独维护，内存和精度都不可控。
正确做法是启用 Hyperf 自带的 DelayQueue 组件，并配一个专用的 delayed 进程监听 Zset。它底层用的是 ZRANGEBYSCORE + ZREM 原子操作，避免重复消费。
- 必须关闭
scan类轮询配置，改用blockingPop模式（Hyperf v3.1+ 默认启用） - 确保 Redis 连接配置中
read_timeout≥ 5，否则阻塞等待会被提前中断 - 不要在
handle()里做耗时同步调用（如 HTTP 请求、大文件读写），会卡住整个延迟队列协程
Hyperf\DelayQueue\Driver\RedisDriver 的关键参数怎么设才不丢任务
默认驱动是 RedisDriver，但它不直接暴露 Zset key 名和 score 精度，全靠配置项控制行为。最容易出问题的是时间精度和重试机制：
-
queue_name：实际对应 Zset 的 key，建议加业务前缀，比如order:delay:close，避免和其他延时队列冲突 -
score_precision：默认是1（秒级），订单超时关闭强烈建议设为0.001（毫秒级），否则两个 10 分钟后执行的任务可能被当成同一时刻处理 -
retry_seconds：失败后重新入队的延迟，默认 60 秒。订单关闭失败时，应设为60而非0，否则会立即重试，可能加重 DB 压力 -
max_attempts：最大重试次数，建议设为3，超过就进死信队列（需手动配置dead_letter_queue）
示例配置片段（config/autoload/delay_queue.php）：
return [ 'default' => [ 'driver' => Hyperf\DelayQueue\Driver\RedisDriver::class, 'queue_name' => 'order:delay:close', 'score_precision' => 0.001, 'retry_seconds' => 60, 'max_attempts' => 3, ], ];
投递订单关闭任务时，push() 的 $delay 是秒还是毫秒？
这是最常踩的坑：$delay 参数单位取决于 score_precision 配置，不是固定值。比如你设了 score_precision => 0.001，那 push($job, 600) 表示 600 毫秒后执行，不是 600 秒。
Redis 8.2.3 是一款安全优先的高性能键值存储系统。该版本紧急修复了可能引发远程代码执行（RCE）的高危漏洞（CVE-2025-62507），并解决了 HyperLogLog 及 Cuckoo Filter 等数据结构在特定场景下的崩溃问题。建议所有用户立即升级，以保障生产环境的系统稳定与数据安全。
订单超时通常按分钟计（如 30 分钟未支付自动关单），所以推荐统一换算成毫秒再传：
- 30 分钟关单 →
$delay = 30 * 60 * 1000 - 代码里别写死数字，用常量或配置项，比如
OrderConfig::CLOSE_DELAY_MS - 投递前务必校验订单状态，已关闭/已支付的订单不能进延时队列，否则会白占 Zset 空间
- 如果用
Job类封装任务，构造函数里不要做 DB 查询，延迟队列进程没有完整的 DI 容器上下文
正确投递示例：
use Hyperf\DelayQueue\DelayQueue;$delayQueue = $this->container->get(DelayQueue::class); $delayQueue->push(new CloseOrderJob($orderId), 30 60 1000);
为什么 Zset 中任务没被消费，但 zcard 显示还有数据？
常见原因是消费者进程没启动，或者启动了但没监听对的 queue_name。Hyperf 的延时队列消费者是独立进程，不会随 start 自动拉起，必须显式运行：
- 检查是否执行过
php bin/hyperf.php delay-queue:handle - 确认该命令运行时加载的是正确的配置（比如
dev环境下是否误用了test配置） - 用
redis-cli手动查：执行ZRANGEBYSCORE order:delay:close -inf +inf WITHSCORES LIMIT 0 1，看返回的时间戳是否已过期 - 如果 score 是毫秒时间戳（如
1717023456789），但你的score_precision是1，就会导致永远匹配不到——因为 Zset 内部存储的是整数秒，而查询时传的是毫秒值
另一个隐蔽问题是 Redis 主从同步延迟：如果写入用主节点，消费用从节点（某些云 Redis 默认开启读写分离），Zset 数据还没同步过去，消费者就查不到。务必确保消费者连接的是主节点。
