Cloudflare Workers Builds：能承担哪些工作，与 GitHub Actions 如何分工

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Cloudflare 与 GitHub 官方文档整理，使用 Context7 辅助核验，资料日期为 2026-09-16。功能与限额以文中官方来源为准；任务分工属于本文建议。运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 版本 0.154.0-alpha.6.2（不代表桌面 App 版本）。

配置说明补充（2026-09-16，Agent：Codex）：核对 Workers Builds 平台命令、Wrangler Custom Builds 与仓库脚本的配置边界，补充 Builds API 管理方式。运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 版本 0.154.0-alpha.6.2（不代表桌面 App 版本）。

Worker Previews 更新（2026-09-28，Agent：Codex）：根据新发布的 Worker Previews 文档，区分新旧非生产分支命令与 Durable Objects、Containers 的预览资源边界。执行入口 Codex Desktop；完整模型标识与 reasoning effort 未取得运行记录。

Workers Builds 可以承担一个 Cloudflare 项目的检查、测试、构建和部署。当需求扩展到多操作系统、多任务依赖、人工审批或大量仓库自动化时，GitHub Actions 的原生编排能力更合适。两者都能执行脚本，选型应看运行环境与流程复杂度。

Workers Builds 实际运行什么

Workers Builds runs a configurable build command followed by a deploy command. GitHub Actions organizes automation into workflows, jobs, and steps. Cloudflare 配置、GitHub Actions 基础概念

当前 Workers Builds 使用 Ubuntu 24.04、x86_64 构建环境，支持 Node.js、Python、Go 等工具链。因此它可以运行测试、数据处理和构建脚本；这些命令不是在处理网页请求的 Worker Runtime 中执行，不能套用 Worker 请求的 CPU 时间限制。Build image

适合放进去的工作包括：

• 质量检查：格式检查、lint、类型检查、单元测试，以及能在其环境和时限内完成的集成测试。
• 生成发布产物：编译前端、生成静态 HTML、压缩资源、生成类型和搜索索引。
• 准备构建数据：调用 CMS/API、拉取公开内容、转换 JSON 或 Markdown，再参与构建。
• 发布相关脚本：在凭据和权限齐全时上传资源、上传 source map、调用其他服务的 CLI/API。数据库迁移也可由脚本执行，但其失败与回滚策略需要单独设计。

这些是根据自定义命令与构建环境推导出的可承担任务，并不表示平台为每项都提供了专门界面。测试失败应返回非零退出码；具体工具、网络依赖和耗时需要在真实构建中验证。

部署目标通常是 Worker、随 Worker 发布的静态资源，或适配 Workers 的全栈应用。当前也支持通过 wrangler deploy 构建和发布 Cloudflare Containers 的镜像；不能笼统地说 Workers Builds 不支持 Dockerfile 构建。在 Deploy Containers 指南所述的 wrangler versions upload 分支流程中，只上传 Worker 代码而不更新 Container 镜像；对应的 Version URLs 不提供分支资源隔离。新的 Worker Previews 则会为每个 Preview 自动配置独立的 Durable Object namespace/storage 和 Container app/instances，需要 Wrangler 4.135.0 或更新版本；Containers 的 Preview 支持目前仍有部分限制，须实测进程是否启动并响应。Deploy Containers、Worker Previews 的资源隔离、工作流比较

与 GitHub Actions 的工作边界

下表区分平台现成能力与需要自己编写的流程。Workers Builds 没有同级配置入口，不代表通过脚本绝对无法实现。

GitHub 侧依据：jobs 与依赖、Matrix 和 service containers 语法、Runner 环境、self-hosted Runner、workflow artifacts、事件触发、部署环境及套餐条件。

Workers Builds 可以连接同一 monorepo 下的多个 Worker，分别配置 Root directory、命令及 Build watch paths；这方便按应用独立构建，但不等于已有跨应用的统一依赖编排。Advanced setups

一个可以直接套用的发布流程

下面针对已有 Node.js 项目：package.json 已定义 lint、typecheck、test:ci 和 build，其中 test:ci 执行一次测试后退出；项目已配置 Wrangler，并在依赖及 lockfile 中固定版本。脚本名是本文示例，使用时替换为项目实际入口。

在 Worker 的 Settings → Build 中设置 Build command：

npm run lint && npm run typecheck && npm run test:ci && npm run build

生产 Deploy command：

npx wrangler deploy

这对应“检查通过 → 测试通过 → 生成产物 → 部署”。&& 保证前一步失败时停止后续命令，避免吞掉测试失败后继续构建。可以把长命令收进仓库脚本，再在控制台调用。Build command 与 Deploy command

Workers Builds 默认会安装依赖，因此上例没有再加一次 npm ci。如果需要自行控制安装过程，可设置 Build variable SKIP_DEPENDENCY_INSTALL=1，再把 npm ci 加在命令最前面。依赖安装配置

验收时检查三个结果：让一个测试故意失败，确认没有进入部署；恢复测试后确认生成并部署预期产物；核对日志中的提交版本与目标环境。本文仅验证了命令串的成功、失败短路行为，没有为该示例创建真实 Worker 或执行远端发布。

