Cloudflare Worker 实战：用 cf CLI 管理与部署

真正省下的并不是几次键盘输入，而是集成工作。创始人无需在控制台里反复查找就能检查账户；平台团队可以向智能体提供机器可读的结果；服务商也能统一不同客户账户的 Cloudflare 操作，不必为每项产品分别维护一套 API 封装。

使用 cf 不需要另购许可证。代码仓库已经开源，小型 Worker 可以从 Cloudflare Free 套餐起步，而 Workers Paid 的月度最低费用为 $5。如果预算走到另一端，Spacelift 这类通用基础设施治理平台的 Starter+ 方案标价为 $20,000。cf 能省去两者之间大量 API 对接工作，但审批、审计记录和谨慎的权限配置依然不可少。

Cloudflare Worker 工作流里的 cf CLI 到底是什么

cf 一方面为整套 Cloudflare API 生成统一的命令入口，另一方面也为创建、构建、迁移和部署 Worker 等任务提供人工设计的项目工作流。可以把 Wrangler 看作一张面向 Worker、工具齐全的专业工作台；cf 则像整栋 Cloudflare 大楼的目录和服务台。遇到更适合 Wrangler 的 Worker 任务时，它仍会把工作交回 Wrangler。

这也说明本次发布与 Cloudflare 4 月 13 日的技术预览有何不同。4 月的版本只覆盖少量产品；9 月的公开测试版才带来完整 API 覆盖、默认 JSON 结果、命令搜索、TypeScript Worker 配置，以及作为默认 Worker 路径的 Vite。

真正改变工作方式的是下面 4 点：

• 完整 API 覆盖： 生成式命令遵循 cf <product> [group…] <operation> 结构，可调用 3,000 多项操作。
• 命令搜索： 给 cf cli search 一句自然语言任务描述，它会返回按相关度排序的 5 个 JSON 结果，无需背下整棵命令树。
• 默认输出 JSON： API 结果会以格式化 JSON 写入标准输出，同一份响应可以直接交给人、脚本或编码智能体筛选。
• 类型化 Worker 配置： cloudflare.config.ts 能为编辑器和编码智能体提供 TypeScript 反馈。目前它从 Workers 起步；未来可能扩展为 DNS、域名区域和策略等整个账户的配置入口，但这还不是现有功能。

安装并认证 cf CLI，然后验证一次只读操作

先从只读操作开始。这样可以一次确认软件包、凭据、账户选择、命令发现和 JSON 处理链路均可用，再考虑让脚本执行任何修改。

官方软件包要求 Node.js 22 或更高版本。人在终端操作时，cf auth login 会管理默认 OAuth 配置；在 CI 中，则应设置权限范围尽可能小的 CLOUDFLARE_API_TOKEN，cf 会优先检查这个环境变量，再读取已保存的 OAuth 配置。若需要处理多个客户或公司账户，还可以创建命名配置，并将其绑定到不同目录。

传给 cf cli search 的文字要保持通用。只描述动作和资源类型，不要带上域名、邮箱地址、账户 ID 或令牌。

node --version
npm i -g cf
cf --version

cf auth login
cf auth whoami

cf cli search "list zones in an account"
cf zones list | jq -e 'type == "array" and all(.[]; has("name") and has("status"))'

目前，这项任务的搜索结果会把 cf zones list 排在首位。最后一行才是真正的验证：它发起一次只读 API 调用，并且仅当返回值是 JSON 数组、其中每项都包含 name 和 status 时才会成功退出。如果有多个账户，可通过 --profile 选择命名配置，或用 --account-id 限定命令。

不要把令牌直接粘贴进 shell 历史记录。应把限定权限的令牌放进 CI 进程环境，而且只授予任务所需的读写权限。对于个人终端会话，OAuth 通常更省心，因为 cf 可以刷新当前选中的配置。

一次性测试实际验证了什么

9 月 29 日，在全新的隔离环境中安装后得到 cf v1.0.0-beta.5。命令搜索返回了有效的 5 项 JSON 数组，cf init 创建了带类型配置的 Worker 项目，新项目和迁移后的 Vite 测试项目也都在本地成功构建。测试环境没有 Cloudflare 测试账户凭据，因此已认证的域名区域读取和部署都没有被列为已完成测试。

这条边界很重要：本地构建成功只能证明项目路径可行，不能证明令牌具备正确的生产权限，也不能证明部署已经到达 Cloudflare。

创建一个小型 Cloudflare Worker，再检查 cf 生成了什么

