Workerman定时任务核心是Timer::add()，它返回整数ID而非对象，所有任务由主进程轮询触发，多进程下各子进程独立执行，需用Redis锁等确保单次运行，最小稳定精度约0.1秒。
在 Workerman 5.2.3 中使用定时任务，核心是调用 Workerman\Lib\Timer::add() 方法注册回调，但必须注意它不是“面向对象式定时器”，而是基于主进程轮询的轻量级调度机制。实际使用中，关键不在“怎么写”，而在“怎么写对”——尤其要避开多进程重复执行、精度误判、生命周期失控等高频坑。
定时任务必须在 onWorkerStart 中注册
Workerman 的定时器依赖事件循环，只能在 Worker 进程启动后运行。主进程不跑事件循环，不能注册；在全局作用域或 onWorkerStop 中注册均无效。
- ✅ 正确位置：在
$worker->onWorkerStart回调内调用Timer::add() - ❌ 错误做法：在
Worker::runAll()前直接调用；或在onConnect/onMessage中反复调用（会导致同一任务被注册多次） - ⚠️ 注意：每个子进程都会独立执行自己的定时器。若
Worker::$processCount = 4，且你在onWorkerStart里注册了每秒一次的任务，则每秒实际触发 4 次
Timer::add() 的参数与常见写法
Timer::add(float $interval, callable $callback, array $args = [], bool $persistent = true)
-
$interval 单位是秒，支持小数（如
0.5表示 500ms），但实际最小稳定精度约 0.1 秒，高负载下可能延迟更大 -
$callback 必须是可调用类型：匿名函数、
[$obj, 'method']数组、PHP 8.1+ 支持的箭头函数；禁止传字符串函数名（如'my_func'），否则报TypeError -
$persistent = false 表示只执行一次（即延时任务），设为
true（默认）则周期执行 - 示例：延迟 3 秒发邮件（仅一次）
Timer::add(3, 'send_email', ['user@domain.com', 'Hi!'], false);
如何确保任务只执行一次（单例场景）
Workerman 不提供跨进程锁，需自行保障“单次性”。靠 Worker::$pid === Worker::$masterPid 不可行（主进程无事件循环），可靠方式有：
- 启动一个专用 Worker，设置
$task->count = 1，并在其onWorkerStart中注册所有需单例执行的定时任务 - 用 Redis 分布式锁：每次执行前
SETNX lock:task_name 1 EX 10，成功才运行，结束后DEL；避免死锁需设过期时间 - 文件锁（适合单机）：
flock($fp, LOCK_EX | LOCK_NB)尝试加锁，失败则跳过
停止与清理定时任务
Timer::add() 返回的是整型 ID，仅用于 Timer::del($id) 删除，它不返回对象，无法调用 cancel() 或 reset()。
- 保存 ID：建议存到
$worker实例属性或静态变量中，便于后续管理$worker->heartbeatId = Timer::add(10, fn() => echo "ping\n"); - 停止单个：
Timer::del($worker->heartbeatId); - 停止全部：Workerman 没有内置批量删除 API，需自行维护 ID 列表并遍历
del - 进程重启时，所有未
del的定时任务自动失效，无需手动清理
