Cloudflare 全新 cf CLI 实用指南

cf 是 Cloudflare 推出的命令行工具，覆盖整个 Cloudflare API。它于 2026 年 9 月 28 日开启公测，需在 Node.js 22.18 或更高版本上通过 npm i -g cf 安装。

如果你用 Wrangler 部署 Workers，那么在处理 DNS、Zone 以及各类设置时，你可能仍然需要打开控制台，因为这些功能 Wrangler 从未覆盖。cf 则两者兼顾：账户资源和 Worker 项目，只需一个二进制文件即可管理。本指南将带你完成安装、解读输出、编写新的 TypeScript 配置、部署，以及迁移现有 Worker。如果你需要先复习一下 Workers 的基础知识，可以从这篇 Cloudflare Workers 入门指南开始。

cf 与 Wrangler 有何不同？

Wrangler 是一条命令一条命令逐步扩充起来的 CLI，而取代它的 cf 则基于 Cloudflare 的 OpenAPI schema 自动生成。根据发布公告，cf 支持超过 3,000 个 API 操作，而 Wrangler 仅约 280 个。cf 文档的统计口径有所不同：超过 2,900 条命令。Cloudflare 在设计 cf 时充分考虑了编程智能体（coding agent）的使用场景，但每条命令由你手动输入时的行为完全相同。

更新日志条目提醒，在正式版发布之前，命令、配置和 Build Output 仍可能发生变化。

如何安装 cf 并登录？

从 npm 安装 cf 包，然后使用 cf auth login 进行身份验证。由于其他工具也可能安装名为 cf 的命令，请确认你安装的是官方包，它链接到 cloudflare/cf 仓库。

npm i -g cf
cf --version

cf auth login     # add --no-browser over SSH or in a container
cf auth whoami

根据入门文档，该包以 cf 和 cloudflare 两个名称提供同一个 CLI。如果 PATH 中已有其他程序占用了 cf 这个名称，可以改用 cloudflare 调用。登录时，cf 会显示一个链接和一次性验证码，然后在浏览器中打开该链接供你授权。cf 会单独存储自己的凭据，因此 Wrangler 的登录状态不会沿用过来。

在 CI 环境中，请改为设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID。通过这种方式设置的 token 优先级高于任何已保存的登录。

先从一个只读命令开始：

cf zones list

如何读取和过滤 cf 的 JSON 输出？

大多数 cf 命令会将结果以 JSON 格式写入 stdout，而进度和状态信息则写入 stderr。因此，无需任何额外参数，即可将结果保存到文件或通过管道传给 jq。

cf zones list > zones.json        # results only; status stays on stderr
cf zones list | jq .              # inspect the shape
cf zones list | jq '.[].id'       # print each zone's id
cf zones list --name example.com  # look up one domain

如资源管理文档所示，cf zones list 返回一个 JSON 数组，其中每个 zone 都包含一个 id 字段。在 zone 内执行操作的命令接受 --zone 或其简写 -z 参数，值可以是 zone ID，也可以是域名：

cf dns records list --zone example.com
cf dns records list -z example.com

使用 cf cli search 查找命令

要查找命令，可以运行 cf cli search 并用自然语言描述你要完成的任务，然后查看推荐命令的帮助信息。根据智能体相关文档，cf cli search 最多返回五个匹配项，以 JSON 数组形式按匹配度从高到低排列。搜索在本地完成，因此无需登录。

cf cli search "create a DNS record"
cf dns --help
cf complete zsh >> ~/.zshrc   # shell completion

--help 在命令树的每一层级都可用。

如何使用 cloudflare.config.ts 配置 Workers？

cloudflare.config.ts 是 cf 用于 Workers 的 TypeScript 配置文件。它从 cf/config 导入 defineConfig，以默认导出的方式导出结果，并通过类型化的辅助函数声明 binding 和 trigger，编辑器可以对其进行自动补全。编程式配置参考文档指出，该文件就是一个普通的 TypeScript 模块，因此可以在其中使用 import、函数、环境变量和异步值。

发布公告中的第一个示例使用 with { type: "cf-worker" } 导入属性导入 Worker 模块，然后设置 name、entrypoint 和 compatibilityDate。在下面的代码片段中，// ... 代表这些字段。以下是发布公告中 bindings 示例的精简版本，它向 defineConfig 传入一个函数，使配置值可以根据 mode 变化：

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    // ...
    env: {
      API_TOKEN: bindings.secret(),
      DATABASE: bindings.d1({ name: `example-${mode}-database` }),
      UPLOADS: bindings.r2({ name: `example-${mode}-uploads` }),
      JOBS: bindings.queue<{ userId: string }>({
        name: `example-${mode}-jobs`,
      }),
      AI: bindings.ai(),
    },
  },
}));

完整示例还用到了 bindings.text、bindings.kv、bindings.vectorize 和 bindings.worker。trigger 统一放在一个数组中。下面这段代码向 defineConfig 传入一个普通对象：

import { defineConfig, triggers } from "cf/config";

