Cloudflare Workers

概述

Cloudflare Workers 是一个无服务器执行环境，可在 Cloudflare 全球网络上运行 JavaScript、TypeScript、Python 和 Rust 代码。Workers 在毫秒级内启动，自动扩缩容，并通过绑定（bindings）与 Cloudflare 的存储和计算产品深度集成。

核心优势：

• 零冷启动 — Workers 运行于 V8 隔离环境（isolates），而非容器
• 全球部署 — 代码在遍布全球 300 多个城市的边缘节点运行
• 丰富生态 — 支持 D1、KV、R2、Durable Objects、Queues、Containers、Workflows 等多种绑定
• 全栈能力 — 单个项目即可构建 API 并托管静态资源
• 标准兼容 — 原生支持 Web 标准 API（fetch、crypto、streams、WebSockets）

适用场景

以下场景推荐使用 Cloudflare Workers：

• API 与后端服务 — RESTful API、GraphQL、tRPC、WebSocket 服务器
• 全栈应用 — React、Next.js、Remix、Astro、Vue、Svelte 等框架搭配静态资源托管
• 边缘中间件 — 身份认证、速率限制、A/B 测试、动态路由
• 后台任务处理 — 定时任务（cron）、队列消费者、Webhook 接收器
• 数据转换 — ETL 流水线、实时数据处理
• AI 应用 — RAG 系统、聊天机器人、基于 Workers AI 的图像生成
• 持久化工作流 — 支持自动重试的多步骤长周期任务（Workflows）
• 容器化工作负载 — 在 Workers 旁运行 Docker 容器（Containers）
• MCP 服务器 — 托管远程 Model Context Protocol 服务器
• 代理与网关 — API 网关、内容变换、协议转换

快速入门流程

1. 安装 Wrangler CLI

npm install -g wrangler

# 登录 Cloudflare 账户
wrangler login

2. 创建新 Worker

# 推荐方式：使用 C3（create-cloudflare）
npm create cloudflare@latest my-worker

# 或手动创建
wrangler init my-worker
cd my-worker

3. 编写 Worker 逻辑

基础 HTTP API（TypeScript）：

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);

    if (url.pathname === "/api/hello") {
      return Response.json({ message: "Hello from Workers!" });
    }

    return new Response("Not found", { status: 404 });
  },
};

结合环境变量与 KV：

interface Env {
  MY_VAR: string;
  MY_KV: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise {
    // 访问环境变量
    const greeting = env.MY_VAR;

    // 从 KV 读取数据
    const value = await env.MY_KV.get("my-key");

    return Response.json({ greeting, value });
  },
};

4. 本地开发

# 启动本地开发服务器（支持热重载）
wrangler dev

# 访问地址：http://localhost:8787

5. 部署至生产环境

# 部署到 workers.dev 子域名
wrangler deploy

# 部署到自定义域名（需在 wrangler.toml 中配置）
wrangler deploy

核心概念

Workers 运行时

Workers 基于 V8 JavaScript 引擎，并原生支持 Web 标准 API：

• 执行模型：隔离环境（isolates），非容器 — 实现即时冷启动
• CPU 时间限制：每次请求 10ms（免费版），30 秒（付费版）
• 内存限制：每个 isolate 最高 128 MB
• 支持语言：JavaScript、TypeScript、Python、Rust
• 可用 API：fetch、crypto、streams、WebSockets、WebAssembly

支持的 Web API：

• Fetch API（发起 HTTP 请求）
• URL API（URL 解析）
• Web Crypto（加解密、哈希）
• Streams API（数据流处理）
• WebSockets（实时双向通信）
• Cache API（边缘缓存控制）
• HTML Rewriter（HTML 内容改写）

处理器（Handlers）

Workers 通过不同事件处理器响应各类事件：

Fetch 处理器（HTTP 请求）：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return new Response("Hello!");
  },
};

Scheduled 处理器（定时任务）：

