中文
所有文章
AIClaude

Cloudflare 新命令行 cf 实测教程：安装、本地开发和迁移，以及怎么让 Claude Code 部署 Workers（2026）

Cloudflare 新命令行 cf 覆盖整个 Cloudflare API。本文基于 beta.26 实测安装、--help 里的智能体提示、cf cli search、cf init、cf dev、cf build 和 cf migrate，并根据官方文档说明如何让 Claude Code 部署 Worker。

约 10 分钟阅读
Cloudflare Workers 部署教程（cf 命令行）：一把浅蓝色钥匙和一个多抽屉小柜
其他语言EspañolEnglish

版本说明：本文基于 cf 1.0.0-beta.26 实测，测试日期 2026-10-31。cf 目前还是 beta，命令和输出以后可能会变。

Cloudflare 在 2026-09-28 发布了新命令行工具 cf，目前是公开 beta。这篇 Cloudflare Workers 部署教程用的就是这个新 CLI：我在自己的机器上跑了安装、--help 里写给 AI 智能体的提示、命令搜索、cf init、cf dev、cf build，还拿一个旧的 Wrangler 项目试了 cf migrate。后面也讲怎么配置，让 Claude Code（或 Codex）用 cf 部署 Worker。

需要先说明：cf auth login 和 cf deploy 我没有运行，因为这两步需要 Cloudflare 账号。文中登录和部署的部分全部来自官方文档，到那一节我会再标一次。

cf 是什么，和 Wrangler 是什么关系

cf 是覆盖整个 Cloudflare API 的命令行工具，不只管 Workers。官方 changelog 写的是超过 2,900 个命令，发布博客写的是覆盖 3,000 多个 API 操作；作为对比，博客说 Wrangler 大约覆盖 280 个。命令是根据 Cloudflare 的 API 定义生成的，所以 DNS、R2、D1、Access、AI Gateway 这些产品的命令和 Workers 命令放在同一个工具里。

博客也解释了做这个工具的原因：截至 2026 年 9 月下旬，智能体已经占到 Wrangler 使用量的 48%（3 月时还是四分之一）。所以 cf 的设计重点是让智能体自己找到正确的命令。每个命令的 JSON 结果输出到 stdout，提示信息输出到 stderr。

Wrangler 暂时不会消失。博客的说法是：公开 beta 结束时，Cloudflare 会发布 Wrangler 的最后一个大版本，引导你和你的智能体改用 cf；beta 结束后 Wrangler 还会继续获得 18 个月的维护支持。文档也说明，不迁移项目也能开始用 cf，比如 cf d1 list 这类账号级命令在任何目录都能运行。

官方对比页列出的主要区别：

  • 配置文件从 wrangler.toml / wrangler.jsonc 换成 cloudflare.config.ts，用 defineConfig、bindings.* 和 triggers.* 来写。
  • Wrangler 的 --env 改成了 --mode。
  • cf 用资源 ID，不用资源名称。
  • cf 默认操作远程数据，--local 只支持 KV、D1 和 R2。
  • cf dev、cf build、cf deploy 会交给框架自己的命令、Cloudflare Vite 插件，或 Wrangler 4.136.0 及以上版本去执行。新项目默认用 Vite。

安装前的环境要求

文档要求 Node.js 22.18 或更高版本。我注意到一个细节：beta.26 的 npm 包里 engines 字段写得更严格，是 ^22.23.0 || ^24.22.0 || ^26.12.0，所以用较新的 Node 22、24 或 26 更稳妥。Bun 不能作为运行时：文档说在 Bun 上运行 cf 时，需要加载 cloudflare.config.ts 的命令会失败。

官方文档没有列出支持哪些操作系统，所以这里不下结论。我也没找到 CLI 本身的单独定价。我推测 CLI 本身不收费，费用只来自你用到的 Cloudflare 产品。

第 1 步：安装 cf 并查看版本

npm install --global cf
cf --version

npm 输出了 added 32 packages in 3s，另外有一条警告，说 workerd 的 postinstall 脚本不在 allowScripts 的允许范围内。这条警告没有影响后面的测试。版本号是 1.0.0-beta.26。这个包会装两个命令：cf 和 cloudflare，指向同一个工具。需要 Tab 补全的话，cf complete 支持 zsh、bash、fish 和 PowerShell。

第 2 步：cf –help 开头写给智能体的提示

cf --help 最先输出的是一段写给 AI 智能体的说明：不要一层层地调用 --help 去翻命令，先用搜索；搜索内容要匿名，不要带名称、域名、ID 或 token。

Cloudflare Workers 部署教程：cf --version 与 cf --help 开头写给智能体的提示（beta.26）

我推测这样做是为了避免智能体对几百个子命令挨个运行 --help，把上下文占满。CLI 直接告诉智能体该怎么查命令。

