Hyperf定时任务默认单实例安全,需设$singleton=false并移除$mutex配置才能实现多进程并发执行;每个Worker会独立触发任务,适用于本地资源处理场景。

Hyperf 定时任务默认是单实例、多进程安全的,但若需「同一任务在多个进程里并发执行」(比如不同 Worker 同时跑同一个定时逻辑),必须主动关闭单例保护和分布式锁——否则框架会自动拦截重复执行。
关闭单例模式
Hyperf 默认启用 $singleton = true,确保整个服务集群中该任务只运行一次。要允许多进程并发执行,需显式设为 false:
- 在任务类中将
public array $singleton = false; - 注意:这仅解除进程内单例限制,不解决跨机器重复问题
禁用分布式锁
即使关了 singleton,若配置了 $mutex(如 Redis 锁),任务仍会被串行化。需彻底移除或注释掉 mutex 配置:
- 删除或注释掉类似
public array $mutex = ['type' => 'redis'];的行 - 确保
config/autoload/crontab.php中未全局开启 mutex 默认策略
确认进程模型与调度行为
Hyperf 定时任务由 Crontab Manager 统一调度,每个 Worker 进程都会加载并监听任务。当 $singleton = false 且无锁时:
- 每个 Worker 进程会独立触发该任务(例如 8 个 worker → 每次调度最多执行 8 次)
- 适用于“每个进程需独立处理本地资源”的场景,如清理本机临时文件、上报本机监控指标
- 不适用于需共享状态的业务(如扣减库存),此时应改用异步队列 + 去重逻辑
验证是否真正并发执行
启动后观察日志输出频率和进程 ID:
- 在
execute()中加入echo "PID: " . getmypid() . " | Time: " . date('H:i:s') . PHP_EOL; - 若同一秒内出现多个不同 PID 的日志,说明已实现多进程并发
- 若只有单个 PID 或间隔明显拉长,检查是否仍有其他锁机制(如自定义 Redis key、文件锁等)


