export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    // 按 wrangler.toml 中定义的时间表执行
    await env.MY_KV.put("last-run", new Date().toISOString());
  },
};

Queue 处理器（消息队列消费）：

export default {
  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
    for (const message of batch.messages) {
      await processMessage(message.body);
      message.ack();
    }
  },
};

绑定（Bindings）

绑定用于将 Worker 连接到 Cloudflare 各类资源，需在 wrangler.toml 中配置：

KV（键值存储）：

[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-namespace-id"

// 使用示例
await env.MY_KV.put("key", "value");
const value = await env.MY_KV.get("key");

D1（SQL 数据库）：

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"

// 使用示例
const result = await env.DB.prepare(
  "SELECT * FROM users WHERE id = ?"
).bind(userId).all();

R2（对象存储）：

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

// 使用示例
await env.MY_BUCKET.put("file.txt", "contents");
const object = await env.MY_BUCKET.get("file.txt");
const text = await object?.text();

环境变量：

[vars]
API_KEY = "development-key"  # pragma: allowlist secret

密钥（Secrets）（敏感信息）：

# 通过 CLI 设置（不写入 wrangler.toml）
wrangler secret put API_KEY

上下文（ctx）

ctx 参数提供对请求生命周期的精细控制：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // 在响应发送后异步执行任务
    ctx.waitUntil(
      env.MY_KV.put("request-count", String(Date.now()))
    );

    // 出现异常时透传至源站
    ctx.passThroughOnException();

    return new Response("OK");
  },
};

顶层环境访问（Top-level Environment Access）

自 2025 年 3 月起，您可在模块顶层直接导入 env，无需再通过处理器参数传递：

import { env } from "cloudflare:workers";

// 在处理器外部访问绑定
const apiClient = new ApiClient({ apiKey: env.API_KEY });

export default {
  async fetch(request: Request): Promise {
    // 此处亦可直接使用 env，无需声明参数
    const data = await env.MY_KV.get("config");
    return Response.json({ data });
  },
};

此举避免了函数签名中冗余的 env 参数传递（prop-drilling），并支持模块级初始化逻辑。

高效开发模式

Wrangler 配置

精简版 wrangler.toml 示例：

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-09-01"

# 自定义域名路由
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

# 或启用 workers.dev 子域名
workers_dev = true

# 环境变量
[vars]
ENVIRONMENT = "production"

# 绑定配置
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

[[d1_databases]]
binding = "DB"
database_name = "production-db"
database_id = "your-db-id"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

# 定时触发器
[triggers]
crons = ["0 0 * * *"]  # 每日午夜执行

环境管理

通过环境区分预发布（staging）与生产（production）：

[env.staging]
vars = { ENVIRONMENT = "staging" }

[env.staging.d1_databases]
binding = "DB"
database_name = "staging-db"
database_id = "staging-db-id"

[env.production]
vars = { ENVIRONMENT = "production" }

[env.production.d1_databases]
binding = "DB"
database_name = "production-db"
database_id = "production-db-id"

# 部署至 staging 环境
wrangler deploy --env staging

# 部署至 production 环境
wrangler deploy --env production

常用开发模式

带错误处理的 JSON API：

export default {
  async fetch(request: Request, env: Env): Promise {
    try {
      const url = new URL(request.url);

      if (url.pathname === "/api/users" && request.method === "GET") {
        const users = await env.DB.prepare("SELECT * FROM users").all();
        return Response.json(users.results);
      }

      if (url.pathname === "/api/users" && request.method === "POST") {
        const body = await request.json();
        await env.DB.prepare(
          "INSERT INTO users (name, email) VALUES (?, ?)"
        ).bind(body.name, body.email).run();
        return Response.json({ success: true }, { status: 201 });
      }

      return Response.json({ error: "Not found" }, { status: 404 });
    } catch (error) {
      return Response.json(
        { error: error.message },
        { status: 500 }
      );
    }
  },
};

身份认证中间件：

