Cloudflare Workers 入门

知识图谱你要学什么

⚡

Workers 运行时

V8 隔离环境，<1ms 冷启动，全球 300+ 边缘节点就近响应

🔄

Fetch 事件

通过 addEventListener("fetch") 拦截并处理 HTTP 请求

🗺️

路由与中间件

请求分发、CORS 处理、日志拦截等中间件链模式

💾

KV 存储

Cloudflare 的分布式键值存储，全局低延迟读写

🔐

环境变量

bindings / secrets / wrangler.toml 配置管理

🚀

部署与 Wrangler

本地开发、预览部署、生产发布全流程

核心概念

V8 隔离

每个 Worker 在独立的 V8 Isolate 中运行，冷启动 < 1ms，资源隔离，无容器开销

全局共享

代码和常量在每个请求间复用，但变量不共享（除非用 Durable Objects / KV）

Fetch 事件

每个 HTTP 请求触发一次 fetch 事件，通过 event.respondWith() 返回 Response

Request / Response

基于 Web Standards 的 Fetch API，与浏览器中完全一致，无需重新学习

KV 绑定

分布式键值存储，通过 env.MY_KV.get(key) 读取，写操作最终一致

Secrets 绑定

通过 wrangler secret put 注入，代码中通过 env.MY_SECRET 读取，不暴露明文

Level 1 — 认识 ~25 分钟

目标：理解 Worker 的请求-响应模型，能够读取 Request 对象并构造 Response。

📌 任务 1：模拟一个 Cloudflare Worker

Cloudflare Worker 通过 addEventListener("fetch") 拦截请求，用 event.respondWith() 返回响应。下面用浏览器模拟这个流程。

编辑器 — 修改下面的代码

输出

点击 "运行代码" 查看结果...

💡 需要提示？点击查看

// 任务 A：将 status 改为 201，message 改为 "已创建"
return new Response(
  JSON.stringify({ message: "已创建", status: 201 }),
  { headers: { "Content-Type": "application/json" } }
);

// 任务 B：添加 echo 端点
else if (url.pathname === "/api/echo") {
  return new Response(
    JSON.stringify({ method: method, path: url.pathname }),
    { headers: { "Content-Type": "application/json" } }
  );
}

我已成功让 Worker 返回了正确的 JSON 响应（任务 A + B）

Level 2 — 引导实践 ~30 分钟

目标：理解 KV 存储的工作机制，能够在 Worker 中实现基本的读写缓存。

📌 任务 2：模拟 KV 存储 — 实现一个计数器

Cloudflare KV 是一个全局分布式键值存储。我们用 JavaScript 对象模拟它的行为：

kv.get(key) — 读取值，如果不存在返回 null
kv.put(key, value) — 写入值（覆盖原有值）
kv.list() — 列出所有 key

编辑器

输出

点击 "运行代码" 测试你的 KV 实现...

💡 任务 A 提示

async function handleRequestKV(request) {
  const url = new URL(request.url);

  if (url.pathname === "/api/page-views") {
    let count = await kv.get("page_views");
    if (count === null) count = 0;
    count++;
    await kv.put("page_views", count);
    return new Response(
      JSON.stringify({ views: count }),
      { headers: { "Content-Type": "application/json" }}
    );
  }
  return new Response("Not found", { status: 404 });
}

📌 任务 3：构建 KV 计数器

完成后回答下面的问题来检验你的理解：

Q1. Cloudflare KV 的读写一致性模型是？

强一致性最终一致性读写分离

Q2. 为什么 KV 写操作不适合需要强一致性的场景？

我已理解 KV 存储的读写模型并完成了计数器任务

Level 3 — 独立实现 ~35 分钟

目标：从零构建一个带路由、CORS、中间件和 KV 缓存的完整 Worker。

📌 任务 4：构建完整的 API Gateway

在上一级的基础上，现在你要添加以下功能：

路由：/api/users 列表、/api/users/:id 单条、/api/health 健康检查
KV 缓存：GET /api/users 结果缓存 10 秒
CORS 中间件：所有端点自动添加 Access-Control-Allow-Origin: *
日志中间件：记录每个请求的方法、路径和响应状态

