在 CI 中使用 cf

在持续集成（CI）中运行 cf，以检查每个拉取请求，并在无人值守的情况下部署 Worker。在 CI 中，cf 使用 API 令牌进行身份验证，并且不会等待输入。

从 GitHub Actions 部署

此工作流会为每个拉取请求以及对 main 的每次推送构建一次项目。它用 dry run 检查构建，并且仅在推送到 main 时部署同一构建。

将 cf 添加为开发依赖，使每次运行使用同一发行版：
npm i -D cf
yarn add -D cf
pnpm add -D cf
bun add -d cf
通过 cf init 创建或通过 cf migrate 迁移的项目已经包含它。
提交 cloudflare.config.ts。如果项目还没有该文件，请参阅提交项目配置。
将 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 添加为仓库 secrets。只授予工作流所需的令牌权限。要创建令牌，请参阅创建 API 令牌。

添加工作流文件：

.github/workflows/deploy.ymlyaml

name: Deploy

on:
  pull_request:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      CF_SEND_TELEMETRY: "false"
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx cf build
      - run: npx cf deploy --prebuilt --mode production --dry-run
      - if: github.event_name == 'push'
        run: npx cf deploy --prebuilt --mode production
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

该工作流假定项目由 cf init 创建，并且已提交 package-lock.json。只有最后的部署步骤接收 secrets，因此拉取请求步骤也适用于来自 fork 的拉取请求。如果向 cf build 传入了其他 --mode，请在两个部署步骤中使用相同模式。以下各节说明每个部分。

提供凭据

cf auth login 需要有人在浏览器中批准访问。在 CI 中，请改为设置这些环境变量：

变量	用途
`CLOUDFLARE_API_TOKEN`	对 API 请求进行身份验证。优先于任何已存储的登录。
`CLOUDFLARE_ACCOUNT_ID`	选择账户。未设置时，`cf` 使用 `cloudflare.config.ts` 中的 `accountId`，然后使用同一检出中先前运行保存的账户，再然后使用唯一可访问的账户。
`CLOUDFLARE_ZONE_ID`	在未传入 `--zone` 时，为 zone 级命令选择 zone。

如果令牌可以访问多个账户，且未设置或保存账户，命令会失败而不是提示：

More than one account available but unable to select one in non-interactive mode.
Please set the appropriate `account_id` in your cf config file or assign it to the `CLOUDFLARE_ACCOUNT_ID` environment variable.
Available accounts are (`<name>`: `<account_id>`):
  `(redacted)`: `<ACCOUNT_ID>`

在 CI 中，cf 会将账户名称替换为 (redacted)。要修复此错误，请设置 CLOUDFLARE_ACCOUNT_ID，或在 cloudflare.config.ts 的默认导出中添加 accountId。

为本地自动化使用 `.env` 文件

对于本机上的脚本，调用 Cloudflare API 的 cf 命令也可以从当前目录的 .env 文件读取这些变量。它们不会读取 .env.local。已在环境中设置的变量优先。详情请参阅从 .env 文件加载凭据。

固定 `cf` 版本

将 cf 安装为开发依赖后，npx cf <COMMAND> 会运行项目内的副本。在开发者机器上，全局安装的 cf 也会把每条命令交给项目内的副本。这样协作者、编码 Agent 和 CI 就会运行同一版本。一次性运行（例如 npx cf@<VERSION>）不会被转交。

使用 Node.js 22.18 或更高版本。详情请参阅要求。

了解非交互行为

当 cf 没有终端，或检测到 CI 环境（例如通过 CI 环境变量）时，会将运行视为非交互。在非交互运行中：

提示使用默认答案。没有默认值的提示会失败，因此请改为将值作为选项传入。
破坏性命令 在没有 --force 时会中止。它们向标准错误打印 Aborted.，不进行任何更改，并以状态码 0 退出。
cf init 需要目录，例如 cf init my-worker 或 cf init .。新项目使用启动 cf 的包管理器，否则使用 npm。传入 --package-manager 可选择其他包管理器。

在作业中传入 --force 之前，请阅读该命令的 --help 输出。在某些命令上，--force 也是 API 参数。

提交项目配置

在没有 cloudflare.config.ts 的项目中，每个会构建的命令都会先运行自动配置。在 CI 中，自动配置会接受检测到的设置、安装软件包，并在不问询的情况下编辑项目文件。

为避免未经审查的更改，请在本机运行 cf init .。审查结果，并将 cloudflare.config.ts 与其他更改一起提交。有关自动配置会改动什么，请参阅自动配置。

构建一次，然后部署该构建

要部署先前步骤构建的内容，请先构建一次项目：

npx cf build

yarn cf build

pnpm cf build

然后使用 --prebuilt 以及它所记录的模式部署该构建：

npx cf deploy --prebuilt --mode production

yarn cf deploy --prebuilt --mode production

pnpm cf deploy --prebuilt --mode production

--prebuilt 会跳过构建和自动配置，并使用 .cloudflare/output 中的 Build Output。除非你传入 --mode，否则 Vite 构建会记录 production。如果用 --mode staging 构建，请用 --mode staging 部署。模式不匹配时，部署会在上传任何内容之前停止，并打印应使用的模式。

如果 Build Output 包含多个 Worker，除非传入 --worker <NAME>，否则 cf 会部署默认 Worker。完整规则请参阅部署预构建输出。

用 dry run 检查拉取请求

cf deploy --dry-run 会构建项目并验证结果，而不会上传或发送 API 请求。它不需要凭据，因此也适用于来自 fork 的拉取请求（这些拉取请求无法使用 CI secrets）。

npx cf deploy --dry-run

yarn cf deploy --dry-run

pnpm cf deploy --dry-run

要改为检查先前步骤的构建，请像示例工作流那样添加 --prebuilt 以及所记录的 --mode。

从 CI 部署预览

cf previews deploy 会构建项目并部署 Worker Preview。它需要凭据，并且没有 --dry-run 选项。

npx cf previews deploy

yarn cf previews deploy

pnpm cf previews deploy

预览名称默认为当前分支。在 GitHub Actions 中，cf 读取 GITHUB_HEAD_REF 或 GITHUB_REF_NAME。在 GitLab CI/CD 中，它读取 CI_COMMIT_REF_NAME。否则，它使用当前 Git 分支。在没有这些变量的游离检出中，请将预览名称作为参数传入。有关输出和选项，请参阅部署预览。

关闭遥测

cf 会发送匿名使用遥测，其中会记录它是否在 CI 中运行。要为作业关闭遥测，请在作业环境中设置 CF_SEND_TELEMETRY=false 或 DO_NOT_TRACK=1。cf 在 CI 中不会检查 npm 更新。