4939 字
25 分钟
Workers 进阶:Cron 定时任务与 KV 存储

先说问题:上一篇的 Worker 只会「被叫到才动」#

在 Workers 入门 里,我们写的 Worker 全都是一个模式:请求进来,fetch 处理函数接住,处理完返回响应。没有人访问,它就静静躺着,一行代码都不会跑。

但真实需求里有一大类活儿不是请求驱动的:

  • 每 5 分钟探一次自己的几个站点还活着没有;
  • 每天凌晨把某个 API 的数据拉回来整理一遍;
  • 每小时刷新一次缓存、同步一次状态。

这类活儿的共同点是两个:到点自己醒,以及醒来干完活,得有个地方把结果放下,不然下次醒来两眼一抹黑,也没法把结果展示给访客看。

这正是本篇的两块拼图:

拼图解决什么在 Cloudflare 里叫什么
定时醒来按计划自动触发代码Cron Triggers
存下结果跨请求、跨运行保留数据Workers KV

把这两块拼上,Worker 就从「被动接请求」升级成「能自己干活的小服务」。本篇路线:先讲 Cron Triggers 的配置与时区坑,再讲 scheduled 处理函数的写法,然后讲 KV 的本质与全套操作,最后把两者组合成一个完整实战——定时探活加状态页。

核心结论先放这里:Cron 负责「什么时候跑」,KV 负责「跑完把结果放哪」,两者组合就是绝大多数轻量自动化任务的完整骨架。

Cron Triggers:让 Worker 按计划醒来#

cron 表达式五字段速通#

Cron Triggers 用的是经典的 cron 表达式,一共五个字段,用空格分隔:

分 时 日 月 星期
│ │ │ │ │
│ │ │ │ └─ 星期:0–6(0 是周日),也可用 MON、TUE 等英文缩写
│ │ │ └──── 月:1–12
│ │ └─────── 日:1–31
│ └────────── 时:0–23
└───────────── 分:0–59

每个字段除了写具体数字,还支持三种符号:

  • *:任意值,这个字段不限制;
  • */n:每隔 n 个单位,比如分钟字段写 */5 就是每 5 分钟;
  • a-b:范围,比如小时字段写 9-18 就是 9 点到 18 点;
  • a,b,c:枚举,比如星期字段写 1,3,5 就是周一、周三、周五。

常用例子对照表:

需求表达式说明
每 5 分钟*/5 * * * *探活、刷状态最常用的节奏
每小时整点0 * * * *分钟写 0,即每个整点
每天凌晨 2 点0 2 * * *注意这是 UTC 时间,下文细说
每天早上 8 点半30 8 * * *时、分顺序别写反
每周一上午 9 点0 9 * * 1星期字段 1 是周一
每月 1 号零点0 0 1 * *日字段写 1
工作日每小时0 * * * 1-5周一到周五

最大的坑:时区是 UTC#

Cron Triggers 的时间一律按 UTC 计算,没有时区设置项。这是新手最容易栽的地方:在中国(UTC+8)想让任务每天北京时间凌晨 2 点跑,表达式要写的是 UTC 的前一天 18 点:

北京时间 02:00 = UTC 18:00(前一天)
表达式:0 18 * * *

换算方法很简单:北京时间减 8 小时。减完跨到前一天也没关系,cron 只认钟点不认日期对应关系,你只要保证换算后的 UTC 时刻正确即可。但要注意一种情况:带星期字段时,跨天会连星期一起错位。比如想在北京时间周一早上 9 点跑,UTC 是周一凌晨 1 点,同一天,没问题;但想在北京时间周日早上 6 点跑,UTC 是周六 22 点,星期字段要写 6(周六)而不是 0(周日)。

WARNING

改表达式之前,先在心里(或纸上)把目标时间换算成 UTC 再写。线上发现「任务没按时跑」,十有八九不是平台故障,而是时区算错了 8 小时,任务其实在另一个时刻准时跑了。

两种配置方式#

方式一:控制台配置。 打开 Cloudflare 控制台,进入对应 Worker 的「设置 → 触发器(Triggers)→ Cron 触发器」,点添加,填入表达式即可。适合快速试错,改完立即生效,不用重新部署代码。

