infra-platform-cloudflare-workers

Cloudflare Workers 模式

**快速指南：**Cloudflare Workers 在 Cloudflare 的全球边缘网络上使用 V8 隔离环境（而非容器）运行 TypeScript/JavaScript。使用 wrangler.jsonc 进行配置，使用 wrangler dev 进行本地开发，并使用 wrangler deploy 部署到生产环境。通过 env 参数上的类型安全绑定访问 KV、D1、R2、Queues、Durable Objects 和 Workers AI。运行 wrangler types 自动生成 Env 接口。对大型负载进行流式处理——Workers 的内存限制为 128 MB。切勿将请求作用域的状态存储在模块级变量中。

---

<critical_requirements>

重要：使用此技能前

（必须运行 wrangler types 生成 Env 接口——切勿手动编写绑定类型）

（新项目必须使用 wrangler.jsonc——Cloudflare 推荐使用 JSON 配置，且某些功能仅支持 JSON）

（必须对大型请求/响应正文进行流式处理——切勿将完整负载缓冲到内存中（内存限制为 128 MB））

（必须避免模块级可变状态——Workers 会在多个请求间复用 V8 隔离环境，导致请求间数据泄漏）

（必须使用 Cloudflare 服务（KV、D1、R2、Queues）的绑定——切勿在 Workers 内使用 REST API）

</critical_requirements>

---

示例

• 核心设置与配置 — wrangler.jsonc、项目初始化、fetch 处理器、密钥、多环境、CI/CD、测试
• KV 存储 — KV 绑定、类型化 get/put、TTL、stale-while-revalidate 缓存
• D1 数据库 — D1 绑定、参数化查询、批量操作、迁移、CRUD API
• R2 对象存储 — R2 绑定，通过流式传输上传／下载／删除文件
• Durable Objects — DO 类、SQLite、RPC、速率限制器、WebSocket 聊天
• 路由与中间件 — API 框架集成、中间件、队列、cron、服务绑定、AI、流式传输
• 快速参考 — Wrangler CLI 命令、绑定类型签名、配置模板、CPU 限制

---

自动检测： Cloudflare Workers、wrangler、wrangler.toml、wrangler.jsonc、Workers KV、Cloudflare KV、D1 数据库、R2 存储桶、Durable Objects、Cloudflare Queues、Workers AI、服务绑定、miniflare、compatibility_date、compatibility_flags、nodejs_compat、cloudflare:workers、ExportedHandler、DurableObject、wrangler dev、wrangler deploy、wrangler types、Cloudflare Pages Functions、边缘 Worker、CF Worker

适用场景：

• 将 TypeScript/JavaScript 部署到 Cloudflare 边缘网络
• 配置 Wrangler CLI 以进行本地开发和部署
• 使用 Cloudflare 绑定：KV、D1、R2、Queues、Durable Objects、Workers AI
• 使用框架（例如 Hono）在 Workers 上构建 API
• 使用 Durable Objects 和 WebSockets 实现实时功能
• 设置 cron 触发器和定时处理器
• 配置服务绑定以实现 Worker 间通信
• 管理环境变量、密钥和多环境部署

不适用场景：

• 超出 CPU 时间限制的长时间运行计算任务（使用传统服务器或 Workflows）
• 需要与外部数据库建立持久 TCP 连接，且未使用 Hyperdrive 的应用
• 每个请求需要超过 128 MB 内存的工作负载

涵盖的关键模式：

• Wrangler 配置（wrangler.jsonc）和项目设置
• Fetch 处理器、定时处理器和队列处理器
• KV 键值存储（缓存、配置、会话数据）
• D1 SQLite 数据库（边缘上的关系型数据）
• 与 S3 兼容的 R2 对象存储（文件、上传内容、资源）
• Durable Objects（有状态边缘计算、WebSockets、协调）
• Cloudflare Queues（异步消息处理）
• Workers AI（边缘推理）
• 框架集成（Hono 示例）及类型化绑定
• 环境变量、密钥和多环境配置
• 服务绑定（Worker 间 RPC）
• Cron 触发器和定时 Workers
• 流式传输和性能优化
• 使用 Workers 原生测试池进行测试

---

## 理念

Cloudflare Workers 在全球 300 多个数据中心的 V8 isolate（而非容器）上运行。它们可在 5 毫秒内启动，且没有冷启动。其编程模型与传统服务器有根本区别：

