前面几篇讲的都是「配置」:改 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 请求」有关,放到边缘又快又省。
WARNINGWorkers 的代码运行在 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:控制台快速上手
第一次接触,先别装工具。控制台在线编辑是最快的验证路径,五分钟能看到效果。
操作顺序:
- 登录 Cloudflare 控制台,进入「Workers 和 Pages」→「创建」→「创建 Worker」,起个名字,比如
hello-edge,点部署。 - 部署完点「编辑代码」,把默认代码换成下面这段:
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" }, }); },};- 点右上角「部署」。回到 Worker 概览页,点开它给的
*.workers.dev地址(形如hello-edge.你的子域名.workers.dev),就能看到输出,且路径会跟着你访问的路径变。
到这一步,代码已经在全球边缘跑起来了。但要注意:workers.dev 地址只是给你预览和测试用的,真正给自己域名上的流量用,必须绑路由(Route),这一步在下面「路由与触发」里讲。很多新手卡在「Worker 部署成功了但网站上没反应」,原因就是没绑路由。
路线 B:Wrangler 命令行
正经维护的 Worker 应该走 Wrangler:Cloudflare 官方的命令行工具,负责本地调试、部署、看日志、管绑定。代码进 Git、部署一条命令,比在网页编辑器里改生产代码靠谱得多。
安装与登录
Wrangler 是个 npm 包,建议装在项目里而不是全局:
mkdir my-worker && cd my-workernpm init -ynpm install -D wrangler登录(会拉起浏览器走 OAuth 授权):
npx wrangler login初始化项目
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 会自动填当天的日期,照做就行。
本地调试与发布
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 对象存储从建桶到当图床、做备份完整走一遍。