方式二:wrangler.toml 配置。 把触发器写进项目配置文件,跟着代码一起版本管理:

name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-11-01"
[triggers]
crons = ["*/5 * * * *", "0 18 * * *"]

一个 Worker 可以挂多个 cron 表达式(数组里写多条)。部署时 wrangler deploy 会把 triggers 一并同步上去。

两种方式的关系要注意:如果 wrangler.toml 里写了 [triggers],每次 deploy 都会以文件为准覆盖控制台里的设置。团队协作时统一走配置文件,避免出现「控制台改了、下次部署又被打回去」的灵异事件。拿不准当前线上到底挂了哪些触发器,去控制台的触发器页面看一眼,那里显示的是实际生效值。

scheduled 处理函数:醒来之后干什么#

Cron Triggers 只负责「叫醒」。醒来之后执行哪段代码,由 scheduled 处理函数决定。它和 fetch 并列写在同一个 export default 对象里:

export default {
// 处理 HTTP 请求(入门篇写过)
async fetch(request, env, ctx) {
return new Response("hello");
},
// 处理定时触发(本篇主角)
async scheduled(event, env, ctx) {
console.log("被 cron 叫醒了,计划时间:", new Date(event.scheduledTime).toISOString());
// 在这里写定时任务的逻辑
},
};

三个参数各管一摊:

  • event:这次触发的信息,event.cron 是触发它的表达式字符串(挂了多个 cron 时靠它区分是哪个计划在叫你),event.scheduledTime 是计划触发时刻的时间戳;
  • env:环境变量与各种绑定(包括下文要绑的 KV),和 fetch 里的是同一套;
  • ctx:执行上下文,最重要的是 ctx.waitUntil(promise)。

ctx.waitUntil 为什么重要#

定时任务里经常有「发出去就不管了」的异步活儿,比如探活要同时请求好几个 URL、结果要写 KV。scheduled 函数本身返回后,这次运行随时可能被平台收尾。用 ctx.waitUntil() 把关键的 Promise 登记进去,等于告诉平台「等这些事办完再结束」:

async scheduled(event, env, ctx) {
ctx.waitUntil(doWork(env));
}
async function doWork(env) {
const res = await fetch("https://example.com");
await env.STATUS.put("last-check", String(Date.now()));
}

实践建议:把真正的活儿抽成一个独立函数,scheduled 里只做一件事——ctx.waitUntil(活儿(env))。结构清楚,也避免漏登记导致任务「跑了一半被掐掉」。

还有一个区分多计划的常见写法:

async scheduled(event, env, ctx) {
if (event.cron === "*/5 * * * *") {
ctx.waitUntil(checkSites(env)); // 5 分钟计划:探活
} else if (event.cron === "0 18 * * *") {
ctx.waitUntil(dailyReport(env)); // 每日计划:汇总
}
}

一个 Worker 挂多个计划、各干各的活,完全可行,不必为每个计划单独建一个 Worker。

本地测试:手动触发 scheduled#

wrangler dev 启动后,scheduled 不会真的等 cron 到点才跑。本地测试有两种方式:

  1. 启动时加参数 wrangler dev --test-scheduled,然后访问 http://localhost:8787/__scheduled,每访问一次就手动触发一次 scheduled,还可以带参数指定用哪个表达式触发:http://localhost:8787/__scheduled?cron=*/5+*+*+*+*;
  2. 不加参数时,本地默认根本不触发 scheduled,别对着日志干等。

改完代码先在本地用 __scheduled 把逻辑点通,再部署上线,这是最稳的节奏。

KV:给 Worker 一个能存东西的地方#

它是什么,本质是什么#

Workers KV 是一个键值存储:你给一个字符串键(key),存一个字符串值(value),之后凭键取回来。就这么简单,没有表、没有行、没有查询语言。

它的设计取向非常鲜明:

维度KV 的表现
读取数据复制到全球边缘节点,读的时候就近取,极快
写入写进中心存储后,再逐步同步到全球各节点
一致性最终一致:刚写完的值,其他地区可能要过一会儿(通常 60 秒内)才读得到
适合存配置、开关、状态快照、缓存、探活结果
不适合存账户余额、库存计数、需要读了立刻改的强一致数据