cf cli search 接收一句自然语言描述，返回 5 个匹配命令的 JSON，不需要任何凭据。

cf cli search "create a DNS record" 返回 5 个 DNS 命令的 JSON

另外两个查询命令也不需要账号。cf schema 可以查看命令背后的 API 请求细节（把搜索结果开头的 cf 换成 cf schema 即可）。cf docs search "deploy a worker" 返回了 5 条排好序的 JSON 结果，包含标题、描述和链接，其中一条是 developers.cloudflare.com/cf/projects/ 的 “Develop, build, and deploy” 页面。帮助文本说，智能体可以带上 Accept: text/markdown 请求结果链接，读取完整页面。

我还试了一个缺少参数的真实命令 cf dns records list。它以退出码 1 结束，报错是 No zone specified，并列出三种指定 zone 的方法：位置参数、--zone，或者环境变量 CLOUDFLARE_ZONE_ID。这样的报错，智能体很容易照着改。

第 4 步：用 cf init 创建 Worker

cd ~
cf init ./hello --package-manager npm

这一步生成了 .gitignore、cloudflare.config.ts、package.json、src/index.ts、tsconfig.json 和 vite.config.ts，安装了依赖，并在 .cloudflare/types/index.d.ts 生成了类型文件。生成的配置如下：

import { bindings, defineConfig } from "cf/config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({
	worker: {
		name: "hello",
		compatibilityDate: "2026-10-23",
		entrypoint,
		env: {
			WORLD: bindings.text("World"),
		},
	},
});

Worker 代码通过 import { env } from "cloudflare:workers" 读取这个绑定，返回 Hello ${env.WORLD}!。package.json 里的脚本分别是 cf dev、cf build、cf deploy，typecheck 是 cf workers types && tsc。

第 5 步：cf dev 本地运行，cf build 构建

cf init、cf dev 在 localhost:5173 返回 Hello World，以及 cf build 输出

cf dev 交给 npx vite 执行，Worker 运行在 http://localhost:5173/。用 curl -i 请求，返回 HTTP/1.1 200 OK、content-type: text/plain;charset=UTF-8 和 Hello World!。

cf build 交给 npx vite build 执行，产物在 .cloudflare/output/v0/workers/default/bundle/，bundle 只有 0.24 kB。

坑 1：cf dev –port 在 Vite 项目里不能用

我一开始运行的是 cf dev --port 8799，结果报错：

Arguments cannot currently be forwarded to the detected dev command `npx
vite`. Run that command directly with the required arguments.

在 beta.26 里，参数不会转发给 Vite。直接运行不带参数的 cf dev；如果一定要换端口，就自己运行 npx vite --port 8799。

第 6 步：登录并部署到 Cloudflare Workers（来自官方文档，未实测）

这一步需要 Cloudflare 账号，所以我没有运行。下面是文档给出的首次正式部署前的检查顺序，也是这篇 Cloudflare Workers 部署教程里唯一没有实测的部分：

cf build
cf deploy --dry-run
cf auth login
cf deploy

根据 CI 文档，cf deploy --dry-run 会构建并校验项目，但不上传、也不发送 API 请求，所以不需要凭据。cf auth login 会输出一个链接和一次性验证码，并打开浏览器让你批准授权。在远程服务器、SSH 或容器里，加上 --no-browser，然后用另一台设备的浏览器批准。要重新登录就加 --force，用 cf auth whoami 查看当前登录状态。注意，cf 不会沿用 Wrangler 的登录。

让 Claude Code 用 cf 部署 Worker

文档有一页专门写给智能体的设置，分三步：全局安装 cf，登录，然后在用户级的 AGENTS.md 或 CLAUDE.md 里加一句：

When interacting with Cloudflare, use the `cf` CLI unless the project has a
Wrangler configuration file.

这句话的意思是：有 Wrangler 配置文件的项目继续用 Wrangler，其他 Cloudflare 操作都用 cf。Claude Code 读 CLAUDE.md，Codex 读 AGENTS.md，所以同一句话两边都能用。两个工具都在用的话，可以看看我写的 Codex CLI 和 Codex App 区别。

文档说浏览器登录要你自己完成，智能体没法替你批准。之后给 Claude Code 这样一句提示就够了：

Create a Worker in ~/hello with cf init, run cf build and
cf deploy --dry-run, show me the output, and ask me before running cf deploy.

我推测大多数人都会希望正式部署前先确认一下。比起只靠提示词，用 Claude Code 的权限规则来强制确认更可靠，具体可以看 Claude Code /permissions 怎么用。

无人值守的智能体和 CI：用 API token

