Cloudflare Workers 边缘函数

FreeGuideOnline 最新 2026-07-14

bash npm install -g wrangler


验证安装：
```bash
wrangler --version

3. 登录认证

运行以下命令，按提示在浏览器中完成授权：

wrangler login

登录成功后，Wrangler 会保存 API 令牌，允许后续部署操作。

创建第一个 Worker

初始化项目

在终端中执行：

wrangler init my-first-worker

选择默认模板（Hello World Worker），随后进入项目目录：

cd my-first-worker

项目结构如下：

my-first-worker/
├── src/
│   └── index.js       # Worker 入口文件
├── wrangler.toml      # 配置文件
└── package.json

理解入口代码

打开 src/index.js，你会看到：

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  },
};

fetch 是 Worker 接到 HTTP 请求时调用的处理函数。
request 为标准的 Fetch API Request 对象。
env 包含环境变量和绑定（如 KV 命名空间）。
ctx 提供上下文方法，例如 waitUntil 用于后台任务。

本地开发与测试

启动本地开发服务器，实时预览修改：

wrangler dev

终端会输出本地 URL（通常是 http://localhost:8787）。打开浏览器访问该地址，即可看到 “Hello World!”。

部署到 Cloudflare

确认代码无误后，部署至边缘网络：

wrangler deploy

部署完成后，终端会返回一个以 *.workers.dev 结尾的公开 URL，全球即可访问。

核心概念深入

请求处理与响应

Workers 基于 Service Worker 标准，使用标准的 Fetch API。你可以直接返回 JSON、HTML 或重定向。

示例：返回 JSON 数据

export default {
  async fetch(request) {
    const data = {
      message: "Hello from edge",
      timestamp: Date.now(),
    };
    return new Response(JSON.stringify(data), {
      headers: { "Content-Type": "application/json" },
    });
  },
};

使用路由参数

通过 URLPattern 或手动解析 URL 实现路由：

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/api/user") {
      return new Response(JSON.stringify({ name: "Alice" }));
    }
    return new Response("Not Found", { status: 404 });
  },
};

环境变量与绑定

在 wrangler.toml 中设置环境变量：

[vars]
MY_API_KEY = "your-secret-key"

在代码中通过 env 对象访问：

const apiKey = env.MY_API_KEY;

注意：敏感信息应使用 Secrets 管理，通过 wrangler secret put 设置，避免写入配置文件中。

使用 KV 存储

Cloudflare Workers KV 是全局一致的低延迟键值存储，适合存储配置、会话数据等。

创建 KV 命名空间：

wrangler kv:namespace create "MY_KV"

将返回的 id 写入 wrangler.toml：

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

在代码中操作：

// 写入
await env.MY_KV.put("user:1001", JSON.stringify({ name: "Bob" }));
// 读取
const user = await env.MY_KV.get("user:1001", "json");

Durable Objects（持久化对象）

Durable Objects 提供强一致性的有状态计算，每个对象拥有独立存储和协调机制，适合实时协作、聊天等场景。本教程暂不深入，但可作为进阶学习方向。

构建实用案例

案例一：URL 重定向服务

export default {
  async fetch(request) {
    const url = new URL(request.url);
    const path = url.pathname.slice(1); // 去掉前导斜杠
    const redirectMap = {
      "home": "https://example.com",
      "blog": "https://blog.example.com",
    };
    if (redirectMap[path]) {
      return Response.redirect(redirectMap[path], 301);
    }
    return new Response("Short link not found", { status: 404 });
  },
};

部署后，访问 https://your-worker.workers.dev/home 将跳转至目标地址。

案例二：A/B 测试网关

通过cookie或随机数分流请求到不同版本的后端。

export default {
  async fetch(request) {
    // 50% 概率选择实验组
    const group = Math.random() < 0.5 ? "experiment" : "control";
    let res;
    if (group === "experiment") {
      res = await fetch("https://backend-v2.example.com");
    } else {
      res = await fetch("https://backend-v1.example.com");
    }
    const response = new Response(res.body, res);
    response.headers.set("X-AB-Group", group);
    return response;
  },
};

案例三：简单的 API 缓存层

利用 Cache API 在边缘缓存第三方 API 响应，降低源站压力。

export default {
  async fetch(request) {
    const cacheKey = new Request(request.url, request);
    const cache = caches.default;
    let response = await cache.match(cacheKey);
    if (!response) {
      response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
      response = new Response(response.body, response);
      response.headers.set("Cache-Control", "s-maxage=60");
      ctx.waitUntil(cache.put(cacheKey, response.clone()));
    }
    return response;
  },
};

调试与日志

本地调试

使用 wrangler dev 会输出请求信息和 console.log 内容，方便快速排错。

生产环境日志

通过 wrangler tail 实时查看线上 Worker 的日志：

wrangler tail