Hyperf 定时任务通过 hyperf/crontab 组件实现，支持秒级调度、分布式锁与多进程安全；需安装组件、配置 crontab.php、定义继承 AbstractCrontab 的任务类并标注 @Crontab 注解，启动服务后自动调度。
Hyperf 的定时任务调度主要通过 Hyperf\Crontab 组件实现，它基于协程、无外部依赖（如系统 crond），支持秒级精度、分布式锁防重复、多进程安全执行，是 Hyperf 官方推荐的定时任务方案。
一、安装与基础配置
确保已安装 hyperf/crontab 组件：
composer require hyperf/crontab
组件会自动注册，无需手动启用。默认配置位于 config/autoload/crontab.php，可按需调整：
-
enable：设为
true启用定时任务（开发环境建议开启） -
scan：指定扫描定时任务类的目录，默认为
App\Crontab -
timezone：设置时区（如
'Asia/Shanghai'），影响 cron 表达式解析
二、定义一个定时任务类
在 app/Crontab 目录下创建类，继承 Hyperf\Crontab\AbstractCrontab，并实现必要属性：
namespace App\Crontab;
<p>use Hyperf\Crontab\AbstractCrontab;
use Hyperf\Crontab\Annotation\Crontab;</p><h1>[Crontab]</h1><p>class DemoCrontab extends AbstractCrontab
{
public string $name = 'demo_task';
public string $rule = '<em>/5 </em> <em> </em> *'; // 每5分钟执行一次
public array $singleton = true; // 启用单例模式，防止多进程重复执行
public array $mutex = ['type' => 'redis']; // 可选：使用 Redis 分布式锁（需已配置 Redis）</p><pre class="brush:php;toolbar:false;">public function execute(): void
{
echo "[DemoCrontab] Running at " . date('Y-m-d H:i:s') . PHP_EOL;
// 此处写你的业务逻辑，如调用 Service、发消息、清理缓存等
}}
注意：
- $rule 支持标准 cron 表达式（分 时 日 月 周），也支持秒级扩展格式（6段，首段为秒）
- 若需秒级调度（如 '*/3 * * * * *'），需在配置中开启：'enable_millisecond' => true
三、启动与验证任务
定时任务随主服务一起启动，无需单独运行：
php bin/hyperf.php start
启动后，框架会在后台自动注册并调度所有 @Crontab 标记的任务。可通过以下方式确认是否生效：
- 查看控制台日志，启动时会打印类似
[INFO] Crontab manager started with 2 tasks - 观察任务输出（如上面的
echo），检查执行频率是否符合$rule - 使用
ps aux | grep crontab查看是否存在CrontabWorker进程
四、进阶技巧与避坑提示
常见问题与优化建议：
-
任务卡死或超时：在
execute()中避免同步阻塞操作（如 curl、sleep），改用协程客户端（Co\Http\Client）或co::sleep() -
多实例部署重复执行：务必启用
$mutex（Redis 类型），并确保各实例共享同一 Redis 实例 -
调试阶段快速触发：临时将
$rule改为'* * * * *'或使用date -d '+1 minute' +%M计算下一分钟时间点 - 动态修改规则：不建议运行时修改；如需灵活调度，可封装为「任务+参数」模式，由数据库或配置中心驱动
