4269 字
21 分钟
Cloudflare Workers 入门

前面几篇讲的都是「配置」:改 DNS、套规则、开缓存。这一篇开始写「代码」了。Cloudflare Workers 让你把一段 JavaScript 代码部署到 Cloudflare 遍布全球的边缘节点上,请求在到达你的源站之前,先经过你的代码处理一遍:可以改请求、改响应、直接返回内容、把流量转发到别处,甚至整个站都不需要源站。

本篇主线分三段:先讲清 Workers 是什么、和你熟悉的服务器有什么本质区别;再给两条上手路线(控制台在线编辑、Wrangler 命令行),任选一条把第一个 Worker 跑起来;最后给出三个拿来就能用的完整例子——加安全响应头、维护模式页、简单反代。读完你应该能自己判断:什么需求值得写个 Worker,什么需求用前面几篇的规则配置就够了。

Workers 是什么#

Workers 是 Cloudflare 的边缘计算平台。你写一个处理函数,部署上去,Cloudflare 把它分发到全球数百个城市的节点。访客的请求就近进入某个节点时,先执行你的函数,再决定是返回你生成的内容,还是继续去源站取数据。

它的运行时不是 Node.js,也不是一台虚拟机,而是 Chrome 同款的 V8 引擎里的 isolate(隔离实例)。这是理解 Workers 一切特性的钥匙:

  • 没有冷启动。传统 Serverless 函数冷启动要拉起一个容器或进程,慢则几百毫秒;isolate 的启动成本低到可以忽略,官方口径是接近零冷启动。
  • 没有完整的操作系统环境。没有文件系统、没有 fs、child_process 这类 Node.js API,能用的是 Web 标准 API:fetch、Request、Response、URL、Web Crypto 等。你在浏览器里写前端时用的那套 API,在这里基本都能用。
  • 按请求计费。不跑不花钱,免费版每天有一定请求额度,具体数字以官方定价页为准。

和你熟悉的几种东西横向对比一下定位:

方案运行位置启动速度环境完整度适合场景
自己买的 VPS固定机房常驻运行完整系统,随便装长期服务、数据库、复杂后端
云函数(如 Lambda)云厂商机房有冷启动较完整,可带依赖事件触发的后端任务
Cloudflare Workers全球边缘节点近乎无冷启动只有 Web 标准 API请求改写、边缘逻辑、轻量 API、反代

一句话定位:Workers 不是用来替代你的服务器的,而是给流量加一层可编程的「门卫」——请求进门之前先过一遍你的逻辑。重活、长连接、大计算该放源站的还是放源站;但凡逻辑只跟「这一次 HTTP 请求」有关,放到边缘又快又省。

WARNING

Workers 的代码运行在 Cloudflare 的节点上,请求和响应都会经过它。给支付、登录这类敏感接口写 Worker 之前,先想清楚日志里会不会打出请求头、Cookie、令牌这类东西——把敏感信息写进 console.log 是最常见的翻车方式,调试完记得清掉。

运行模型速通#

Workers 的心智模型非常简单,就一句话:一个请求进来,交给你的 fetch 处理函数,你要么自己造一个 Response 返回,要么用 fetch() 把请求转发出去、拿到响应加工后再返回。

现行推荐的是模块写法(Module Worker),骨架长这样:

export default {
async fetch(request, env, ctx) {
// request:进来的请求(URL、方法、头、体都在里面)
// env:绑定的变量、KV、密钥等都挂在这里
// ctx:用来登记「响应返回后继续在后台干」的任务
return new Response("Hello from Workers!");
},
};

几个必须先建立的概念:

  • 一切都是 Web 标准对象。request.url 是字符串,要解析就 new URL(request.url);请求头用 request.headers.get("User-Agent") 读;改响应头不能直接改原对象,要新建 Headers 再构造新的 Response(下面的例子会演示)。
  • 没有本地状态。每个请求可能落在不同节点、不同 isolate 里,别指望用一个全局变量当数据库。需要存数据,用后面提到的 KV、D1、R2。
  • CPU 时间有限。免费版单个请求的 CPU 时间很短(具体以官方定价页为准),它适合做判断、改写、转发,不适合在里面跑重型计算或长时间循环。
  • 老写法了解即可。你在旧教程里会看到 addEventListener("fetch", ...) 的 Service Worker 写法,那是早期语法,现在新项目一律用上面的模块写法,本篇所有例子都用模块写法。