1. 绑定优先于 API - 通过 env 参数上的进程内直接绑定访问 Cloudflare 服务（KV、D1、R2、Queues），而非调用 REST API。绑定无需经过网络，也没有身份验证开销。
2. 默认无状态 - 每个请求都会获得全新的执行上下文。Workers 会复用 V8 isolate，因此模块级变量会跨请求保留——这是错误来源，而非功能特性。
3. 全程使用流 - Workers 的内存限制为 128 MB。不要缓冲数据；使用 TransformStream 和 pipeTo 流式处理请求和响应正文。
4. 边缘优先架构 - 代码在离用户最近的位置运行。需要协调或状态时使用 Durable Objects；需要持久化时使用 D1/KV/R2。

适用场景：

• API 端点、中间件和请求路由
• 缓存层和内容转换
• Webhook 接收器和事件处理器
• 实时协作（结合 Durable Objects）
• 全栈应用（结合 Workers Static Assets 或 Pages）

不适用场景：

• 超出限制的 CPU 密集型计算（每个请求免费版 10 毫秒 / 付费版 30 秒）
• 需要超过 128 MB 内存的工作负载
• 需要持久数据库连接的应用（使用 Hyperdrive 作为代理）
• 超出限制的长时间运行后台作业（使用 Workflows 实现持久执行）

---

核心模式

模式 1：项目设置和 Wrangler 配置

每个 Workers 项目都从 wrangler.jsonc 开始。Cloudflare 推荐使用 JSON 格式——一些较新的功能仅支持 JSON。更改绑定后运行 wrangler types，以重新生成 Env 接口。

// wrangler.jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-api",
  "main": "src/index.ts",
  "compatibility_date": "2025-09-15",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true },
  "placement": { "mode": "smart" },
  "upload_source_maps": true,
}

完整的项目初始化、多环境配置、密钥管理、CI/CD 和测试设置，请参阅 examples/core.md。

---

模式 2：Fetch 处理器（请求/响应）

Fetch 处理器是 HTTP 请求的入口点。使用 satisfies ExportedHandler<Env> 确保类型安全。

import type { ExportedHandler } from "cloudflare:workers";

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === "/health") {
      return Response.json({ status: "healthy" });
    }
    return new Response("Not Found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

切勿在模块级变量中存储可变状态——V8 isolate 复用会导致跨请求数据泄漏。包含 CORS 和路由的完整处理器，请参阅 examples/core.md。

---

模式 3：KV 键值存储

KV 是一种最终一致的键值存储，适用于读多写少的工作负载。使用类型化的 get<T>(key, "json")，务必设置 expirationTtl，并使用 ctx.waitUntil() 执行非阻塞写入。

const CACHE_TTL_SECONDS = 3_600;
const profile = await env.CACHE.get<UserProfile>(`user:${id}`, "json");
ctx.waitUntil(
  env.CACHE.put(`user:${id}`, JSON.stringify(data), {
    expirationTtl: CACHE_TTL_SECONDS,
  }),
);

适用场景： 读多写少的工作负载（配置、缓存、功能标志），且可以接受最终一致性（传播约需 60 秒）。

不适用场景： 关系型数据（使用 D1）、频繁写入同一个键、需要强一致性的场景（使用 Durable Objects）。

过期后重新验证模式和完整缓存示例，请参阅 examples/kv.md。

---

模式 4：D1 SQLite 数据库

D1 是边缘端的无服务器 SQLite。务必通过 prepare().bind() 使用参数化查询，以防止 SQL 注入。使用 batch() 执行原子多语句操作。启用读取副本复制时，使用 withSession() 确保读取副本的一致性。

const user = await db
  .prepare("SELECT * FROM users WHERE email = ?")
  .bind(email)
  .first<User>();

const { results } = await db
  .prepare("SELECT * FROM users LIMIT ? OFFSET ?")
  .bind(DEFAULT_PAGE_SIZE, offset)
  .all<User>();

迁移、批量操作和完整 CRUD API，请参阅 examples/d1.md。

---

模式 5：R2 对象存储

R2 是兼容 S3 的存储服务，不收取出口流量费用。务必将 R2 正文直接流式传输到响应中——对于大型对象，切勿调用 .arrayBuffer() 或 .text()。

const object = await env.BUCKET.get(key);
if (!object) return new Response("Not Found", { status: 404 });
const headers = new Headers();
object.writeHttpMetadata(headers);
return new Response(object.body, { headers }); // Stream directly

包含内容类型验证和列表操作的文件服务示例，请参阅 examples/r2.md。

---

### 模式 6：Durable Objects（有状态边缘计算）

Durable Objects 提供单线程、强一致性的计算能力。每个实例都有 SQLite 存储。使用 RPC 方法（而非 fetch），并使用 blockConcurrencyWhile 进行架构迁移。

import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS ...");
    });
  }
  async increment(name: string): Promise<number> {
    /* RPC method */
  }
}

**适用场景：**协调（聊天、协作）、实体级状态（会话、游戏实例）、WebSocket 连接、速率限制。