async function authenticate(request: Request, env: Env): Promise {
  const authHeader = request.headers.get("Authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return null;
  }

  const token = authHeader.substring(7);
  const userId = await env.SESSIONS.get(token);
  return userId;
}

export default {
  async fetch(request: Request, env: Env): Promise {
    const userId = await authenticate(request, env);

    if (!userId) {
      return Response.json({ error: "Unauthorized" }, { status: 401 });
    }

    // 继续处理已认证请求
    return Response.json({ userId });
  },
};

CORS 响应头设置：

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export default {
  async fetch(request: Request): Promise {
    if (request.method === "OPTIONS") {
      return new Response(null, { headers: corsHeaders });
    }

    const response = await handleRequest(request);

    // 向响应添加 CORS 头
    Object.entries(corsHeaders).forEach(([key, value]) => {
      response.headers.set(key, value);
    });

    return response;
  },
};

静态资源托管（全栈应用）

将静态文件与 Worker 代码一同部署：

[assets]
directory = "./public"
binding = "ASSETS"

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);

    // API 路由
    if (url.pathname.startsWith("/api/")) {
      return handleAPI(request, env);
    }

    // 通过 ASSETS 绑定提供静态资源
    return env.ASSETS.fetch(request);
  },
};

测试

使用 Vitest：

import { env, createExecutionContext } from "cloudflare:test";
import { describe, it, expect } from "vitest";
import worker from "./index";

describe("Worker", () => {
  it("responds with JSON", async () => {
    const request = new Request("http://example.com/api/hello");
    const ctx = createExecutionContext();
    const response = await worker.fetch(request, env, ctx);

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({ message: "Hello!" });
  });
});

框架集成

Workers 原生支持主流框架（通过适配器）：

• Next.js — 完整支持 App Router 与 Pages Router
• Remix / React Router — 官方 Cloudflare 适配器
• Astro — 在 Workers 上实现服务端渲染（SSR）
• SvelteKit — 提供 Cloudflare 适配器
• Hono — 专为 Workers 设计的轻量级 Web 框架
• tRPC — 类型安全 API，完整支持 Workers

Hono 示例：

import { Hono } from "hono";

const app = new Hono();

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

export default app;

进阶主题

如需了解高级功能的详细说明，请参阅以下参考文档：

• 完整绑定指南：references/bindings-complete-guide.md — 涵盖全部绑定类型（D1、KV、R2、Durable Objects、Queues、Workers AI、Vectorize、Workflows、Containers、Secrets Store、Pipelines、AutoRAG）
• 部署与 CI/CD：references/wrangler-and-deployment.md — Wrangler v4 迁移指南、命令详解、GitHub Actions 集成、GitLab CI/CD、渐进式发布、远程绑定配置
• 开发最佳实践：references/development-patterns.md — 测试策略、调试技巧、错误处理、性能优化、顶层 env 访问模式
• 高级特性：references/advanced-features.md — Containers、Workflows、MCP 服务器、Workers for Platforms、WebSockets、Node.js 兼容性、流式响应
• 可观测性：references/observability.md — 日志（tail、Logpush、Workers Logs）、指标（metrics）、链路追踪（traces）、调试方法

参考资料

官方文档：

• Workers：https://developers.cloudflare.com/workers/

• Wrangler CLI：https://developers.cloudflare.com/workers/wrangler/

• 运行时 API：https://developers.cloudflare.com/workers/runtime-apis/

• 示例代码：https://developers.cloudflare.com/workers/examples/

• Workflows：https://developers.cloudflare.com/workflows/

• Containers：https://developers.cloudflare.com/containers/

模板与快速启动：

• 模板库：https://developers.cloudflare.com/workers/get-started/quickstarts/
• 框架指南：https://developers.cloudflare.com/workers/framework-guides/

社区支持：

• Discord：https://discord.cloudflare.com
• GitHub：https://github.com/cloudflare/workers-sdk