因为Hyperf Crontab默认采用IntervalStrategy，各Worker进程独立扫描执行@Crontab任务，无跨进程/跨机器协调机制；需通过Redis分布式锁+自定义Strategy实现全局唯一调度。
为什么单机 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;
<p>class DistributedCrontabStrategy extends AbstractStrategy
{
public function <strong>construct(
protected Redis $redis,
protected StdoutLoggerInterface $logger
) {
parent::</strong>construct();
}</p><pre class="brush:php;toolbar:false;">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 同步。