没人在旁边的智能体无法完成 cf auth login。文档的做法是设置环境变量 CLOUDFLARE_API_TOKEN，在 CI 里再加上 CLOUDFLARE_ACCOUNT_ID。token 只给任务需要的权限，含有 token 的 .env 文件不要提交到仓库。cf 读取凭据的优先顺序是：

  • CLOUDFLARE_API_TOKEN（包括从 .env 读到的值）
  • --profile 参数
  • 用 cf auth activate 绑定到项目的 profile
  • 默认 profile

不支持 Global API Key。

用 CLI 还是用 MCP？

cf 的思路是让智能体通过搜索找到命令，这和用 MCP 接入工具是两种不同的方式。如果你在两者之间犹豫，可以看 Claude Code Skills 和 MCP 区别，以及 Claude Code MCP 推荐。

第 7 步：用 cf migrate 迁移 Wrangler 项目

为了测试迁移，我建了一个小的 Git 仓库，里面的 wrangler.toml 有一个变量、一个 KV 命名空间、一个每小时触发的 cron，以及一个 staging 环境：

name = "legacy-worker"
main = "src/index.js"
compatibility_date = "2025-06-01"
[vars]
GREETING = "hi"
[[kv_namespaces]]
binding = "CACHE"
id = "00000000000000000000000000000000"
[triggers]
crons = ["0 * * * *"]
[env.staging.vars]
GREETING = "staging"

cf migrate 要求 Git 工作区是干净的（可以用 --force 跳过）。建议先跑 --dry-run。预览显示它会修改 cloudflare.config.ts、package.json 和 package-lock.json；因为项目没有声明 Vite 插件，所以继续用 Wrangler 的打包器（可以用 --bundler vite 改掉）；另外，Wrangler 的环境会被改写成 switch (ctx.mode) 语句。

cf migrate --dry-run 和 --no-install 在示例 wrangler.toml 上的输出

生成的 cloudflare.config.ts 用的是 defineConfig((ctx) => { switch (ctx.mode) { ... } })。staging 分支里的 Worker 名称是 legacy-worker-staging。KV 绑定 CACHE 只出现在默认分支里，这和 Wrangler 里 KV 绑定不会被环境继承的规则一致。原来的 wrangler.toml 保留不动。

坑 2：cf migrate –no-install 生成的配置会直接抛错

加上 --no-install 后，命令以退出码 1 结束，提示 Migration requires follow-up work。它写出了 cloudflare.config.ts，但 package.json 没有变化。配置文件里有一条 TODO，还有一行会抛出错误：Migration incomplete. Resolve every cf migrate TODO in cloudflare.config.ts. 运行任何命令之前，先在项目里安装 cf@latest，再删掉 TODO。如果没有特别原因，就让 cf migrate 自己安装依赖。

文档还提醒：不要在尚未迁移的 Wrangler 项目里运行 cf dev、cf build 或 cf deploy。Durable Object 迁移、Workflows、Containers 和 package 脚本在迁移后可能需要手动处理。

目前还要用 Wrangler 的操作

cf 还在 beta，并没有覆盖所有功能。文档列出了两处缺口：

  • 实时日志：cf 暂时不能实时查看日志，用 npx wrangler tail 。
  • 单个 secret：cf 暂时不能单独设置一个 secret，用 npx wrangler secret put --name ，或者给 cf deploy / cf workers versions create 传 --secrets-file 。

Wrangler 不读 cloudflare.config.ts。迁移后如果还要运行 Wrangler 命令，先把 Wrangler 配置文件留着。

关闭遥测

cf 会发送匿名使用统计。要关闭的话，在环境变量里设置 CF_SEND_TELEMETRY=false 或 DO_NOT_TRACK=1。

常见问题

用 cf 部署 Cloudflare Workers 要钱吗？

cf 从 npm 免费安装，我没找到 CLI 的单独定价。我推测费用只来自你用到的 Cloudflare 产品，这一点和 Wrangler 一样。

现在必须从 Wrangler 换到 cf 吗？

不用。Wrangler 还能正常用，beta 结束后还有 18 个月的维护期。不迁移项目，也可以先用 cf 跑账号和资源相关的命令。

cf 支持 Windows、macOS 和 Linux 吗？

官方文档没有列出支持的操作系统。我只在 Linux 上测试过。

需要哪个版本的 Node.js？

文档写的是 Node.js 22.18 或更高。beta.26 的 npm 包声明的是 ^22.23.0 || ^24.22.0 || ^26.12.0。

Claude Code 能替我运行 cf auth login 吗？

不能，浏览器里的授权需要你本人批准。无人值守的场景请用上面说的 API token。

旧的 Cloudflare Workers 部署教程还能用吗？

基于 Wrangler 的教程目前仍然有效。区别在于新项目用 cloudflare.config.ts 和 cf deploy，老项目可以先不动。

参考来源

留下你的想法

你的邮箱不会公开。