Cloudflare Workers 边缘计算实战指南 封面配图

Cloudflare Workers 边缘计算实战指南

作者

Cloudflare Workers 边缘计算配置指南

如果你需要在请求到达源站前完成 A/B 路由、Header 改写、地区跳转或轻量 API，Cloudflare Workers 边缘计算是性价比最高的方案之一。它把 JavaScript 或 TypeScript 函数部署到全球 300 多个边缘节点，冷启动通常低于 5 毫秒，免费方案每天提供 10 万次请求。本文将教你如何从零搭建一个 Workers 项目，覆盖路由改写、KV 存储、定时任务与 R2 回源四个常见场景，并解决”本地能跑、上线就 503″这类高频问题。

一、Cloudflare Workers 的能力边界

Workers 运行在 V8 隔离环境（Isolates）中而非容器中，启动快、内存上限严格。免费方案的关键限制：CPU 时间最多 10 毫秒、内存 128 MB、请求体上限 100 MB。Paid 方案放宽 CPU 至 50 毫秒并可配置 Unbound 模式上限 30 秒。判断你的逻辑是否适合放到 Workers，可参考三点：延迟敏感（鉴权、签名校验、地区跳转）、逻辑轻量（单次请求 CPU 在毫秒级、不依赖大型库）、状态可外置（KV、Durable Objects 或外部数据库）。

如果你的源站在海外、面向中国大陆用户，Workers 适合做静态资源签名与缓存控制，但回源仍依赖主机线路。源站选型可参考 WordPress 香港主机选购指南 与 云服务器选购指南，跨境链路（Cross-Border，跨越国界的网络通信）的优化逻辑同样适用于 Workers 回源。

二、本地开发与首次部署

Cloudflare 提供 wrangler CLI 完成项目脚手架、调试与部署。npm install -g wrangler@latest 装好后，依次执行 wrangler login、wrangler init my-edge-worker 即可初始化项目，会生成 wrangler.toml 与 src/index.ts。wrangler.toml 是部署清单，关键字段包括 name、main、compatibility_date、workers_dev、以及 KV/R2 等绑定列表。compatibility_date 决定运行时行为，建议每 3 个月更新一次。本地调试用 wrangler dev，端口默认 8787，但要注意：本地默认 --remote=false，连接 KV 时不会读真实生产数据；如需读真实 KV，加 --remote 参数。wrangler deploy 完成首次部署后会返回 workers.dev 子域名，绑定到自定义域名要进入控制台 Workers Routes 添加路由并选择对应的 Zone。

三、路由改写与 Header 注入

最常见的场景是把请求按地区或路径分流到不同源站。示例：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const country = request.headers.get("cf-ipcountry") || "XX";
    const url = new URL(request.url);

    if (country === "CN" && url.pathname.startsWith("/api/")) {
      url.hostname = "origin-cn.example.com";
    } else {
      url.hostname = "origin-global.example.com";
    }

    const upstream = await fetch(url.toString(), {
      method: request.method,
      headers: request.headers,
      body: request.body,
    });

    const response = new Response(upstream.body, upstream);
    response.headers.set("x-edge-region", country);
    return response;
  },
};

这段代码完成了三件事：基于 cf-ipcountry 头进行地区判断、替换上游主机名、注入自定义响应头。cf-ipcountry 是 Cloudflare 自动注入的两字母 ISO 代码，免费方案可用。需要注意的是：当 Workers 与 Pages 同域部署时，Workers 路由优先级高于 Pages 函数，调试时务必看清当前请求被哪一层接管。

四、KV 存储与定时任务

Workers KV 是边缘键值存储，读延迟约 50 毫秒、写一致性为最终一致（约 60 秒同步到所有节点）。适合做配置开关、地区映射、限流计数等读多写少的场景，不适合做实时计数器（强一致用 Durable Objects）。

读写示例：用 await env.MY_KV.get("config:routing", "json") 读取，未命中则 await env.MY_KV.put(..., { expirationTtl: 600 }) 写入。定时任务通过 Cron Triggers 配置：在 wrangler.toml 加 [triggers]\ncrons = ["*/5 * * * *"]，并在 src/index.ts 暴露 scheduled 入口，用 ctx.waitUntil(refreshConfig(env)) 确保异步任务完成才结束 Worker 调用，否则任务可能被中断。常见用途包括预热 KV 缓存、定期清理过期键、向监控平台推送指标。

五、回源缓存控制与 R2 集成

对静态资源加速场景，可让 Workers 在 R2 命中后直接返回，未命中再回源并写缓存。R2 是 Cloudflare 的 S3 兼容对象存储，免费方案提供 10 GB 存储和 100 万次 A 类操作每月，且没有出站流量费用，对边缘下发图片、字体、视频片段尤其合算。

务必把回源响应头中的缓存策略单独控制，不要透传源站的短 TTL 导致频繁回源。一个常见的反例是源站使用 WordPress 默认设置返回 no-cache，Workers 直接照搬这个头，结果每次请求都会重新到 R2 读一次再到源站验证一次，反而比直接回源更慢。正确做法是 Worker 自己根据资源类型重写响应头，让浏览器至少缓存几分钟到几小时，再让 Workers 自己决定何时回源拉新版本。

如果源站本身已在加速链路上，可参考 WordPress W3 Total Cache 调优实战 中关于浏览器缓存与边缘缓存协作的部分，把本地插件设置与 Worker 的覆盖策略对齐，避免出现一边缓存一边主动失效的内耗状况；更多 WordPress 边缘加速思路可在 WordPress 分类 下查看相关文章。

实际部署 R2 之前，建议先评估真实流量分布：哪些路径占了 80% 流量、哪些资源体积大但访问稀疏、哪些资源更新频繁。一般来说，把图片、字体、长尾文章封面这类访问稳定、变更稀少的对象放进 R2 收益最大；登录页、个人中心这类高度个性化的页面则不适合走 R2 缓存层。

六、调试与排障清单

排查 Workers 异常时按下面顺序检查会更快：

  • 用 wrangler tail 在线查看实时日志，配合 console.log 输出关键路径；免费方案 tail 会话最多 100 条/秒。
  • CPU 时间超限会返回 1102 错误码，先检查是否在循环中做了同步序列化大对象。
  • KV 写失败常见原因是单 key 大小超过 25 MB 或 value 过大，超出后改用 R2。
  • 如果出现 503 但 wrangler tail 无任何日志，可能是 Routes 未生效，控制台确认 Route 顺序与 Zone 绑定。
  • 跨境回源失败时，结合 cf-ray 头与 美国 VPS 部署教程 中的 MTR 命令逐跳定位。

总结与建议

Cloudflare Workers 把 Serverless（无服务器架构，按调用计费的函数执行模型）的边缘能力开放到全球节点，对中小站点而言可以在不增加运维成本的前提下显著降低跨境时延。建议先从 Header 注入与路由分流这两个低风险场景上手，再根据流量规模决定是否引入 KV、R2 与 Durable Objects。如果你需要把 Workers 与已有主机或 WordPress 站点组合，可以考虑先用 Workers 接管鉴权与缓存控制层，源站继续承担业务逻辑，迁移过程更平滑。整体而言，把 Workers 作为现有架构的旁路加速层而不是新的核心服务，更容易在短期内拿到稳定收益，也方便在出现问题时直接关停回退而不影响主业务运行。

发表评论