cf init 是验证新项目工作流最直接的方式。在空目录中运行后，它会生成 TypeScript 源码、cloudflare.config.ts、vite.config.ts、软件包脚本和 Worker 类型；随后，cf build 会把构建交给 Cloudflare Vite Plugin，并产出标准化的 Build Output。

cf init hello-cf --package-manager npm
cd hello-cf
npm run build

# In a copied existing Vite Worker:
cf migrate --dry-run
cf migrate
npm run build

无论走哪条路径，完成后都要打开 cloudflare.config.ts 检查。基础 Worker 通常会有一个 worker 配置块，包含名称、兼容日期、入口文件和带类型的绑定。文本绑定通过配置 API 声明，无需再复制到多个环境块中。TypeScript 的价值就在这里：字段拼错可以先在编辑器里暴露，而不是等到部署失败才发现。

生成的 Vite 配置并非装饰。Vite 现在是 cf 默认的本地开发与构建路径，Cloudflare 也建议前端和后端 API 都使用其 Vite 插件。一次性项目中的 npm run build 已交由 Vite 并顺利完成，但部署被有意跳过。完成代码审查和账户测试后，文档中的 cf deploy 命令会默认执行构建并上传。

Wrangler 仍应保留在哪些环节

不要因为 cf 安装成功就删除 Wrangler。迁移方式要由项目当前的构建路径决定。

对于现有 Vite Worker，cf migrate 可以把 Wrangler 的 JSON、JSONC 或 TOML 转换成 cloudflare.config.ts。该命令会检查 Wrangler 配置旁是否声明了 Cloudflare Vite 插件；若有，就采用 Vite 路径。若未声明，当前公开测试版会改用 Wrangler 打包器。先运行迁移预览，逐项阅读后续提示，并在副本或干净分支中完成迁移，再动正在工作的项目。

如果 JavaScript Worker 仍依赖 Wrangler 的 esbuild 行为，cf 会继续把开发和部署交给 Wrangler；Rust 和 Python Worker 也是如此。这是兼容机制，并不意味着迁移失败。团队仍可把 cf 作为统一入口，同时保留已经验证可靠的构建器。

Cloudflare 的支持时间也很容易被误读。Wrangler 计划在公开测试结束后继续维护 18 个月，而不是从 9 月 28 日发布当天起计算 18 个月。因此，没有理由本周就强行把 Rust、Python 或 esbuild 项目改成 Vite。

最先值得落地的 7 个 cf 工作流

最适合率先采用的场景都有一个共同点：先替代重复的查找和格式整理工作，而不是第一天就开放大范围写权限。

1. 服务商统一账户检查方式

服务商可以把命名 OAuth 配置绑定到每个客户目录，搜索所需的只读命令，再把一致的 JSON 结构送入审查脚本。这样就不会出现一名工程师在控制台逐页点击、另一名工程师维护自定义 curl 命令所造成的偏差。对 DNS、域名区域、账户设置和安全审查等跨客户工作来说，最大的收益是可重复执行。

2. 平台团队为编码智能体提供安全的 Cloudflare 接口

平台负责人可以围绕 cf cli search 制定一条 AGENTS.md 规则：默认允许只读命令，任何修改都需要人工批准。搜索功能能避免智能体猜测旧版 Wrangler 语法，JSON 则让结果保持紧凑、方便筛选。当团队已经让智能体检查构建状态、日志、队列或账户资源，并希望统一为一个可预测的入口时，这套方式尤其有用。

3. 值班工程师快速收集事故上下文

事故发生时，值班人员可以直接搜索正确的日志、域名区域、规则集或分析读取命令，无需在多个产品面板间来回切换。具体命令和权限依旧重要，但发现过程已经转到本地，响应也能直接交给 jq。对于运行 Cloudflare Browser Run 等任务的团队，这能缩短从失败任务定位到账户上下文的路径。

4. 创始人无需先设计工具链就能启动一个 Worker

要构建 webhook、重定向服务或小型内部 API，创始人可以运行 cf init，检查生成的 Worker 和绑定，再直接使用 Vite 构建，不必逐个挑选软件包。项目可以从 Workers Free 开始；若需要付费套餐，当前每个账户每月最低为 $5。这里的价值是更快得到可供审查的本地产物，而不是承诺生产运维从此免费。

5. Vite 团队无需重写应用即可转换配置

