快速入门

每个 cf 工作流都以相同方式开始：安装 CLI、登录，然后运行命令。本页末尾的参考部分说明 cf 如何选择凭据、账户和 zone。

• 一个 Cloudflare 账户。如果还没有，请注册 ↗。
• Node.js 22.18 或更高版本。不支持 Bun。当 cf 在 Bun 上运行时，加载 cloudflare.config.ts 的命令会失败。

全局安装 cf，使该命令在每个目录中都可用：

npm i cf

yarn add cf

pnpm add cf

bun add cf

该软件包安装两个运行同一 CLI 的命令：cf 和 cloudflare。如果 PATH 上已有名为 cf 的其他工具，请使用 cloudflare。

确认安装：

cf --version

以后要更新 cf，请安装最新发行版：

npm i cf@latest

yarn add cf@latest

pnpm add cf@latest

bun add cf@latest

项目也可以将 cf 添加为开发依赖。在该项目内，全局 cf 命令会运行项目中安装的版本，因此协作者、编码 Agent 和持续集成（CI）使用同一发行版。通过 cf init 创建的项目已经包含它。

在远程机器、SSH 或容器中，请添加 --no-browser。cf 会打印链接而不打开它，你可以在另一台设备的浏览器中批准请求。要再次登录，请添加 --force。

cf 保存自己的凭据，不会复用 Wrangler 登录。即使你已经在使用 Wrangler，也只需登录一次。

列出你可以访问的 zone：

cf zones list

结果在标准输出上为 JSON。进度和状态消息写入标准错误，因此你可以无需额外标志即可重定向或管道传输结果：

cf zones list > zones.json

要查找任务对应的命令，请向 cf cli search 描述该任务：

cf cli search "create a DNS record"

cf cli search 以 JSON 打印最多五个匹配命令。它在本地运行，不需要凭据。要改为浏览，请向 cf、某个产品（例如 cf dns）或任意命令添加 --help。

有关查找、创建和删除资源的演练，请参阅从命令行管理资源。

将补全添加到 shell 配置文件，然后重启 shell：

cf complete zsh >> ~/.zshrc

cf complete 还支持 bash、fish 和 powershell。运行 cf complete --help 查看 bash 和 fish 的等效命令。

cf 使用它找到的第一个凭据：

1. CLOUDFLARE_API_TOKEN 环境变量，包括从 .env 文件 加载的值。
2. 用 --profile <NAME> 选择的 profile。
3. 通过 cf auth activate 绑定到当前目录或其最近父目录的 profile。
4. 默认 profile，即 cf auth login 登录到的 profile。

cf 不支持 Global API Key。

当命令需要账户时，cf 按此顺序选择：

1. CLOUDFLARE_ACCOUNT_ID 环境变量。
2. cloudflare.config.ts 默认导出中的 accountId 字段。
3. cf 在先前命令中为此项目保存的账户。
4. 你的凭据可以访问的唯一账户。如果有多个，cf 会请你选择一个。

当 cf 选择你的唯一账户，或你选择了一个账户时，它会保存该账户，并在同一项目的后续命令中使用，而不再询问。它将账户存储在最近的 node_modules 目录内的 .cache/cloudflare/ 中，文件名为 cloudflare-account.json，命名 profile 则为 cloudflare-account-<PROFILE>.json。当没有 node_modules 目录，或当前目录中已存在 .cloudflare/cache/ 且 node_modules 缓存不存在时，它改为使用 .cloudflare/cache/。

要重新选择，请删除该文件。从项目目录运行 cf auth login --force 或 cf auth logout 也会清除它，但在设置了 CLOUDFLARE_API_TOKEN 时不会。

在脚本或 CI 作业等非交互会话中，如果凭据可以访问多个账户，且未设置或保存账户，命令会失败。

要为项目设置默认账户，请参阅设置账户默认值。

zone 范围的命令接受 --zone 或 -z。值可以是 zone ID 或域名：

cf dns records list --zone example.com

对于域名，cf 会在所选账户中查找匹配的 zone。--zone 选项优先于 CLOUDFLARE_ZONE_ID 环境变量。

profile 保存独立凭据，例如用于工作账户和个人账户。创建 profile：

cf auth create work

cf auth create 会创建 profile 并为其开始登录。要在项目中使用该 profile，请将其绑定到项目目录：

cf auth activate work

cf auth activate 将 profile 绑定到当前目录及其子目录。要绑定其他目录，请在 profile 名称之后传入该目录。要移除绑定，请运行 cf auth deactivate。要为单条命令使用某个 profile，请传入 --profile <NAME>。要查看你的 profile，请运行 cf auth list。

当设置了 CLOUDFLARE_API_TOKEN 时，cf auth create、cf auth activate、cf auth deactivate 和 cf auth delete 不会运行，因为令牌优先于每个 profile。

在 CI 和其他非交互环境中，请设置 API 令牌，而不是运行 cf auth login：

export CLOUDFLARE_API_TOKEN=<API_TOKEN>
export CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID>

只授予作业所需的令牌权限。要创建一个，请参阅创建 API 令牌。完整流水线设置请参阅在 CI 中使用 cf。

API 命令会从当前目录的 .env 文件读取这些变量：

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_ZONE_ID
• CLOUDFLARE_COMPLIANCE_REGION
• CLOUDFLARE_ACCESS_CLIENT_ID
• CLOUDFLARE_ACCESS_CLIENT_SECRET

例如：

CLOUDFLARE_API_TOKEN=<API_TOKEN>
CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID>

cf 只读取 .env。它不会读取 .env.local 或特定模式的文件（例如 .env.<MODE>）。已在环境中设置的变量会覆盖文件中的值。

带 --local 运行的命令不会读取该文件。cf deploy、cf previews deploy、cf workers versions create 和 cf workers triggers deploy 仅在构建完成后读取它。

• 要查看 CLI 设置，请参阅环境变量。
• 如果刚接触 Workers，请部署你的第一个 Worker。
• 如果管理 zone 和 DNS，请从命令行管理资源。
• 如果目前使用 Wrangler，请阅读 Wrangler 用户使用 cf。
• 如果与编码 Agent 一起工作，请为 Agent 设置 cf。
• 如果从流水线部署，请在 CI 中使用 cf。