KV 的本质是「读多写少、能容忍几十秒延迟」的全球分发存储。理解这一点,后面所有用法和坑都顺理成章:探活结果每 5 分钟写一次、访客随时读,完美契合;而拿它当计数器高频自增,就是跟最终一致性对着干,迟早读到旧值算错账。

WARNING

不要用 KV 存任何「写完必须立刻读到新值」的关键数据。典型反例:限流计数、秒杀库存、会话令牌的即时吊销。这类需求要的是强一致存储,应该去用 D1 或外部数据库(本篇结尾会再收束这条边界)。

建 namespace 与绑定#

KV 的存储空间叫 namespace(命名空间),可以理解成「一个独立的键值仓库」。一个 Worker 可以绑多个 namespace,互不干扰。

第一步:建 namespace。 控制台在「Workers 和 Pages → KV」里新建;命令行则是一条:

Terminal window
npx wrangler kv namespace create STATUS_KV

命令会返回这个 namespace 的 id,形如:

{ binding = "STATUS_KV", id = "abcd1234..." }

第二步:绑到 Worker。 把绑定写进 wrangler.toml:

[[kv_namespaces]]
binding = "STATUS_KV"
id = "abcd1234..." # 上一步拿到的 id

绑定名(binding)就是代码里访问它的变量名,env.STATUS_KV。部署后生效。注意本地开发时 wrangler dev 默认用的是本地模拟 KV,数据不和线上互通;想连线上数据调试需显式加 --remote,日常开发用本地模拟即可,别把测试垃圾写进生产库。

代码里操作 KV:put / get / delete / list#

绑定完成后,在 fetch 和 scheduled 里通过 env.绑定名 使用:

// 写:存一个字符串
await env.STATUS_KV.put("site:blog", "up");
// 写的时候顺带设置过期时间(秒),到期自动删除
await env.STATUS_KV.put("temp:token", "xyz", { expirationTtl: 300 });
// 读:键不存在时返回 null,记得判空
const value = await env.STATUS_KV.get("site:blog");
if (value === null) {
// 没这个键
}
// 读的时候直接按 JSON 解析(存的时候存的是 JSON 字符串时很好用)
const obj = await env.STATUS_KV.get("state", { type: "json" });
// 删
await env.STATUS_KV.delete("site:blog");
// 列:按前缀列出键(返回的列表本身也有最终一致性)
const list = await env.STATUS_KV.list({ prefix: "site:" });
for (const key of list.keys) {
console.log(key.name);
}

几个使用要点:

  • value 只能是字符串(或 ArrayBuffer、流),对象要先 JSON.stringify 再存,读时再解析,或直接用 { type: "json" } 让运行时帮你解析;
  • expirationTtl 是相对秒数,最小 60 秒;还有绝对时间版本 expiration(Unix 时间戳)。临时状态、验证码类数据用它自动清理,省得手动删;
  • list 适合按前缀做简单枚举(比如把所有站点状态一次列出来渲染状态页),但不要拿它当数据库的 WHERE 查询使,键多了性能与语义都不对路;
  • 单个 value 有大小上限,KV 是存小数据的,别往里塞大文件——那是 R2 的活。

命令行直接操作 KV#

调试和运维时不用写代码,wrangler kv 子命令组可以直接读写:

Terminal window
# 写一个键
npx wrangler kv key put --binding STATUS_KV "site:blog" "up"
# 读一个键
npx wrangler kv key get --binding STATUS_KV "site:blog"
# 列出所有键
npx wrangler kv key list --binding STATUS_KV
# 删一个键
npx wrangler kv key delete --binding STATUS_KV "site:blog"

注意区分两种寻址方式:--binding 是按 wrangler.toml 里的绑定名(要在项目目录里执行),也可以用 --namespace-id 直接指定 namespace。线上排障时先用 key get 看一眼实际存的值,往往比看日志更快定位问题。

完整实战:定时探活 + 状态页#

现在把两块拼图装到一起,做一个真能用的小系统:

  • 每 5 分钟,scheduled 自动探活两个站点,把每个站点的状态(up/down)、HTTP 状态码、检查时间写入 KV;
  • 任何人访问这个 Worker 的地址,fetch 从 KV 读出最新结果,渲染成一个极简状态页。