export default defineConfig({
  worker: {
    // ...
    triggers: [
      triggers.fetch({ pattern: "example.com/*" }),
      triggers.scheduled({ schedule: "0 * * * *" }),
      triggers.queue({ name: "jobs", maxBatchSize: 10 }),
    ],
  },
});

发布公告中的版本还增加了一个 triggers.email 条目。参考文档中还列出了用于原始套接字的 triggers.connect。在发布公告中，Cloudflare 表示计划让该文件也能配置 zone 和 DNS。目前，默认导出涵盖 Worker、Container 应用以及账户设置。

初始化、部署与迁移

使用 cf init 创建新项目，使用 cf deploy 进行部署，使用 cf migrate 迁移现有的 Wrangler 项目。

cf init my-worker      # or `cf init .` inside an existing app
cf deploy

cf init 会创建 cloudflare.config.ts 和 vite.config.ts；在现有的 Vite 应用中，它还会安装 @cloudflare/vite-plugin。如果不带参数运行，它会暂停并询问目标目录。根据部署文档，一次 cf deploy 调用即可完成项目的构建和检查，确定要使用的凭据和账户，然后上传新的 Worker Version 并使其生效。静态站点在首次执行 cf deploy 之前无需任何配置文件。

如果你的项目包含 wrangler.toml、wrangler.json 或 wrangler.jsonc，请在运行 cf dev、cf build 或 cf deploy 之前先完成迁移。这三条命令只读取 cloudflare.config.ts，会忽略任何 Wrangler 配置文件。

cf migrate --dry-run
cf migrate

cf migrate 可以直接读取 TOML，因此无需事先转换旧文件。如果你只是想以 JSON 形式查看旧的 wrangler.toml，可以使用 TOML 转 JSON 工具。《面向 Wrangler 用户的 cf 指南》说明，除非项目已经在使用 Cloudflare Vite 插件，否则迁移后会继续使用 Wrangler 的打包工具，因此切换到 Vite 是可选的。在保留 Wrangler 打包工具的情况下，迁移会生成一个 wrangler.config.ts，而根据迁移文档，Worker 所在的包需要安装 Wrangler 4.136.0 或更高版本。发布公告还补充道，Rust 和 Python Workers 也将继续交由 Wrangler 处理。

Wrangler 的未来如何？

Wrangler 目前仍可正常使用，但其终止时间已经确定。cf 公测结束后，Cloudflare 计划发布最后一个 Wrangler 大版本，引导用户转向 cf，并从那时起继续维护 Wrangler 18 个月。由于 Cloudflare 尚未公布公测结束时间，这 18 个月的具体起止日期目前还无法确定。

Vite 成为默认构建工具，也与 Workers 生态整体向 Vite 靠拢的趋势相吻合。

总结

你可以将 cf 与 Wrangler 并行安装：cf 的资源管理命令在未迁移的项目中也能运行，只有当你要把 Worker 的构建切换到 cf 时，迁移才变得必要。安装官方包后，运行 cf zones list | jq . 亲自看看输出效果；然后，赶在公测结束、Wrangler 进入维护期之前，在一个非关键 Worker 的分支上测试 cf migrate --dry-run。

常见问题

如何在多个 Cloudflare 账户之间使用 cf？

使用命名配置文件（profile）。运行 cf auth create work 创建一个 profile 并登录，然后运行 cf auth activate work 将其关联到当前文件夹及其所有子文件夹。传入 --profile work 可在单条命令中使用指定 profile，运行 cf auth list 可查看所有 profile。CLOUDFLARE_API_TOKEN 环境变量的优先级高于所有 profile，且设置该变量后，profile 管理命令将无法使用。

cf 能从 .env 文件读取凭据吗？

可以。API 命令可以从运行目录下的 .env 文件中读取 CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_ZONE_ID。cf 只读取 .env，不读取 .env.local，因此请确保 .env 已加入 .gitignore。以这种方式加载的 token 优先级高于任何 profile 或已保存的登录。cf 不支持 Global API Key，请改用限定权限范围的 API token。

如何在 monorepo 中迁移 Wrangler 项目？

将配置文件路径传给 cf migrate，例如 cf migrate packages/api/wrangler.jsonc --dry-run，然后去掉 --dry-run 再运行一次相同的命令。如果不指定路径，cf migrate 要求当前目录中有且仅有一个 wrangler.json、wrangler.jsonc 或 wrangler.toml 文件。它会将生成的文件写在配置文件旁边，并根据 package.json 选择打包工具（除非你传入 --bundler vite 或 --bundler wrangler）；如果 Git 工作区不干净，则需要加上 --force。

如果在迁移前就在 Wrangler 项目中运行 cf deploy，会发生什么？

cf 会忽略 wrangler.jsonc 和 wrangler.toml，因此可能会自行初始化项目，并修改 package.json 等文件。要恢复原状，请运行 git status，使用 git restore 还原每个被修改的文件，并删除新生成的文件，例如 cloudflare.config.ts、wrangler.config.ts 以及 .cloudflare 目录。然后再运行 cf migrate——注意，只要存在 cloudflare.config.ts，cf migrate 就不会执行。