用途
Cloudflare Workers 用于在 Cloudflare 全球边缘网络部署 JavaScript 和 TypeScript 函数。根据资料,其适用场景包括:构建边缘侧的轻量级 API 和微服务;在源站服务器前添加中间件(认证、限流、请求头注入);按计划运行 cron 定时任务而无需维护基础设施;处理 webhook、图像变换或 A/B 测试逻辑;从 KV、D1 或 R2 存储绑定提供动态内容。
前置条件
本地需安装 Node.js 18 及以上版本;安装 Wrangler CLI:npm install -g wrangler;拥有 Cloudflare 账号(免费计划支持每天 100,000 次请求);完成认证:wrangler login 或设置 CLOUDFLARE_API_TOKEN。
快速开始
脚手架创建新的 Worker 项目
npm create cloudflare@latest my-worker cd my-worker
登录 Cloudflare
npx wrangler login
启动本地开发服务器(端口 8787)
npx wrangler dev
部署到生产
npx wrangler deploy
常用 Wrangler 命令
资料列出的命令包括:使用远程绑定进行本地开发(npx wrangler dev --remote);部署到指定环境(npx wrangler deploy --env staging);设置密钥(npx wrangler secret put API_TOKEN,可加 --env staging);列出密钥(npx wrangler secret list);实时跟踪生产日志(npx wrangler tail,可加 --status=error --search="timeout" 过滤);查看部署版本(npx wrangler deployments list);回滚到之前的部署(npx wrangler rollback)。
Wrangler 配置
wrangler.toml 中可配置 name、main、compatibility_date、compatibility_flags(如 nodejs_compat)、routes(自定义路由)、workers_dev 子域、[vars] 非密钥环境变量,以及 [env.staging] 等环境覆盖配置。资料给出了完整示例,包括 staging 环境的名称、路由和变量覆盖。
主要能力示例
资料提供了多类代码示例:基础 API 路由(使用 fetch 处理不同 pathname,包括健康检查、POST 接收数据并用 ctx.waitUntil 异步记录分析);使用 KV 实现限流中间件(基于 CF-Connecting-IP 和 KV 计数,超过阈值返回 429);KV 存储绑定操作(put 带过期时间、get 读取 JSON、按前缀 list、delete);D1 数据库绑定(参数化查询、插入、batch 批量语句);Cron 触发器(在 [triggers] 中配置 crons,使用 scheduled 处理器按 event.cron 分支执行任务);Durable Objects(定义 Counter 类,通过 idFromName 获取并路由请求)。同时还包含 KV、D1 的 CLI 操作命令,以及自定义路由的配置方式(支持自定义域名并自动启用 SSL)。
适用场景与限制
资料中的问题排查表说明了若干限制:Worker 未处理的异常会导致 Error 1101,需用 try/catch 并借助 wrangler tail 查看堆栈;CPU 时间限制为免费版 10ms、付费版 30s,超出会报错;KV 为最终一致性(约 60 秒),可能读取到旧数据,需使用 cacheTtl 或改用 Durable Objects 以获得强一致性;本地绑定错误需使用 --remote 或配置 preview_id;密钥环境不匹配会找不到密钥;浏览器 CORS 错误需添加 CORS 响应头并处理 OPTIONS 预检;路由不匹配通常是因为 pattern 缺少 /* 后缀。
相关资料中提及的关联技能包括 cloudflare-pages(前端部署)、cloudflare-r2(对象存储)、cloudflare-zero-trust(用 Access 保护 Worker 端点)。关于价格、收费、性能效果等具体数据,除上述免费计划请求量和 CPU 时间限制外,资料暂未提供更多信息。