SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cloudflare-workers

cloudflare-workers

部署与运维

查看项目

更新于 10-27 02:34

技能介绍

用途

该技能用于构建和部署 Cloudflare Workers 边缘函数，核心工具为 Wrangler CLI。适用于在边缘提供轻量 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。

资料特别提示：应核实实际账户的 Node/Wrangler 支持情况、计划配额与 CPU 限制，文中历史数字不构成当前权益保证；部署、回滚或远程开发前需明确目标账户、环境与路由。

使用方式

快速开始：

npm create cloudflare@latest my-worker
cd my-worker
npx wrangler login
npx wrangler dev
npx wrangler deploy

常用 Wrangler 命令包括：wrangler dev --remote（在 Cloudflare 执行并可能影响绑定的远程资源）、按环境部署 wrangler deploy --env staging、设置密钥 wrangler secret put、列出密钥 wrangler secret list、实时查看日志 wrangler tail（可加 --status=error --search="timeout" 过滤）、查看部署版本 wrangler deployments list、回滚 wrangler rollback。

配置示例（wrangler.toml）包含 name、main、compatibility_date、compatibility_flags、routes、[vars] 及 [env.staging] 覆盖配置，也可启用 workers_dev 子域名。

主要能力

  • 基础 API 路由：基于 URL pathname 分发请求，支持 JSON 响应，并用 ctx.waitUntil 在响应返回后执行后台日志上报。
  • KV 计数器示例：以 CF-Connecting-IP 为键、60 秒窗口、最大 100 次请求的近似限流，超出返回 429 与 Retry-After。资料强调这是近似方案，非强制级限流器，安全场景应使用权威限流器。
  • KV 存储绑定：通过 wrangler.toml 的 kv_namespaces 绑定，支持带 TTL 写入、读取 json、按前缀 list、删除；并提供 kv namespace create/list 与 kv key put/get/list 等 CLI 操作。
  • D1 数据库绑定：通过 d1_databases 绑定，支持参数化查询、插入、批量执行；并提供 d1 create/list/execute 等 CLI 操作。
  • Cron 触发：在 [triggers] 中声明 crons，在 scheduled 处理器中按 event.cron 分支，用 ctx.waitUntil 执行清理或周报生成。注意资料指出第三个 cron 没有对应处理器。
  • Durable Objects：定义 Counter 类，通过 storage 读写计数，在入口用 idFromName 路由到对象；需在配置的入口点重新导出该类并使用兼容的 migration 类型。
  • 自定义路由：按 zones 配置 pattern，要求包含 /* 后缀以匹配全部路径；也可用自定义域名（自动 SSL）。

适用场景与限制

适用于边缘 API、微服务、中间件、定时任务与轻量数据处理。主要限制与风险：

  • KV 读-改-写非原子且最终一致，并发自增会丢更新，重复 put 会触及写入限制，TTL 重置使其成为滑动近似。提高 cacheTtl 不会让 KV 变为强一致。
  • waitUntil 是有界的后台工作，不是持久化任务队列，也不能绕过 CPU 限制。
  • 仅绑定已批准来源，代理前剥离意外凭证，分析数据外发前校验输入。
  • 内联 KV/D1 示例会在每次请求时变更数据，须隔离或鉴权。
  • 定时辅助函数与分析端点属于占位实现；第三个 cron 无处理器。
  • 基础设施命令可能中断服务，变更状态前需确认目标主机与范围，并准备备份或快照。
  • 该技能仅文档导入，上游脚本与模板未随附。

故障排查

资料列出常见问题：Error 1101（fetch 处理器未捕获异常，用 try/catch 并查看 tail 堆栈）；超出 CPU 时间（免费 10ms、付费 30s，需优化或 offload）；KV 读到陈旧数据（最终一致约 60s，可切换 Durable Objects 获取强一致）；wrangler dev 绑定错误（用 --remote 或配置 preview_id）；密钥未找到（检查环境是否匹配）；CORS 错误（添加 Access-Control-Allow-Origin 并处理 OPTIONS 预检）；路由不匹配（补 /* 后缀）。