cloudflare

Cloudflare

概述

Cloudflare Workers 是一个无服务器边缘计算平台，可在 Cloudflare 的全球网络上运行 JavaScript、TypeScript 和 WebAssembly。Workers 使用 ES 模块格式，并提供 fetch、scheduled 和 queue 事件处理程序，通过环境绑定访问平台服务（KV、D1、R2、Durable Objects）。

适用场景： 边缘优先的 API、低延迟全球应用、无服务器函数、使用 Pages 托管静态网站、键值缓存、边缘关系型数据，以及无需出口费用的对象存储。

不适用场景： 超出 CPU 时间限制的长时间运行计算、需要持久 TCP 连接的工作负载、需要完整 Node.js API 兼容性的应用，以及更适合使用容器的大型单体应用。

快速参考

模式	API / 配置	要点
Fetch 处理程序	export default { fetch(request, env, ctx) }	HTTP 请求的入口点
定时处理程序	export default { scheduled(controller, env, ctx) }	通过配置中的 [triggers] 设置 Cron 触发器
环境变量	env.VAR_NAME	在 wrangler.toml 或控制面板中设置
KV 读写	env.KV.get(key) / env.KV.put(key, value)	最终一致，值最大为 25 MiB
D1 查询	env.DB.prepare(sql).bind(...params).all()	边缘上的 SQLite，使用预处理语句
D1 批处理	env.DB.batch([stmt1, stmt2])	原子事务，一次往返
R2 上传	env.BUCKET.put(key, body)	兼容 S3，无出口费用
R2 下载	env.BUCKET.get(key)	返回包含 ReadableStream 的 R2ObjectBody
Durable Objects	env.DO.get(id) 然后调用 stub.fetch(request)	单实例有状态协调
DO 存储	this.ctx.storage.sql.exec(query)	建议新建 DO 使用 SQLite 后端
Pages 部署	wrangler pages deploy <dir>	静态内容 + Functions，自动生成路由
Worker 部署	wrangler deploy	从 wrangler.toml 读取配置
开发服务器	wrangler dev	使用绑定进行本地开发
密钥	wrangler secret put SECRET_NAME	加密存储，不写入 wrangler.toml
静态资源	assets: { directory: "./dist" }	默认无需调用 Worker 即可提供服务
工作流	export class MyWorkflow extends WorkflowEntrypoint	持久化的多步执行引擎
Hyperdrive	env.HYPERDRIVE.connectionString	为外部 PostgreSQL 提供连接池
Queues 生产消息	env.QUEUE.send(message)	Worker 之间的异步消息传递
配置格式	wrangler.jsonc（新项目推荐使用）	带注释的 JSON；优先于 TOML

常见错误

错误	正确做法
将绑定作为全局变量访问	在模块格式中通过 env 参数访问
将机密存储在 wrangler.toml 中	对加密值使用 wrangler secret put
使用 KV 实现强一致性	使用 D1 或 Durable Objects 实现一致性读取
在 D1 查询中不绑定参数	始终使用 .prepare().bind() 防止 SQL 注入
超出 KV 值大小限制（25 MiB）	对于大于 25 MiB 的对象，使用 R2
忘记在存储操作中使用 await	KV、D1、R2 方法均为异步方法
使用 fetch() 时未传入 signal	传入 request.signal，以便自动取消
在 Worker 代码中创建 D1 数据库	使用 wrangler d1 create 创建，并在配置中绑定
配置中缺少 compatibility_date	始终设置该项，以避免发生破坏性变更
从 fetch 处理程序返回非 Response	必须返回 Response 对象
在新项目中使用 wrangler.toml	新项目使用 wrangler.jsonc；其 IDE 支持更好
使用 KV 执行关系查询	使用 D1 执行 SQL 查询；KV 仅支持键值存储

委派

• 架构审查：使用 Task Agent 评估边缘与源站模式
• 代码审查：委派给 code-reviewer Agent
• 存储选择：使用 Explore Agent 比较 KV、D1、R2 与 DO

参考资料

• Workers 语法、fetch 处理程序、定时事件和绑定
• KV、D1、R2 和 Durable Objects 存储 API
• Cloudflare Pages、函数、路由和构建配置
• Wrangler CLI、配置、开发服务器、部署和机密