路线 A:控制台快速上手#

第一次接触,先别装工具。控制台在线编辑是最快的验证路径,五分钟能看到效果。

操作顺序:

  1. 登录 Cloudflare 控制台,进入「Workers 和 Pages」→「创建」→「创建 Worker」,起个名字,比如 hello-edge,点部署。
  2. 部署完点「编辑代码」,把默认代码换成下面这段:
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
return new Response(`你正在访问:${url.pathname}\n`, {
headers: { "content-type": "text/plain; charset=utf-8" },
});
},
};
  1. 点右上角「部署」。回到 Worker 概览页,点开它给的 *.workers.dev 地址(形如 hello-edge.你的子域名.workers.dev),就能看到输出,且路径会跟着你访问的路径变。

到这一步,代码已经在全球边缘跑起来了。但要注意:workers.dev 地址只是给你预览和测试用的,真正给自己域名上的流量用,必须绑路由(Route),这一步在下面「路由与触发」里讲。很多新手卡在「Worker 部署成功了但网站上没反应」,原因就是没绑路由。

路线 B:Wrangler 命令行#

正经维护的 Worker 应该走 Wrangler:Cloudflare 官方的命令行工具,负责本地调试、部署、看日志、管绑定。代码进 Git、部署一条命令,比在网页编辑器里改生产代码靠谱得多。

安装与登录#

Wrangler 是个 npm 包,建议装在项目里而不是全局:

Terminal window
mkdir my-worker && cd my-worker
npm init -y
npm install -D wrangler

登录(会拉起浏览器走 OAuth 授权):

Terminal window
npx wrangler login

初始化项目#

Terminal window
npx wrangler init

它会问几个问题(项目名、是否用 TypeScript 等),然后生成骨架。生成的关键文件是 wrangler.toml,这是 Worker 的部署说明书,核心字段先认识这几个:

name = "hello-edge" # Worker 名称,部署后就是这个名字
main = "src/index.js" # 入口文件
compatibility_date = "2025-01-01" # 兼容性日期,决定运行时行为版本,新项目填近期日期即可
# 绑到自己域名时才写 routes,二选一即可
# routes = [
# { pattern = "example.com/api/*", zone_name = "example.com" },
# ]

compatibility_date 是个容易被忽略的坑:它锁定了运行时的行为版本,太旧的日期可能用不了新 API。新建项目时 Wrangler 会自动填当天的日期,照做就行。

本地调试与发布#

Terminal window
npx wrangler dev # 本地起一个模拟环境,改代码即时生效
npx wrangler deploy # 部署到 Cloudflare 边缘
npx wrangler tail # 实时看线上日志,排障必备

wrangler dev 会在本机模拟 Workers 运行时(底层是本地版的 workerd),绝大多数 API 行为和线上一致,先在本地把逻辑跑通再 deploy,这是标准姿势。

两条路线怎么选,看这张表:

对比项控制台在线编辑Wrangler
上手成本零安装,打开网页就能写要装 Node.js 和 npm 包
代码管理存在 Cloudflare 侧,无版本历史本地文件,可进 Git
本地调试无,只能部署后看wrangler dev 本地模拟
看线上日志控制台里有简单日志wrangler tail 实时流
适合临时验证、一次性小改动任何要长期维护的 Worker

例子一:给全站响应加安全头#

第一个实战例子:让 Worker 在每个响应返回给访客之前,统一加上几个安全相关的响应头(防点击劫持、防 MIME 嗅探等)。这种事在源站 Nginx 上也能做,但边缘统一加的好处是:不管源站换成什么,头都在。

export default {
async fetch(request, env, ctx) {
// 先正常去源站(或后续逻辑)拿到响应
const response = await fetch(request);
// 响应头是只读的,必须复制一份再改
const newHeaders = new Headers(response.headers);
newHeaders.set("X-Content-Type-Options", "nosniff");
newHeaders.set("X-Frame-Options", "SAMEORIGIN");
newHeaders.set("Referrer-Policy", "strict-origin-when-cross-origin");
// 用改好的头构造一个新响应返回
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers: newHeaders,
});
},
};