编辑器

// ─── API Gateway — 完整实现 ───

// 用户数据
const users = [
  { id: 1, name: "张三", role: "开发者", avatar: "https://i.pravatar.cc/40?u=1" },
  { id: 2, name: "李四", role: "设计师", avatar: "https://i.pravatar.cc/40?u=2" },
  { id: 3, name: "王五", role: "产品经理", avatar: "https://i.pravatar.cc/40?u=3" },
  { id: 4, name: "赵六", role: "运维工程师", avatar: "https://i.pravatar.cc/40?u=4" },
  { id: 5, name: "孙七", role: "测试工程师", avatar: "https://i.pravatar.cc/40?u=5" }
];

// ─── 1. KV 缓存 ───
const cache = {};

// TODO: 实现 getCache(key) — 检查缓存是否有效（10秒 TTL）
// TODO: 实现 setCache(key, data) — 写入缓存

// ─── 2. 日志中间件 ───
const logs = [];

// TODO: 实现 logRequest(method, path, status) — 记录请求日志

// ─── 3. CORS 中间件 ───
// TODO: 实现 withCORS(response) — 为 Response 添加 CORS 头
// 需要添加的响应头：
//   Access-Control-Allow-Origin: *
//   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
//   Access-Control-Allow-Headers: Content-Type

// ─── 4. 路由处理 ───
// TODO: 实现 handleRoute(request)
//   GET /api/health     → { status: "ok", timestamp: ... }
//   GET /api/users      → 返回用户列表（优先从缓存读，缓存 miss 才读 users 数组）
//   GET /api/users/1    → 返回 id=1 的用户（找不到返回 404）
//   GET /api/logs       → 返回所有请求日志
//   其他               → 404

// ─── 5. 主处理函数 ───
// TODO: 实现 handleRequest(request)
//   处理链：日志开始 → CORS OPTIONS 拦截 → 路由 → CORS 包装 → 日志结束 → 返回

输出

点击 "运行代码" 测试你的实现...

💡 需要提示？点击查看关键片段

CORS 中间件：

function withCORS(response) {
  const newHeaders = new Headers(response.headers);
  newHeaders.set("Access-Control-Allow-Origin", "*");
  newHeaders.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
  return new Response(response.body, {
    ...response,
    headers: newHeaders
  });
}

带缓存的 getUsers：

async function getUsers() {
  const cached = getCache("users_list");
  if (cached) return cached;

  const result = users.map(u => ({ id: u.id, name: u.name, role: u.role }));
  setCache("users_list", result);
  return result;
}

我的 API Gateway 实现了路由 + 缓存 + CORS + 日志四个功能

Level 4 — 进阶实践 ~30 分钟

目标：理解环境变量、Secrets 和 Wrangler 配置管理，能够安全地部署 Worker。

📌 任务 5：环境变量与 Secrets

实际项目中，API Key、数据库密码等敏感信息不能硬编码。Workers 提供两种配置机制：

机制	用途	安全性
vars	非敏感配置，如 API 地址、功能开关	明文可见于 dashboard
secrets	敏感信息，如数据库密码、第三方 API Key	加密存储，不可明文读取
bindings	KV / Durable Objects / R2 等服务绑定	由 Cloudflare 管理

wrangler.toml 配置示例

# wrangler.toml — Worker 项目配置文件
name = "my-api-gateway"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# ─── 环境变量（非敏感）───
[vars]
API_BASE_URL = "https://api.example.com"
FEATURE_FLAG_NEW_UI = "true"
ENV = "production"

# ─── KV 绑定 ───
[[kv_namespaces]]
binding = "CACHE"        # 代码中通过 env.CACHE 访问
id = "abc123..."         # Cloudflare dashboard 中创建
preview_id = "xyz789..."

# ─── Secrets（通过 wrangler 命令注入）───
# wrangler secret put API_KEY
# wrangler secret put DATABASE_URL

📌 任务 6：识别配置问题

下面的 Worker 代码存在多个安全问题，找出它们：

