Hyperf分布式定时任务实现方法

Hyperf默认的定时任务机制在集群环境下会因各Worker进程独立扫描执行而引发任务重复执行问题，这并非缺陷而是单机设计的必然结果；本文深入剖析了其根本原因，并提供了一套基于Redis分布式锁与自定义Strategy的可靠解决方案——通过按时间维度（如分钟级）生成唯一锁Key、原子化加锁与安全删锁、配合容器绑定替换策略，实现跨进程跨机器的全局唯一调度，同时预警了Redis连接异常、任务超时、秒级精度丢失以及时钟漂移等线上高频陷阱，助你构建真正高可用、可落地的分布式定时任务体系。

为什么单机 hyperf/crontab 在集群下会重复执行？

因为默认的 Hyperf\Crontab\Strategy\IntervalStrategy 是每个 Worker 进程独立扫描和触发，只要服务启多个实例（哪怕只是多开几个 php bin/hyperf.php start），所有节点都会各自读取 @Cron 注解并执行——没有协调机制，自然就重复了。

这不是 bug，是设计使然：它本就面向单机场景。想跨进程/跨机器只跑一次，必须引入外部共识或锁。

• 常见现象：curl 调用接口发短信、写数据库统计、清理缓存等任务在日志里反复出现多次
• 本质问题：没有全局唯一调度入口，也没有执行态互斥
• 不推荐靠「人工限制只启一个实例」——违背高可用前提，且扩缩容时极易出错

用 Redis 分布式锁 + Crontab 自定义策略怎么写？

核心思路是把「谁来触发任务」这个决策权从每个进程手里收上来，统一交给一个带锁的调度器。关键不在禁用原策略，而在替换掉它的触发逻辑。

你需要自定义一个 Strategy 类，继承 Hyperf\Crontab\Strategy\AbstractStrategy，并在 execute() 中加锁判断：

use Hyperf\Contract\StdoutLoggerInterface;
use Hyperf\Crontab\Strategy\AbstractStrategy;
use Hyperf\Redis\Redis;
class DistributedCrontabStrategy extends AbstractStrategy
{
public function construct(
protected Redis $redis,
protected StdoutLoggerInterface $logger
) {
parent::construct();
}
public function execute(): void
{
    $lockKey = 'crontab:lock:' . date('Y-m-d-H-i'); // 按分钟粒度锁
    $lockValue = uniqid('', true);
    $result = $this->redis->set($lockKey, $lockValue, ['NX', 'EX' => 30]);
    if (! $result) {
        $this->logger->info("Skip crontab execution this minute: lock not acquired");
        return;
    }

    try {
        parent::execute(); // 真正执行所有匹配的 @Cron 任务
    } finally {
        // 防误删：只删自己设的锁
        $current = $this->redis->get($lockKey);
        if ($current === $lockValue) {
            $this->redis->del($lockKey);
        }
    }
}
}

• 锁 key 必须带时间维度（如 Y-m-d-H-i），否则同一任务可能被卡住一整小时
• 务必用 NX+EX 原子写入，避免 set + expire 分离导致锁失效
• finally 里删锁要校验 value，防止 A 加锁后超时，B 加锁成功，A 回来误删 B 的锁

如何让 Hyperf 加载你自己的 DistributedCrontabStrategy？

不能靠注解自动注册，得手动覆盖容器里的 Hyperf\Crontab\Strategy\StrategyInterface 绑定。

在 config/autoload/dependencies.php 中写：

return [
    Hyperf\Crontab\Strategy\StrategyInterface::class => [
        'alias' => App\Task\DistributedCrontabStrategy::class,
    ],
];

注意两点：

• 别漏掉 alias 键，否则 DI 容器无法识别这是接口实现
• 确保你的类已正确声明命名空间，并被 Composer 自动加载（检查 composer dump-autoload）
• 如果用了 hyperf/watcher，改完依赖配置需重启 watcher，否则热更不生效

还有哪些容易被忽略的坑？

分布式定时任务不是加个锁就万事大吉。下面这些点线上出过真实故障：

• Redis 连接不稳定时，set 报错会直接中断整个 execute() 流程，导致当次所有任务全跳过——建议对 $this->redis->set() 做 try/catch 并记录 warn 日志，失败时 fallback 到本地执行（或直接跳过）
• 任务本身耗时超过锁的 EX 时间（比如锁设 30 秒，但某次清理日志花了 45 秒），下次调度进来会抢到锁并并发执行——要么调大锁过期时间，要么在任务里主动续期（不推荐复杂化）
• @Cron 注解里的表达式如果含秒级（* * * * * *），而锁 key 只按分钟打点，会导致每分钟最多只执行一次，秒级精度丢失——此时应改用 Y-m-d-H-i-s，但要注意 Redis key 数量暴增

最麻烦的其实是时钟漂移：不同机器系统时间不一致，可能导致某些节点永远抢不到锁，或者两个节点同时认为「现在该我执行了」。生产环境务必开启 NTP 同步。

本篇关于《Hyperf分布式定时任务实现方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！