cloudflare-workers 快速入门

让 AI 帮你写 Cloudflare Workers 时,默认按 Wrangler + Bindings 的官方推荐模式产出可部署代码。

这是什么?解决什么问题?

cloudflare-workers 对应 Cloudflare 官方在 cloudflare/skills 仓库下提供的边缘计算开发 Skill。Cloudflare Workers 是基于 V8 Isolates 的 Serverless 平台,允许你在 200+ 数据中心的边缘节点跑 JavaScript / TypeScript / Rust 代码,冷启动 < 5ms,按请求计费。

这个 Skill 解决的问题,和大多数新手第一次用 Workers 时遇到的痛点一致:

• Wrangler 配置怎么写?wrangler.toml 里的 compatibility_date、main、compatibility_flags 一堆字段,版本号错了就直接报错。
• Bindings 是什么?Workers 不能直接访问外部数据库,必须通过 Bindings(KV、D1、R2、Queues、Hyperdrive、Service Bindings)注入。
• 本地开发怎么模拟生产环境?wrangler dev 在本地起一个模拟环境,但和生产 Workers 实际行为有差异。
• 部署策略怎么选?直接 wrangler deploy 还是用 GitHub Actions 自动化?要不要加环境(staging / production)?

Skill 沉淀的模式包括 Wrangler 配置规范、Bindings 模式选型、路由与域名配置、多环境部署策略、Bundle 体积控制。

如果你正在设计一个对延迟敏感、对全球分布有要求、又不希望自己运维服务器的应用,Cloudflare Workers 是一个非常值得考虑的选择。它和传统 FaaS(AWS Lambda、Vercel Functions)最大的区别在于:Lambda 在一个区域内运行,Workers 直接在 200+ 边缘节点运行,大多数请求会被路由到离用户最近的那个节点,冷启动几乎不可感知。

这个 Skill 的真正价值,不是教你”用 Workers 写一个 hello world”,而是教 AI 在以下场景里按 Cloudflare 官方推荐的最佳实践产出代码:

• 新项目从零搭建 Wrangler 配置文件,包括 compatibility_date、main、compatibility_flags 等容易踩坑的字段。
• 为 Workers 选择合适的存储后端——什么时候用 KV(键值缓存)、什么时候用 D1(关系型)、什么时候用 R2(对象存储)、什么时候用 Queues(消息队列),Skill 里有清晰的选型表。
• 配置多环境(staging / production)的工作流,避免误把测试代码部署到生产。
• 排查 Bundle 体积过大、CPU 时间超时等性能问题。

对于习惯了 Node.js 生态的开发者,Workers 的”基于 V8 Isolates”模型有几个反直觉的地方:不能直接用 Node 内置库,没有 fs、path 这种模块,所有 IO 都要走 fetch + Web Streams。Skill 会主动帮 AI 避开这些坑,避免你写完代码部署时才报错。

准备工作