完整代码#

const SITES = [
{ name: "blog", url: "https://blog.example.com" },
{ name: "api", url: "https://api.example.com" },
];
export default {
// ① 定时部分:被 Cron Triggers 叫醒后探活,结果写 KV
async scheduled(event, env, ctx) {
ctx.waitUntil(checkAll(env));
},
// ② 请求部分:有人访问时,读 KV 渲染状态页
async fetch(request, env, ctx) {
const rows = [];
for (const site of SITES) {
const raw = await env.STATUS_KV.get("site:" + site.name, { type: "json" });
if (raw === null) {
rows.push(`<tr><td>${site.name}</td><td>暂无数据</td><td>-</td><td>-</td></tr>`);
} else {
const mark = raw.status === "up" ? "🟢 正常" : "🔴 异常";
const time = new Date(raw.time).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" });
rows.push(`<tr><td>${site.name}</td><td>${mark}</td><td>${raw.code}</td><td>${time}</td></tr>`);
}
}
const html = `<!doctype html>
<html lang="zh-CN"><head><meta charset="utf-8"><title>站点状态</title></head>
<body><h1>站点状态</h1>
<table border="1" cellspacing="0" cellpadding="6">
<tr><th>站点</th><th>状态</th><th>HTTP 状态码</th><th>最近检查(北京时间)</th></tr>
${rows.join("\n")}
</table></body></html>`;
return new Response(html, {
headers: { "content-type": "text/html; charset=utf-8" },
});
},
};
async function checkAll(env) {
for (const site of SITES) {
let result;
try {
const res = await fetch(site.url, { method: "GET", redirect: "follow" });
result = {
status: res.status >= 200 && res.status < 400 ? "up" : "down",
code: res.status,
time: Date.now(),
};
} catch (err) {
result = { status: "down", code: 0, time: Date.now() };
}
await env.STATUS_KV.put("site:" + site.name, JSON.stringify(result));
}
await env.STATUS_KV.put("last-run", String(Date.now()));
}

配套的 wrangler.toml:

name = "site-status"
main = "src/index.js"
compatibility_date = "2024-11-01"
[triggers]
crons = ["*/5 * * * *"]
[[kv_namespaces]]
binding = "STATUS_KV"
id = "替换成你自己的 namespace id"

逐段讲#

为什么探活写在 scheduled、展示写在 fetch。 探活是「到点就该发生」的事,与有没有访客无关,放 scheduled;状态页是「有人来才需要生成」的东西,放 fetch。两者唯一的交集就是 KV:一个只写,一个只读,职责干净。

为什么探活结果要连时间戳一起存。 状态页上只写「正常」是不够的——如果 Worker 的定时任务本身挂了,页面会永远显示上次的「正常」,骗人。把 time 一起存、一起展示,任何人一眼就能看出「这数据是 3 分钟前的还是 3 天前的」。last-run 这个键同理,是给运维留的全局心跳。

为什么状态判断用 200–399 算 up。 站点根路径返回重定向(3xx)在很多部署里是正常行为(比如强制跳 HTTPS 或跳语言首页),一刀切只认 200 会天天误报。连接失败、超时这类异常走 catch,记为 down 且状态码记 0,与「服务器有响应但状态码不对」区分开。

为什么这个组合正好扬长避短。 探活每 5 分钟才写一次,写频率极低;状态页可能被频繁访问,全是读。KV 恰恰是为「写得少、读得多、读要快」设计的。反过来想:如果把每次探活的原始日志都往 KV 里堆、还要按时间范围查询统计,那就已经越界了——那是数据库的活。

上线顺序别搞反。 先建 namespace 拿到 id,填好 wrangler.toml,再 wrangler deploy。部署后先手动验证:浏览器访问一次状态页(此时多半显示「暂无数据」,正常),等 5 分钟 cron 跑过一轮,刷新页面就应该有数据了。等不及也可以在控制台的 Worker 页面里用「触发器」相关的测试入口手动触发一次,或者本地先用 --test-scheduled 把 checkAll 的逻辑验通。

与真数据库的边界#

把话说透,免得以后在选型上反复纠结:

需求特征用 KV换 D1 / 外部数据库
读多写少、能忍几十秒同步延迟✅ 正合适大材小用
存配置、开关、状态快照、缓存✅也行但没必要
写完立刻要读到、不能读旧值❌ 最终一致做不到✅
计数器、余额、库存这类要原子增减❌✅
按条件筛选、排序、聚合统计❌ 只有按前缀 list✅ SQL 的本行
结构复杂、表间有关联的数据❌✅

一句话定位:KV 是「分发到全球边缘的公告板」,不是账本。公告板上的字晚几十秒同步到所有人眼里没关系;账本上的数字错一位、晚一秒,都可能是事故。

排障#

定时任务没触发#

按这个顺序查,别乱猜:

  1. 表达式写错:字段顺序是分、时、日、月、星期,最常见的错误是把时和分写反,或者星期与日同时写了具体值导致语义叠加。用控制台触发器页面对照一遍,那里会把表达式和下一次触发时间直观列出来;
  2. 时区换算错位:任务其实跑了,只是跑在 UTC 换算后的时刻,和你预期的北京时间差 8 小时。去 Worker 的日志(控制台「日志」或 wrangler tail)里看 scheduled 的实际触发时间,一对便知;
  3. 部署没带上 triggers:本地 wrangler.toml 改了 crons 但没重新 wrangler deploy,或者在控制台手动改完又被下一次 deploy 覆盖。记住两者以最后一次 deploy 的文件为准,改完必须部署;
  4. 代码里没有 scheduled:只有触发器、没有处理函数,等于叫醒了但没人应声,不会报错,也不会干活。

KV 读到旧值#

  • 先接受这是正常现象:写入后全球同步需要时间,通常 60 秒内。用「刚 put 完立刻在另一个地区 get 到了旧值」当 bug 提,是对最终一致性的误解;
  • 判断是不是超期未同步:如果过了几分钟还读不到新值,再去查是不是写错了 namespace 或绑定(本地 dev 用的是模拟 KV、线上是另一个库,这种「我明明写了」多半是环境串了);
  • 业务上绕开:如果某个流程确实需要「自己刚写的值自己立刻能读到」,把值在同一次运行内用变量传递,不要写完再读 KV。

wrangler dev 里 scheduled 不自动跑#

这是预期行为,不是坏了。本地开发服务器不会按 cron 表达式自动触发 scheduled,必须加 --test-scheduled 启动,再手动访问 /__scheduled 端点触发(见前文)。另外注意:本地触发时连接的是本地模拟 KV 与本地环境变量,和线上不是一套,测试结论别直接套到线上。

状态页一直显示「暂无数据」#

顺着数据流查:cron 有没有触发(看日志)→ scheduled 里的探活有没有报错(fetch 目标是否可达)→ put 有没有成功(用 wrangler kv key get 直接查键在不在)→ fetch 里读的键名和写的键名是否一致(site: 前缀拼错一位是最常见的低级错误)。

小结#

  • Worker 想自己干活,需要两块拼图:Cron Triggers 管定时唤醒,KV 管保存结果;
  • cron 表达式五字段不难,真正的坑只有一个:时间是 UTC,北京时间减 8 小时再写,带星期时注意跨天错位;
  • scheduled 与 fetch 并列,活儿用 ctx.waitUntil 登记,本地用 --test-scheduled 加 /__scheduled 手动触发测试;
  • KV 是最终一致的全球键值存储,为读多写少而生,put / get / delete / list 加过期时间就是它的全套本事,强一致与复杂查询请交给 D1 或外部数据库;
  • 探活加状态页这个实战把两者的长处用满了:低频写、高频读、结果带时间戳,是拿来练手和真上线的都合适的第一个 Cron + KV 项目。

至此,Workers 从「接请求」到「定时干活存结果」就齐了。下一步如果想让状态异常时主动通知你,可以在探活逻辑里加一条发消息的 API 调用;想存得更结构化,就去看 D1。额度与计费细节以官方定价页为准,动手前扫一眼免费与付费的边界即可。

Workers 进阶:Cron 定时任务与 KV 存储
https://www.anexns.cloudns.org/posts/cloudflare-workers-cron-kv/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0