有问题的 Worker 代码

// ⚠️ 这段代码存在安全问题，你能找出几个？

const DB_PASSWORD = "my_super_secret_password_123";  // 问题 1

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

    if (url.pathname === "/api/users") {
      // 问题 2: 未验证请求来源
      const users = await fetch(
        `${env.API_BASE_URL}/users?key=${DB_PASSWORD}`
      );

      // 问题 3: 未设置 CORS 头
      return new Response(await users.text());
    }

    if (url.pathname === "/admin/delete-all") {
      // 问题 4: 无权限校验
      await env.DB.delete("users:*");
      return new Response("deleted");
    }

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

你的发现

列出你发现的问题：

💡 参考答案（4 个安全问题）

密码硬编码 — 使用 wrangler secret put DB_PASSWORD 注入
密码泄露在 URL 中 — URL 参数会被日志记录，应放在请求 body 或 header 中
缺少 CORS — 所有响应都应添加 Access-Control-Allow-Origin
无权限校验 — /admin/delete-all 没有任何认证，任何人都可以调用

我已理解环境变量 / Secrets / 安全编码的差异和用法

Level 5 — 实战部署 ~30 分钟+

目标：用 Wrangler CLI 从零创建、本地测试并部署一个真实 Worker。

🚀 任务 7：部署你的第一个 Worker

注册 Cloudflare 账号（免费）
安装 Wrangler：npm install -g wrangler
登录：wrangler login（会打开浏览器授权）
创建项目：wrangler init my-first-worker
本地预览：cd my-first-worker && wrangler dev
部署到云端：wrangler deploy
访问你的 Worker URL，确认它在全球边缘运行

🧠 思考题

Workers 的冷启动时间 <1ms，而 Lambda 通常需要数百毫秒。两者架构上的根本差异是什么？
Wrangler 的 wrangler dev 和 wrangler deploy 分别做了什么？
KV 是最终一致性——你在什么业务场景下可以接受这个限制？什么场景下不能？
如果要用 Workers 做一个 A/B 测试服务，你会怎么设计路由和变体分发？

我已用 Wrangler 成功部署了一个 Worker 到 Cloudflare

总结

⚡ Workers 运行时

V8 隔离 + 全球边缘节点，<1ms 冷启动，HTTP 请求通过 fetch 事件驱动处理

🗺️ 路由与中间件

通过路径匹配分发请求，CORS 和日志作为中间件横切所有端点

💾 KV 存储

分布式键值存储，适合缓存、会话、计数器等场景；注意最终一致性

🔐 安全配置

vars 放公开配置，secrets 放敏感信息，bindings 连接 Cloudflare 服务

🚀 Wrangler CLI

wrangler dev 本地开发，wrangler deploy 一键发布到全球边缘网络

🏗️ Serverless 思维

不管理服务器、按需付费、自动扩缩容。Workers 把开发者从运维中解放出来，专注业务逻辑

知识图谱 你要学什么

Workers 运行时

Fetch 事件

路由与中间件

KV 存储

环境变量

部署与 Wrangler

核心概念

Level 1 — 认识 ~25 分钟

📌 任务 1：模拟一个 Cloudflare Worker

编辑器 — 修改下面的代码

输出

Level 2 — 引导实践 ~30 分钟

📌 任务 2：模拟 KV 存储 — 实现一个计数器

编辑器

输出

📌 任务 3：构建 KV 计数器

Level 3 — 独立实现 ~35 分钟

📌 任务 4：构建完整的 API Gateway

编辑器

输出

Level 4 — 进阶实践 ~30 分钟

📌 任务 5：环境变量与 Secrets

wrangler.toml 配置示例

📌 任务 6：识别配置问题

有问题的 Worker 代码

你的发现

Level 5 — 实战部署 ~30 分钟+

🚀 任务 7：部署你的第一个 Worker

🧠 思考题

总结

⚡ Workers 运行时

🗺️ 路由与中间件

💾 KV 存储

🔐 安全配置

🚀 Wrangler CLI

🏗️ Serverless 思维

知识图谱你要学什么