逐段看关键点:

  • await fetch(request):把原始请求原样转发给源站,拿到源站的响应。这一步叫「回源」。
  • new Headers(response.headers):response.headers 不能直接 set,这是新手最常撞的墙——必须先克隆。
  • 重新构造 Response 时把 body、status 一起带上,只换头。

把这个 Worker 的路由绑成 example.com/*(全站),所有经过 Cloudflare 的响应就都带上这三个头了。用 curl -I https://example.com 就能验证。

WARNING

全站绑 /* 意味着每个请求都要过 Worker。免费版每天的请求额度是有限的(以官方定价页为准),高流量站点全站套 Worker 可能把额度烧穿,超额后请求会直接报错。更稳妥的做法是只给需要的路径绑路由,比如只处理动态页面,静态资源走缓存不进 Worker。

例子二:维护模式页#

半夜要给服务器做维护,希望访客看到一个友好的维护页,而不是源站的连接错误。用 Worker 做这件事有个天然优势:源站哪怕关机了,维护页照样能打开,因为它根本不回源。

实现思路:用一个环境变量当开关。变量在控制台的 Worker 设置里加,或者写在 wrangler.toml 的 [vars] 里:

[vars]
MAINTENANCE = "off"

要维护时把值改成 "on" 重新部署(或直接在控制台改变量,立即生效)。代码:

const MAINTENANCE_HTML = `<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>维护中</title></head>
<body style="font-family: sans-serif; text-align: center; padding-top: 15vh;">
<h1>网站维护中</h1>
<p>我们正在进行计划内维护,请稍后再来。</p>
</body>
</html>`;
export default {
async fetch(request, env, ctx) {
if (env.MAINTENANCE === "on") {
return new Response(MAINTENANCE_HTML, {
status: 503,
headers: {
"content-type": "text/html; charset=utf-8",
"Retry-After": "3600",
},
});
}
// 开关关闭时,请求原样回源
return fetch(request);
},
};

两个细节值得注意:一是返回 503 而不是 200,这是给搜索引擎看的——503 表示「临时不可用,过会再来」,不会把你的页面从索引里误伤掉;二是带上 Retry-After 头,告诉爬虫和客户端多久之后再重试。如果只想维护期间放行自己的 IP 测试,可以再在判断里加一个 request.headers.get("CF-Connecting-IP") 的白名单判断,这里就不展开了。

例子三:简单反代#

第三个例子是 Workers 最常见的用法之一:把某个路径的流量转发到另一台服务器。比如主站是 example.com,但你想让 example.com/api/* 实际去请求另一台机器 api.internal.example.net,并且把路径前缀去掉。

export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
// 换源站域名,并去掉 /api 前缀
const target = new URL(url.pathname.replace(/^\/api/, "") + url.search, "https://api.internal.example.net");
// 基于原请求构造新请求,保留方法、头和请求体
const newRequest = new Request(target, {
method: request.method,
headers: request.headers,
body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
redirect: "manual",
});
return fetch(newRequest);
}
// 不匹配 /api/ 的请求,走默认回源
return fetch(request);
},
};

关键点逐个说:

  • 改 URL 要用 new URL() 重新组装,别用字符串硬拼,查询参数(url.search)很容易拼丢。
  • 转发请求体要小心:GET 和 HEAD 没有请求体,传 body 反而可能报错,所以上面做了方法判断。
  • redirect: "manual" 表示源站返回 3xx 时不要自动跟随,把重定向原样透传给访客,避免边缘替源站「做主」。
  • 转发时 Host 头会由 fetch 按目标 URL 自动设置,一般不用手动改;个别源站按 Host 校验的,再单独 headers.set("Host", ...) 处理。

绑路由时把这个 Worker 绑到 example.com/api/* 即可,/api/ 之外的流量根本不进 Worker,比在代码里判断更省额度。代码里的 startsWith 判断留着是双保险。

路由与触发:没绑路由等于没上线#

再强调一遍这个最高频的坑:Worker 部署成功只是把代码放上了边缘,必须再给它绑路由,告诉 Cloudflare「哪些请求要先过这个 Worker」,否则它永远不会被触发。

绑定的方式有两种:控制台里 Worker 页面的「设置 → 触发器 → 路由」里添加,或者写在 wrangler.toml 的 routes 里随部署一起生效。路由的写法是「域名 + 路径」的模式串:

路由写法匹配范围
example.com/*该域名下所有路径
example.com/api/*只有 /api/ 开头的路径
*.example.com/*所有子域名
example.com/static/*.css特定后缀,也支持这种细粒度写法

几个规则要记牢:

  • 更具体的路由优先。同时存在 example.com/* 和 example.com/api/* 两个 Worker 时,/api/ 的请求走后者。
  • 路由所在域名的 DNS 记录必须开启橙云代理(小云朵是橙色)。只有 DNS-only(灰云)的记录,流量根本不经过 Cloudflare,Worker 自然不会触发——这是「路由不生效」的第一嫌疑。
  • workers.dev 子域名是每个账号一个的预览域名,定位就是测试和个人小工具,正式业务请绑自己的域名路由。

存储:一句话各表一个#

Worker 本身是无状态的,需要存东西时 Cloudflare 给了三个选择,本篇只给定位,细节看对应文章:

  • KV:键值存储,全球只读分发、写入后最终一致,适合存配置、开关、映射表这类读多写少的数据。
  • D1:基于 SQLite 的关系型数据库,适合需要正经查表的小型业务数据。
  • R2:S3 兼容的对象存储,适合存文件、图片、备份,细节见本系列的 R2 对象存储实战 一篇。

另外还有环境变量与 Secrets:普通变量写 [vars],密码、令牌这类敏感值用 wrangler secret put 单独存,代码里统一从 env 上取,不要把令牌直接写死在代码里提交进 Git。

排障小节#

Worker 报 1101 错误(Worker threw exception)

访客看到 1101 就是你的代码抛了未捕获的异常。用 npx wrangler tail 实时盯日志,再复现一次请求,异常堆栈会直接打出来;控制台里 Worker 的「日志」页也能看历史报错。本地先用 wrangler dev 复现,能解决掉绝大多数低级错误(变量拼错、给只读头赋值之类)。

路由绑了但完全不生效

按顺序查三件事:一,目标域名的 DNS 记录是不是橙云代理(灰云直接排除);二,路由模式串写对没有,* 的位置和路径前缀最容易写错;三,这个路径是不是被另一条更具体的路由抢去了别的 Worker。三项都对还不行,把路由临时改成 域名/* 全量测试,能触发就说明是模式串的问题。

本地 wrangler dev 好好的,线上就报错

环境差异通常出在三处:一是绑定没配齐——本地 wrangler.toml 里注释掉的 KV、变量,线上忘了建或忘了绑,env.XXX 变成 undefined;二是 compatibility_date 本地和线上不一致,导致某个 API 行为不同;三是本地测试的请求太「干净」,线上真实请求带了本地没测过的头、体或方法。所以上线前至少拿真实域名在预发路径上完整跑一遍,而不是只信本地。

改完代码线上没变化

先确认你改的是不是部署的那个 Worker(多个环境、多个 Worker 很容易改错),再确认 wrangler deploy 真的执行成功而不是报错中断;控制台部署的则检查一下浏览器里编辑的是不是最新版本,顺手刷新一下页面排除缓存的假象。

小结#

  • Workers 是跑在 Cloudflare 全球边缘的 JavaScript,用 V8 isolate 实现近乎无冷启动,代价是只有 Web 标准 API、没有文件系统和本地状态。
  • 心智模型只有一条:请求进来过你的 fetch 函数,你返回自己造的 Response,或者 fetch() 回源加工后再返回。
  • 上手两条路:控制台适合快速验证,Wrangler 适合长期维护;新项目一律用模块写法。
  • 三个例子覆盖了最高频的场景:统一加安全头、源站下线也能展示的维护页、按路径转发到另一台源站的简单反代。
  • 部署不等于上线,绑路由才算数,且域名记录必须是橙云代理。
  • 需要存数据时按形态选 KV、D1、R2,敏感配置用 Secret 存,别写进代码。

下一篇我们回到存储主题,把 R2 对象存储从建桶到当图床、做备份完整走一遍。

Cloudflare Workers 入门
https://www.anexns.cloudns.org/posts/cloudflare-workers-intro/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0