先说问题:上一篇的 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 到点才跑。本地测试有两种方式:
- 启动时加参数
wrangler dev --test-scheduled,然后访问http://localhost:8787/__scheduled,每访问一次就手动触发一次 scheduled,还可以带参数指定用哪个表达式触发:http://localhost:8787/__scheduled?cron=*/5+*+*+*+*; - 不加参数时,本地默认根本不触发 scheduled,别对着日志干等。
改完代码先在本地用 __scheduled 把逻辑点通,再部署上线,这是最稳的节奏。
KV:给 Worker 一个能存东西的地方
它是什么,本质是什么
Workers KV 是一个键值存储:你给一个字符串键(key),存一个字符串值(value),之后凭键取回来。就这么简单,没有表、没有行、没有查询语言。
它的设计取向非常鲜明:
| 维度 | KV 的表现 |
|---|---|
| 读取 | 数据复制到全球边缘节点,读的时候就近取,极快 |
| 写入 | 写进中心存储后,再逐步同步到全球各节点 |
| 一致性 | 最终一致:刚写完的值,其他地区可能要过一会儿(通常 60 秒内)才读得到 |
| 适合存 | 配置、开关、状态快照、缓存、探活结果 |
| 不适合存 | 账户余额、库存计数、需要读了立刻改的强一致数据 |
KV 的本质是「读多写少、能容忍几十秒延迟」的全球分发存储。理解这一点,后面所有用法和坑都顺理成章:探活结果每 5 分钟写一次、访客随时读,完美契合;而拿它当计数器高频自增,就是跟最终一致性对着干,迟早读到旧值算错账。
WARNING不要用 KV 存任何「写完必须立刻读到新值」的关键数据。典型反例:限流计数、秒杀库存、会话令牌的即时吊销。这类需求要的是强一致存储,应该去用 D1 或外部数据库(本篇结尾会再收束这条边界)。
建 namespace 与绑定
KV 的存储空间叫 namespace(命名空间),可以理解成「一个独立的键值仓库」。一个 Worker 可以绑多个 namespace,互不干扰。
第一步:建 namespace。 控制台在「Workers 和 Pages → KV」里新建;命令行则是一条:
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 子命令组可以直接读写:
# 写一个键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 是「分发到全球边缘的公告板」,不是账本。公告板上的字晚几十秒同步到所有人眼里没关系;账本上的数字错一位、晚一秒,都可能是事故。
排障
定时任务没触发
按这个顺序查,别乱猜:
- 表达式写错:字段顺序是分、时、日、月、星期,最常见的错误是把时和分写反,或者星期与日同时写了具体值导致语义叠加。用控制台触发器页面对照一遍,那里会把表达式和下一次触发时间直观列出来;
- 时区换算错位:任务其实跑了,只是跑在 UTC 换算后的时刻,和你预期的北京时间差 8 小时。去 Worker 的日志(控制台「日志」或
wrangler tail)里看 scheduled 的实际触发时间,一对便知; - 部署没带上 triggers:本地 wrangler.toml 改了 crons 但没重新
wrangler deploy,或者在控制台手动改完又被下一次 deploy 覆盖。记住两者以最后一次 deploy 的文件为准,改完必须部署; - 代码里没有 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。额度与计费细节以官方定价页为准,动手前扫一眼免费与付费的边界即可。