使用 Vite Worker 的工程团队可以先在副本上运行 cf migrate --dry-run，检查生成的 TypeScript，再完成构建，最后才调整部署。这在环境配置块日益重复时尤其有用。新格式可以基于共享基础动态计算配置，但团队要迁移的是行为，而不只是文件语法。

6. 数据或运营团队把 Cloudflare 读取结果接入报表

结构化结果默认就是 JSON，因此运营人员可以把一次读取直接送入 jq、数据仓库加载器或定时报表，无需抓取 Unicode 表格。它带来的商业价值朴素却实在：更少的输出适配器，也更少脆弱的解析规则。务必使用权限受限的只读令牌，并避免把命令输出暴露在公开 CI 日志中。

7. Worker 团队先检查本地资源，再接触生产环境

受支持的命令可以使用 --local，与一个由本地状态支撑的短生命周期 Miniflare 实例交互，其中包括 KV、D1 和 R2 已定义的操作。若没有对应的本地能力，cf 会报错，而不是悄悄转向生产环境。开发 Cloudflare AI Search Worker 的团队可以利用这条边界测试配套的本地数据，避免让开发命令意外变成远程写入。

围绕 cf 值得做的 2 类产品

真正的产品机会并不在 CLI 本身，而在团队面对如此广泛的 API 覆盖时仍然需要的控制层。

首选机会：面向服务商的 Cloudflare 变更控制

可以为管理多个 Cloudflare 账户的服务商或小型平台团队打造一层轻量的审批与证据系统。用户提出 DNS、域名区域、WAF 或 Worker 变更后，产品通过 cf 收集当前 JSON 状态，展示便于阅读的差异，发起审批，再使用限定权限的配置执行操作并保存结果。

需求信号不算庞大，但具备商业价值：cloudflare dns management 在美国每月约有 170 次搜索，CPC 为 $6，页首出价区间为 $3.85 至 $36.64。通用基础设施治理同样对应真实预算：Spacelift 的 Starter+ 标价为 $20,000。Cloudflare 专用产品无需治理所有云平台，因此可以更便宜，也更容易落地。

最小可售版本可以是一款 GitHub App 或托管审查队列，先支持 DNS 和 Worker 变更，并提供配置隔离、命令白名单、变更前后 JSON，以及底层 API 支持时的一键回滚。难点在于壁垒：cf 已经解决命令覆盖，真正需要沉淀的是策略、证据、权限和服务商工作流。只有图形界面的薄封装很快就会被复制。

实用功能：Worker 迁移就绪度检查

可以构建一个扫描器，将代码仓库判定为原生 Vite、由 Wrangler 支撑的 esbuild、Python 或 Rust 类型，随后运行安全的迁移预览，并把后续事项整理成拉取请求检查清单。目标买家是管理一批 Worker 的团队，而不是只迁移一个小项目的独立开发者。

需求量不足以单独支撑一家公司。cloudflare worker deployment 在美国每月约有 10 次搜索，尽管这个查询带有交易意图。更合理的 MVP 是把它做成 Cloudflare 运维产品或迁移服务中的付费功能：扫描仓库、运行 cf migrate --dry-run、验证构建，并给出清晰的 Wrangler 回退报告。问题在于公开测试期间版本变化很快；扫描器必须紧跟 cf 和 Cloudflare Vite Plugin 的版本，否则建议会比被检查的项目更早过时。

限制条件与务实结论

现在可以把 cf 用于命令发现、JSON 优先的账户读取、新建 Vite Worker，以及谨慎的迁移试验。凡是 cf 仍会委托给 Wrangler 的场景，就继续保留 Wrangler；所有生产写入则应置于明确的权限范围和审查流程之后。

当前公开测试版还没有让 cloudflare.config.ts 成为整个账户的唯一事实来源，它首先覆盖的是 Workers。完整 API 覆盖也不等于每一项 Cloudflare API 操作都自动变成安全的业务流程。令牌能够触达的范围越广，最小权限和命令审查就越重要。

本地模式同样有明确边界。受支持的 KV、D1、R2、Durable Object 和 Workflow 操作可以使用本地状态；没有本地资源浏览器对应能力的操作则会报错。这是一项合理的安全设计，但也意味着 --local 并非 Cloudflare 的通用离线镜像。

最后，公开测试版本变化很快。团队项目应在依赖中固定 cf 版本，审查生成的配置，并让 CI 使用项目内的本地版本。全局安装适合发现命令；固定版本才能确保协作者得到一致的行为。

如果希望为团队设计并落地一条安全的 Cloudflare 自动化路径，可以了解 AI 生产系统。