如需分支预览，新接入 Workers Builds 的 Worker 默认使用 npx wrangler preview，启用 Preview Builds 后为非生产分支创建 Worker Previews。此前已连接 Builds 的 Worker 保留旧的 Version URL 模型，直到在控制台完成不可逆的一次性切换；切换前需要补齐独立的 Preview 配置、密钥与测试资源。也可把非生产分支命令改为只检查、不上传的脚本，作为轻量 CI；前提仍是已连接的 Worker 构建项目。分支构建、自定义非生产分支命令

构建与部署命令放在哪里

Workers Builds 的 Build command / Deploy command 属于平台上的 trigger 配置，可以通过控制台或 Builds API 设置；不能直接在 wrangler.jsonc 中声明这两个流水线入口。官方目前明确指出，Workers Builds 不遵循 Wrangler 配置中的 Custom Builds。Workers Builds 配置边界

Wrangler Custom Builds is a CLI build hook, not the configuration source for Workers Builds pipeline commands. 例如下面是 Wrangler 的配置片段：

{
  "build": {
    "command": "npm run build"
  }
}

普通 Wrangler 工作流中，这个命令可以作为 wrangler dev、wrangler deploy 的一部分执行。它不会替你声明或同步 Workers Builds 后台的两个入口，因而也不能把“不作为平台配置”扩大解释成“这个字段在所有 Wrangler 场景都不会运行”。使用 Cloudflare Vite plugin 时，该 Custom Builds 配置不适用，仍应按框架自己的构建流程处理。Wrangler Custom Builds、Vite plugin 适用边界

实用做法是将实际逻辑保存在仓库中。沿用上节已有脚本及 Wrangler 依赖的前提，将以下条目合并到 package.json 的 scripts，保留项目已有配置：

{
  "scripts": {
    "ci:build": "npm run lint && npm run typecheck && npm run test:ci && npm run build",
    "ci:deploy": "wrangler deploy"
  }
}

然后仅在控制台设置固定入口：

之后修改检查或构建步骤，只需更新仓库脚本；入口名称不变时，后台也无需跟着修改。若项目同时保留 Wrangler Custom Builds，应核对实际日志，避免同一构建被多个入口重复执行。这是本文的组织建议。

如果希望连平台入口也自动化管理，Builds API 提供 PATCH /accounts/{account_id}/builds/triggers/{trigger_uuid}，可以更新 build_command 和 deploy_command。production 与 preview 使用不同 trigger，需按目标分别配置。这里仍是通过 API 更新平台状态，并不是把同名字段加入 wrangler.jsonc 就会生效。更新 trigger 配置

定时同步、内容更新也能触发吗

可以。CMS、其他 CI 或调度器可以请求 Deploy Hooks，触发指定分支的构建。官方也给出了由 Worker Cron Trigger 定时调用 Deploy Hooks 的方式，因此不能将 Workers Builds 描述成只能在 Git push 时执行。Deploy Hooks

区别是 Actions 可以在工作流里直接声明 schedule；Workers Builds 的这个方案由外部调度器负责时间，再通过 Deploy Hooks 启动构建。它适合“定时更新数据后重建网站”；纯数据同步或仓库维护若与发布无关，通常留在 Actions 或专门的定时任务中更清晰。这是工作分工建议。Actions 触发方式

Deploy Hooks URL 本身携带触发权限，应作为 secret 保存；构建用 secrets 与 Worker 运行时 secrets 也应分别配置。Deploy Hooks 权限、Build variables and secrets

决定能否迁移的限制

目前单次 Workers Builds 最长 20 分钟；免费／付费套餐在同一账户下分别允许 1／6 个并发构建，配备 2／4 vCPU，内存均为 8 GB、磁盘均为 20 GB。测试、准备数据、编译和部署应整体考虑耗时。Limits & pricing

因此，长时间 E2E、大规模矩阵测试、视频处理、训练或常驻进程不适合依赖这条构建流水线；有浏览器依赖的短测试则需实测安装、启动与耗时，不能仅凭它是 Node.js 命令就认定一定可用。这些是依据资源限制提出的选型建议。

费用也不能只比较“3,000 免费分钟”：公开仓库使用 GitHub standard hosted runners 免费且不限分钟，larger runners 等另有计费，artifacts 存储也有自己的规则。是否迁移应先看仓库可见性、Runner 类型和实际耗时。GitHub hosted runners

如何组合两者

• 简单 Cloudflare 应用：Workers Builds 负责快速检查、测试、构建和部署，维护一套发布配置。
• 测试与仓库自动化较多：Actions 负责 Matrix、较重测试、npm/Release 发布和仓库维护；Workers Builds 负责应用发布。
• 生产必须等待完整 Actions 检查：由 Actions 统一组织检查与发布，或在检查通过后显式触发受控构建；核对实际构建的 commit 与通过检查的 commit 一致。

最后一种场景要明确：两个平台同时监听同一次 push，并不自动形成“Actions 测试完成后 Workers Builds 才部署”的依赖关系。如果这是发布条件，应显式建立顺序，避免独立流水线竞速；同一目标也尽量只保留一个实际发布入口。这是根据两套触发模型得出的工程建议。Cloudflare Git 集成、Actions jobs 依赖

迁移时可以复用仓库里的 Shell、Node.js、Python 脚本；.github/workflows/*.yml 的 jobs、事件和权限配置则需要按 Workers Builds 的入口重新安排，不能当作可直接导入的构建配置。

关联阅读

• Cloudflare Worker Previews：按分支管理预览环境
• Workers Builds：免费额度、超限处理与费用计算
• Cloudflare 文档导航