定时任务

任务文件

在 crons/**/*.ts 中创建文件（同样支持 .mts、.js、.mjs）。

每个任务文件必须导出：

• export const cron = "<表达式>"（或表达式数组）
• 一个默认处理器（推荐用 defineScheduled 包装）

import { defineScheduled } from 'void';

export const cron = '0 * * * *';

export default defineScheduled(async (controller, env) => {
  await env.KV.put('jobs:last-heartbeat', controller.scheduledTime.toString());
});

多个调度

一个任务文件可以导出 cron 表达式数组：

import { defineScheduled } from 'void';

export const cron = ['0 * * * *', '30 * * * *'];

export default defineScheduled(async (controller, env) => {
  // 每小时的 :00 与 :30 各运行一次
});

defineScheduled

用 defineScheduled() 包装处理器，可以为它的调度事件、环境与执行上下文提供类型。

共享同一个 cron 表达式的任务每次只运行一次。Void 会等待所有匹配的任务完成，并报告任何失败。以 _ 开头的文件与目录会被忽略。

本地开发

本地开发时调度不会自动触发。通过向 Void 的开发端点发送请求来测试任务：

Content-Type: application/json

{ "cron": "<expression>", "scheduledTime": <unix_ms> }

把 cron 设置为任务导出的某个表达式。调用成功会返回 { "ok": true }。

该端点需要一个本地开发触发令牌。Void 会在开发服务器启动时打印一条可直接粘贴的 curl 命令。

curl -X POST http://localhost:5173/__void/scheduled \
  -H "Content-Type: application/json" \
  -H "x-void-dev-trigger: <printed-token>" \
  -d '{"cron":"0 * * * *","scheduledTime":'"$(date +%s000) "'}'

该端点在原生 Void 应用与受支持的框架中都能工作。框架任务运行在适配器的开发运行时中，使用它提供的绑定。

部署行为

原生的调度事件不需要手动 HTTP 令牌。对于框架部署，对 /__void/scheduled 的 HTTP 请求需要匹配的 x-void-internal 令牌：托管平台会提供它的代理令牌，或者你可以显式配置 CRON_SECRET 以支持手动调用。令牌缺失或不匹配时返回 401，不会运行任务。

在 Void 平台上，每个项目最多可以使用 100 个不同的 cron 表达式与 1,000 个调度（每个任务导出一个表达式计为一个调度）。共享同一表达式的任务在表达式上限中只计一次。部署到你自己的 Cloudflare 账户时，则遵循 Cloudflare 的 Cron Trigger 限制。