**不适用场景：**无状态请求、高扇出、全局速率限制（会形成瓶颈）。

请参阅 examples/durable-objects.md，了解带休眠功能的速率限制器和 WebSocket 聊天示例。

---

模式 7：队列、Cron、服务绑定、Workers AI

队列通过至少一次投递和可配置的重试机制，将生产者与消费者解耦。Cron 触发器按计划调用 Workers。服务绑定支持零成本的 Worker 间调用。Workers AI 在 Cloudflare 的 GPU 网络上运行推理。

请参阅 examples/routing.md，了解这些模式的完整配置和代码示例。

---

模式 8：API 框架集成

对于结构化 API，请使用带类型化绑定的路由框架。除定时任务/队列处理程序外，还要导出该框架的 fetch 处理程序。

import { Hono } from "hono";
const app = new Hono<{ Bindings: Env }>();

app.get("/users/:id", async (c) => {
  const user = await c.env.DB.prepare("SELECT * FROM users WHERE id = ?")
    .bind(c.req.param("id"))
    .first();
  return user ? c.json(user) : c.json({ error: "Not found" }, 404);
});

export default app;

请参阅 examples/routing.md，了解包含中间件、错误处理和多处理程序配置的生产级 API。

---

性能优化

请求处理

技术	影响
智能放置（"mode": "smart"）	根据绑定的位置将请求路由到最佳数据中心
流式响应	避免 128 MB 内存限制，改善 TTFB
使用 ctx.waitUntil() 处理后台任务	立即返回响应，之后再处理异步任务
nodejs_compat 标志	访问 Node.js 内置模块（crypto、buffer、stream）

存储性能

存储	读取	写入	一致性	最适合
KV	快（边缘缓存）	慢（约 60s 传播）	最终一致性	缓存、配置、标志
D1	中等	中等	强一致性（区域内）	关系数据、查询
R2	中等	中等	强一致性	文件、二进制对象、上传
Durable Objects	快（内存中）	快（SQLite）	强一致性（单线程）	协调、实时处理

用于外部数据库的 Hyperdrive

连接 Cloudflare 外部的 PostgreSQL/MySQL 时，务必使用 Hyperdrive。它会在靠近数据库的位置维护连接池，从而消除每个请求的 TCP/TLS 开销。

CPU 时间限制

方案	每个请求的 CPU 时间
免费	10 ms
付费	30 秒（默认），可配置至 15 分钟
Cron 触发器	15 分钟

---

<decision_framework>

决策框架

选择存储原语

What kind of data?
  |
  +-- Key-value pairs (cache, config, sessions)
  |     +-- Read-heavy, eventual consistency OK --> KV
  |     +-- Strong consistency needed --> Durable Objects
  |
  +-- Relational data with queries
  |     +-- Edge-native SQLite --> D1
  |     +-- External PostgreSQL/MySQL --> Hyperdrive
  |
  +-- Files and blobs (images, documents)
  |     +-- S3-compatible storage --> R2
  |
  +-- Coordination state (chat, multiplayer, collaboration)
  |     +-- Single-threaded consistency --> Durable Objects
  |
  +-- Message passing / background work
        +-- Simple fan-out, buffering --> Queues
        +-- Multi-step durable execution --> Workflows

在 Workers 和 Pages 之间进行选择

What are you building?
  |
  +-- API only (no frontend) --> Workers
  |
  +-- Static site + API --> Pages with Functions
  |
  +-- Full-stack with SSR --> Pages (framework) or Workers + Static Assets
  |
  +-- Background processing / cron --> Workers (Pages lacks cron support)
  |
  +-- Real-time / WebSockets --> Workers + Durable Objects

何时使用 Durable Objects，何时使用 D1

Do you need coordination between concurrent requests?
  |
  +-- YES (chat, game, collaboration) --> Durable Objects
  |     +-- Single-threaded, no race conditions
  |     +-- WebSocket support with hibernation
  |     +-- Per-entity sharding (one DO per room/session)
  |
  +-- NO (CRUD, reporting, querying) --> D1
        +-- Full SQL support
        +-- Cross-entity queries
        +-- Traditional database patterns

</decision_framework>

---

## 集成指南

Cloudflare 平台服务：

• Hyperdrive：外部 PostgreSQL/MySQL 的连接池代理，可消除每个请求的 TCP/TLS 开销
• Vectorize：用于存储嵌入向量和配合 Workers AI 进行语义搜索的向量数据库
• Cloudflare Pages：静态网站托管服务，可通过 Workers 驱动的函数构建全栈应用
• GitHub Actions：使用 cloudflare/wrangler-action@v3 进行 CI/CD 部署

框架与 ORM 兼容性：

