Cloudflare Workers 中文文档

本文参照 Cloudflare 官方手册结构，对 Workers 做系统化梳理（数据截至 2026-10，配额/价格以官方最新页面为准）。技术术语保留英文原词以便对照官方资料。

1. 概述

Cloudflare Workers 是 Cloudflare 的无服务器计算平台：你编写代码，用一条命令部署到其全球边缘网络，无需管理任何服务器或复杂配置。它可用于构建前端应用、后端 API、AI 推理、定时任务等几乎任何类型的程序。

核心承诺：

• 边缘执行：代码运行在离用户最近的 Cloudflare 节点，延迟低、可靠性高。
• 多语言：原生支持 JavaScript / TypeScript / Python，Rust 等可通过 WebAssembly 运行；兼容 React、Vue、Svelte、Next、Astro 等框架。
• 免费起步、按需计费：灵活计价，任何规模都负担得起。

Free 与 Paid 计划均可用。

2. 核心概念

2.1 V8 Isolate（隔离）

Workers 运行在 V8 isolate 中，而非传统容器或虚拟机。多个 isolate 可以共享同一进程的内存，启动只需毫秒级，因此冷启动几乎无感。每个 isolate 的内存上限为 128 MB（包含 JS 堆与 WASM 分配）。

2.2 事件驱动模型

一个 Worker 本质是一个监听事件的处理器。最常见的是处理 HTTP 请求（fetch 事件），你导出一个 fetch 处理函数即可响应请求。

2.3 触发器（Triggers）

除了 HTTP 请求，Workers 还支持多种触发方式：

• HTTP 请求：通过路由（Routes）或自定义域名接收流量。
• Cron Triggers：按时间表定时执行。
• Queues：作为消息消费者处理队列。
• Durable Objects / Workflows / Email 等。

2.4 Bindings（绑定）

Bindings 是把外部资源（D1 数据库、R2 桶、KV 命名空间、Durable Objects、Queues、Vectorize、Workers AI 等）「绑」到 Worker 上的机制。绑定后，在代码里通过 env.XXX 直接访问，无需管理密钥与连接池。

2.5 Wrangler

官方命令行工具，用于初始化、本地开发、部署 Worker 项目，以及管理 D1/R2/KV 等资源。

2.6 Smart Placement（智能放置）

可让 Worker 自动调度到离其依赖的数据源（如数据库）更近的位置，以降低端到端延迟。

2.7 CPU 时间 vs 挂钟时间

CPU 时间只统计真正执行代码的时间；await fetch()、访问 KV/D1/R2 等网络等待不计入 CPU 时间。这一区分对理解配额至关重要。

3. 工作原理与架构

• Worker 代码被打包后分发到全球边缘节点；请求到达时，就近的节点拉起 isolate 执行。
• 因为基于 isolate，启动快、密度高；极端情况下（如内存超限）运行时会让在途请求完成后新建 isolate。
• 全局代码（global scope）必须在 1 秒内完成解析与执行。

4. 快速开始

# 1. 安装 Wrangler
npm install -g wrangler

# 2. 登录 Cloudflare
wrangler login

# 3. 初始化项目（按提示选择模板）
wrangler init my-worker

# 4. 本地开发（默认就近远程资源调试）
wrangler dev

# 5. 部署到全球边缘
wrangler deploy

最小 fetch 处理函数（src/index.ts）：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("Hello from the edge!");
  },
} satisfies ExportedHandler<Env>;

5. 配置与绑定

wrangler.jsonc 是 Worker 的配置文件，示例（含常用绑定）：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "vars": { "GREETING": "hello" },
  "routes": [{ "pattern": "example.com/*", "custom_domain": true }],
  "triggers": { "crons": ["0 * * * *"] },
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<id>" }
  ],
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ],
  "kv_namespaces": [
    { "binding": "KV", "id": "<namespace-id>" }
  ]
}

要点：

• 环境变量：Free 每 Worker 64 个、Paid 128 个，单变量 ≤ 5 KB。
• 路由与域名：每 zone 路由 1,000；每 zone 自定义域 100。
• Cron Triggers：Free 5 个 / 账户，Paid 250 个。
• 静态资源（assets）：可把 CSS/JS/图片等部署到 CDN 层，命中后不计 Worker 调用。

6. 配额与限制

其他硬性限制：

• URL ≤ 16 KB；请求头 ≤ 128 KB；响应头 ≤ 128 KB；响应体无强制上限。
• 请求体大小取决于主账户计划：Free/Pro/Business 100 MB，Enterprise 最高 5 GB。
• CDN 缓存对象上限：Free/Pro/Business 512 MB，Enterprise 5 GB。
• Cache API 单次请求调用次数：50（Free）/ 1,000（Paid），与 fetch 子请求共享配额；缓存对象最大 512 MB。
• 每请求日志数据上限 256 KB。
• 超限表现：免费日请求超限返回 Error 1027；CPU/内存超限返回 Error 1102。

7. 定价

• Workers Free：永久免费，含上表免费额。
• **Workers Paid（约 ****$5/月）**：解锁 Paid 配额（无限请求、更长 CPU 时间等），超出部分按 Workers 计价规则计费。具体以官方定价页为准。

8. 最佳实践

• 用 Smart Placement 让计算靠近数据源；把静态资源交给 assets / CDN 层，可不计 Worker 调用。
• 减少子请求次数，善用缓存（Cache API / KV）避免每次请求都回源。
• 控制 CPU 时间：await 的网络 IO 不计入，但应避免在主线程做重计算。
• 免费层每天 10 万请求，中小站点通常够用；预估流量接近上限时及时升级 Paid。

9. 适用场景与选型

• 给现有站点/API 包一层边缘逻辑（鉴权、改写、A/B）。
• 全栈 Web 应用（框架 + 存储产品）。
• 定时任务、后台作业、Serverless AI 推理、边缘无头浏览器。
• 任何需要「跑代码」的场景，都是这套 Serverless 技术栈的入口；配合 D1/R2/KV 即可组成完整应用。