1. 一个支持 Skill 加载的 AI 编程助手(Claude Code / Cursor)。
2. Cloudflare 账号(免费版即可,https://dash.cloudflare.com/sign-up)。
3. Node.js 18+ 与 npm。
4. 安装 Wrangler CLI:

   npm install -g wrangler
   wrangler --version
   

5. 登录:wrangler login
6. Clone 仓库 + 软链 Skill:

   git clone https://github.com/cloudflare/skills.git
   ln -s skills/cloudflare-workers ~/.claude/skills/cloudflare-workers
   

3 步快速上手

第 1 步:初始化项目

mkdir my-worker && cd my-worker
wrangler init

会问几个问题:要不要用 TypeScript?(选 Yes)、要不要用 Workers Assets?(选 No),最后生成 src/index.ts + wrangler.toml。

第 2 步:验证安装

向 AI 发送请求:

“用 cloudflare-workers 帮我写一个 KV 读写的 Worker,KV 命名空间叫 MY_KV。”

如果 AI 输出的 wrangler.toml 里有 [[kv_namespaces]] 配置,代码里用 env.MY_KV.get(...),说明 Skill 加载成功。

第 3 步:用 cloudflare-workers 跑第一个任务

让 AI 帮你写一个带 KV 缓存的简单 Workers:

wrangler.toml:

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-05-01"

[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxx"

[vars]
ENVIRONMENT = "production"

src/index.ts:

export interface Env {
  MY_KV: KVNamespace;
  ENVIRONMENT: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const key = url.pathname.slice(1) || 'default';

    const cached = await env.MY_KV.get(key);
    if (cached) {
      return new Response(cached, {
        headers: { 'X-Cache': 'HIT', 'Content-Type': 'application/json' },
      });
    }

    const data = JSON.stringify({
      message: 'Hello from Cloudflare Workers',
      env: env.ENVIRONMENT,
      timestamp: Date.now(),
    });

    await env.MY_KV.put(key, data, { expirationTtl: 60 });

    return new Response(data, {
      headers: { 'X-Cache': 'MISS', 'Content-Type': 'application/json' },
    });
  },
};

本地测试 + 部署:

wrangler dev      # 本地 http://localhost:8787
wrangler deploy   # 30 秒后全球 200+ 节点生效

常见踩坑

1. compatibility_date 不更新。Workers 平台每 2-4 周发新版本,Skill 建议每季度更新一次。
2. 忘记创建 KV 命名空间。wrangler.toml 写了 binding 但没跑 wrangler kv:namespace create,部署报错。
3. Bundle 体积超 1MB。免费版 Workers 编译后 bundle 上限 1MB,引入整个 lodash 就会爆,Skill 建议按需 import。
4. 同步阻塞调用。Workers 里用 fs.readFileSync / axios 等 Node 内置库会直接报 “Module not found”,要用 fetch + Web Streams。
5. CPU 时间超 10ms(免费)/ 50ms(付费)。同步 for 循环处理 100 万条数据会超时,Skill 建议拆分到 Queues 异步处理。
6. 本地与生产行为不一致。wrangler dev 模拟了大多数 Bindings,但 Secrets 不会从生产拉取,Skill 建议本地用 .dev.vars 文件。

初级用法

用法 1:API 反向代理。让 AI 帮你写一个 Worker 代理到上游 API,顺便加 KV 缓存 + 鉴权头注入。

用法 2:CDN 边缘逻辑。让 AI 帮你写一个 Worker 改写响应头(加 CORS、安全头),绑定到自定义域名的 routes 字段。

用法 3:D1 数据库读写。让 AI 帮你配置 D1(SQLite at the edge),用 env.DB.prepare(...).all() 查数据。

高级玩法

玩法 1:Service Bindings 串联微服务。让 AI 帮你配 [[services]] binding,Worker A 直接调 Worker B,延迟 < 1ms。

玩法 2:Hyperdrive 连接外部 Postgres。让 AI 帮你配 Hyperdrive,让 Workers 直接连 RDS / Supabase / Neon 等外部 Postgres,带连接池与缓存。

玩法 3:Cron Triggers 定时任务。让 AI 帮你配 [triggers] crons = ["0 */6 * * *"],每 6 小时跑一次清理任务。

小技巧

1. 用 wrangler tail 看实时日志。wrangler tail --format pretty,生产环境调试神器。
2. Secrets 走 wrangler secret put。API key、数据库密码用它管理,加密存储,别写在 wrangler.toml 里。
3. 测试用 vitest + @cloudflare/vitest-pool-workers。在 vitest 里直接跑 Workers 代码,不用起 wrangler dev。
4. 环境变量分文件管理。wrangler.toml 默认 + wrangler.production.toml 覆盖,避免一个文件里堆几十个 env。
5. 监控 Workers Analytics。Dashboard → Workers → Analytics,看 P50 / P99 延迟、错误率、CPU 时间,Skill 建议设置告警阈值。

实战建议

如果你打算把 Cloudflare Workers 用在生产环境,有几条来自 Skill 的实战经验值得记下来。

第一,compatibility_date 不要写老日期。很多教程为了让代码”兼容性好”,会把 compatibility_date 设成 2023 或更早,实际上 Cloudflare 推荐的做法是设为发布前 6 个月内的某个固定日期,这样既保证稳定,又能用到相对新的 Web 标准。每季度 review 一次,逐步往前推,这是 Skill 反复强调的节奏。

第二,Bundle 体积要看 wrangler deploy 的输出。本地看不到最终 bundle,只有部署那一刻 Cloudflare 才会真正编译。wrangler deploy --dry-run --outdir=dist 可以先输出 bundle 到本地,用 du -sh dist/* 看每个文件多大,优先优化大的。

第三,CPU 时间监控必加。Workers 免费版限制 10ms CPU 时间,看起来很短,但对绝大多数边缘函数其实够用。关键是要在代码里加时间埋点:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const start = Date.now();
    // ... 业务逻辑
    ctx.waitUntil(
      fetch(`https://metrics.example.com/cpu?ms=${Date.now() - start}`)
    );
    return new Response('ok');
  },
};

第四,多环境用 [env.production] 隔离。wrangler.toml 用 [env.staging] 和 [env.production] 两节,绑定不同的 KV namespace、不同的 routes,部署时 wrangler deploy --env production,杜绝误操作。

第五,Secrets 走 Cloudflare Dashboard。除了 wrangler secret put,也可以在 Dashboard → Workers → Settings → Variables 里手动加,适合非技术同事管理。Skill 强调”API key 绝不出现在 git 历史里”,所以哪怕是临时调试,也要用 secret 而不是写在代码里。

最后,如果你的 Workers 调用了外部 API,必须加重试和超时。Workers 的 fetch 默认 30 秒超时,但实际生产应该用 AbortController 设 3-5 秒,外部 API 慢就快速失败,而不是拖垮整个 Worker。 另外,Skill 提醒在选型阶段就要把 Workers 的局限说清楚:它不是万能的,长任务(超过 30 秒)必须拆,大文件下载(超过 100MB)最好用 R2 走 presigned URL,而不是让 Worker 当代理。理解边界,才能让 Workers 真正发挥边缘计算的优势。

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);
try {
  const res = await fetch('https://slow-api.example.com', { signal: controller.signal });
  return res;
} finally {
  clearTimeout(timeout);
}

参考链接

• cloudflare-workers Skill 仓库:https://github.com/cloudflare/skills
• Cloudflare Workers 官方文档:https://developers.cloudflare.com/workers/
• Wrangler CLI 文档:https://developers.cloudflare.com/workers/wrangler/
• D1 文档:https://developers.cloudflare.com/d1/
• R2 文档:https://developers.cloudflare.com/r2/
• Hyperdrive 文档:https://developers.cloudflare.com/hyperdrive/

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。