Workers 与支持 V8 运行时且针对边缘环境优化的框架和 ORM 兼容。任何导出 fetch 处理程序的框架都可使用（如 Hono、itty-router 等）。D1 可与任何支持 SQLite 的 ORM 搭配使用（请查阅 ORM 的 Workers 兼容性文档）。

测试：

使用 @cloudflare/vitest-pool-workers，在实际的 Workers 运行时中，借助真实绑定（KV、D1、R2）运行测试。测试配置请参阅 examples/core.md。

---

<red_flags>

危险信号

高优先级问题：

• 将请求范围的数据存储在模块级变量中（V8 隔离环境会被重复使用，导致请求间数据泄漏）
• 使用 .text() / .arrayBuffer() 缓冲整个请求或响应正文（内存上限为 128 MB）
• 不运行 wrangler types，而是手写 Env 接口（导致配置与代码不匹配）
• 在 Workers 中使用 REST API 访问 KV/D1/R2/Queues，而不是使用绑定（造成不必要的延迟和身份验证开销）
• 将密钥放在 wrangler.jsonc、源代码或环境变量中（使用 wrangler secret put）
• 为所有流量创建单个全局 Durable Object（约 1000 req/sec 时会形成瓶颈）

中优先级问题：

• 为新项目使用 wrangler.toml（推荐使用 JSON 格式，部分功能仅支持 JSON）
• compatibility_date 过时（无法获得运行时改进和错误修复）
• 缺少 observability 配置（生产环境中的 Workers 会成为没有日志或追踪信息的黑箱）
• 在 fetch 处理程序中解构 ctx（会丢失 this 绑定，导致 ctx.waitUntil 抛出 "Illegal invocation"）
• 使用 exec() 执行 D1 查询，而不是使用 prepare().bind()（没有参数化查询，存在 SQL 注入风险）
• 未在 Durable Objects 中对 WebSocket 关闭操作进行回应（会导致 1006 错误）

常见错误：

• 忘记 KV 是最终一致的（传播约需 60s），却期望写入后立即读取到最新数据
• 使用 Math.random() 生成安全敏感令牌（使用 crypto.randomUUID() 或 crypto.getRandomValues()）
• 未使用 ctx.waitUntil() 执行响应后的后台工作（响应发出后，工作可能会被取消）
• 使用 === 比较密钥，而不是使用 crypto.subtle.timingSafeEqual()（可能遭受计时侧信道攻击）
• 使用 passThroughOnException() 处理错误（会掩盖错误，应使用显式的 try/catch）
• Promise 未等待、未返回，也未传递给 waitUntil()，导致静默失败 — 启用 @typescript-eslint/no-floating-promises，以便在开发时发现此类问题

注意事项与边缘情况：

• 绑定（KV、D1、R2 等）不会跨 Wrangler 环境继承 — 必须在每个环境中重新声明
• wrangler dev 默认使用本地模拟；使用 --remote 可针对 Cloudflare 的真实服务进行测试
• D1 批量操作按顺序执行（而不是并行执行），但具有原子性
• Durable Objects 的内存状态会在驱逐时丢失 — 请务必先将重要数据持久化到 SQLite
• 在 DO 存储写入之间进行不必要的 await 会破坏写入合并 — 写入之间不进行 await 时，批量写入会以原子方式执行
• DO 闹钟处理程序可能会触发多次 — 请将其设计为幂等
• 在每个请求上使用 blockConcurrencyWhile() 会将吞吐量限制在约 200 req/sec — 仅在初始化时使用
• 免费套餐上的 Workers 每个请求的 CPU 时间限制为 10ms（不是墙钟时间 — I/O 等待不计费）
• Cron 触发器变更最多需要 15 分钟才能全局生效
• .dev.vars 文件仅用于本地密钥，必须加入 gitignore
• env 参数由运行时按请求提供；避免在模块作用域缓存绑定引用或派生对象

</red_flags>

---

<critical_reminders>

重要提醒

（必须运行 wrangler types 以生成 Env 接口 — 绝不可手写绑定类型）

（新项目必须使用 wrangler.jsonc — Cloudflare 推荐使用 JSON 配置，且部分功能仅支持 JSON）

（必须对大型请求或响应正文进行流式处理 — 绝不可将整个负载缓冲到内存中（上限为 128 MB））

（必须避免模块级可变状态 — Workers 会在多个请求之间重复使用 V8 隔离环境，导致请求间数据泄漏）

（必须对 Cloudflare 服务（KV、D1、R2、Queues）使用绑定 — 绝不可在 Workers 中使用 REST API）

不遵守这些规则会导致内存崩溃（缓冲）、数据泄漏（模块状态）、类型不匹配（手写 Env）、不必要的延迟（使用 REST 而非绑定）以及密钥泄露（将密钥放在配置中）。

</critical_reminders>