跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

构建并部署 Artifacts 存储库

最后更新 查看 MarkdownAgent 设置

Artifacts 事件可以构建并部署存储在 Artifacts 存储库中的项目。当用户或智能体(agent)推送提交时,该事件会触发一个 Workflow 实例。

如果您需要 Worker 的标准构建与部署行为,请使用 Workers Builds Artifacts 集成。Workers Builds 会在您向存储库推送时运行已配置的构建和部署命令,并支持为非生产分支创建 Worker Previews。

当您需要自定义持续集成(CI)流水线时,请继续阅读本指南。例如,使用此工作流可以并行运行多项检查、跨 runner 缓存依赖项、部署到 Workers for Platforms,或应用自定义重试和凭据设置。

在 Workflow 中,您可以使用 @cloudflare/ci SDK 定义 CI 流水线,以缓存依赖项、运行检查并构建项目。CI 流水线的最后一步可以将输出部署到 Worker 或 Workers for Platforms User Worker。

在需要执行以下操作时,这会很有用:

  • 自动构建并部署存储在 Artifacts 中的应用代码。
  • 在每次推送时运行 lint、类型检查、测试以及其他检查。
  • 在锁文件(例如 pnpm-lock.yaml)未变更时复用依赖项。
  • 在检查或构建失败时停止部署。
  • 将 API 令牌访问权限限制在部署步骤。
  • 将输出部署到 Worker 或 Workers for Platforms User Worker。

工作原理

Artifacts 仓库变更
仓库变更
CI Workflow
1安装并缓存依赖项
2运行 CI 步骤
构建
Lint
类型检查
格式化
部署 Worker
  1. 推送存储库变更 — 向 Artifacts 存储库执行 git push 会发出 artifacts.repo.pushed 事件,该事件会标识被推送的存储库、分支和提交。
  2. 运行 CI Workflow — 该事件会启动一个 Workflow:检出提交、安装并缓存依赖项,然后并行运行 CI 步骤(build、lint、typecheck 和 format)。若某一步失败,会在部署前停止 Workflow。
  3. 部署 Worker — Workflow 会将构建好的 Worker 直接部署到您的账户,或在使用 Workers for Platforms 时部署为 User Worker。

运行 CI Workflow

使用 @cloudflare/ci SDK 定义 CI 步骤。该 SDK 提供两个工具来帮助您构建流水线:

  • Runners — 每次调用 runner() 都会启动一个隔离的沙箱并执行一条 shell 命令。您可以使用已经在本地或其他 CI 系统中运行的相同命令。每个 runner 都会捕获自己的日志、状态和输出文件。
  • Cache — runner 上的 cache 选项会缓存已安装的依赖项,以便后续运行无需重新安装。将决定依赖项的文件(例如 pnpm-lock.yaml)传给 cache.inputs。当这些文件未变更时,SDK 会恢复缓存结果,而不是再次运行该命令。
示意图:三个连续提交。提交 1 发生缓存未命中,因此会运行 install 步骤并将其沙箱快照缓存起来;提交 2 的 pnpm-lock.yaml 未变更,因此缓存键匹配并直接提供已缓存的快照,跳过 install;提交 3 的 pnpm-lock.yaml 已变更,因此缓存键未命中,会再次运行 install。

已缓存的 runner 会为其沙箱拍摄快照(snapshot),供后续 runner 复用。多个 runner 可以从同一缓存结果分支——例如,lint、类型检查和测试 runner 都可以复用一次已缓存的安装。

失败的 runner 会按其步骤配置重试,您可以在其中定义重试次数、退避策略和超时。依赖上一步的 runner 只有在该步重试成功后才会启动。如果达到配置的重试上限,Workflow 会以 Errored 状态终止。

以下示例展示如何设置 Workflow,使用 runner 和缓存来安装依赖项、运行检查、构建项目并部署 Worker:

src/index.jsjs
import { CIWorkflow } from "./src/pipeline";

export class CI extends CIWorkflow {
	async pipeline(_event, _step, ci) {
		// Install once, then run independent checks from the shared snapshot.
		const deps = await ci.runner({
			name: "install",
			command: "bun install --frozen-lockfile",
			cache: { inputs: ["package.json", "bun.lock"] },
		});

		await Promise.all([
			deps.runner({ name: "lint", command: "bun run lint" }),
			deps.runner({ name: "test", command: "bun run test" }),
			deps.runner({ name: "typecheck", command: "bun run typecheck" }),
			deps.runner({ name: "build", command: "bun run build" }),
		]);

		await deps.runner({
			name: "deploy",
			command: "bun wrangler deploy",
			cloudflareCredentials: {
				accountId: this.env.CLOUDFLARE_DEPLOY_ACCOUNT_ID,
			},
		});
	}
}
src/index.tsts
import { CIWorkflow } from "./src/pipeline";
import type {
    CiContext,
    CiParams,
    CiRunnerResult,
    CloudflareArtifacts,
} from "./src/pipeline";
import type { WorkflowEvent, WorkflowStep } from "cloudflare:workers";

export class CI extends CIWorkflow {
    protected async pipeline(
        _event: WorkflowEvent<CiParams<CloudflareArtifacts>>,
        _step: WorkflowStep,
        ci: CiContext,
    ): Promise<void> {
        // Install once, then run independent checks from the shared snapshot.
        const deps: CiRunnerResult = await ci.runner({
            name: "install",
            command: "bun install --frozen-lockfile",
            cache: { inputs: ["package.json", "bun.lock"] },
        });

        await Promise.all([
            deps.runner({ name: "lint", command: "bun run lint" }),
            deps.runner({ name: "test", command: "bun run test" }),
            deps.runner({ name: "typecheck", command: "bun run typecheck" }),
            deps.runner({ name: "build", command: "bun run build" }),
        ]);

        await deps.runner({
            name: "deploy",
            command: "bun wrangler deploy",
            cloudflareCredentials: {
                accountId: this.env.CLOUDFLARE_DEPLOY_ACCOUNT_ID,
            },
        });
    }
}

在代码变更时启动构建

当用户或智能体(agent)向 Artifacts 存储库推送提交时,Artifacts 会发出一个事件,标识发生变更的存储库、分支和提交。您将使用此事件触发 Workflow 实例;该实例会运行 CI 流水线:自动检出提交并克隆存储库,然后根据您的代码安装依赖项、运行检查、构建项目和/或部署 Worker。

本指南在名为 CIWorkflow 的 Workflow 类中定义这些 CI 步骤。要在每次推送后自动启动此 Workflow,请在 Wrangler 配置中添加 cf.artifacts.repo.pushed 触发器。您还应包含:

  • R2 绑定(binding):用于存储缓存依赖项快照的存储桶
  • Container(以及 Durable Object)绑定(binding):创建指向您容器的绑定,以便在每个 runner() 步骤中访问沙箱
  • Workflows 绑定(binding)
  • Artifacts 绑定(binding)
  • 可观测性(可选):通过 Workers 可观测性将 CI 作业作为 Workflow 实例进行检查
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "<worker-name>",
  "main": "src/index.ts",
  "upload_source_maps": true,
  "compatibility_date": "2026-06-16",
  "compatibility_flags": ["nodejs_compat"],
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "<artifacts-namespace>"
    }
  ],
  "containers": [
    {
      "class_name": "CiSandbox",
      "image": "./Dockerfile",
      "max_instances": 10,
      "instance_type": "standard-4"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "SANDBOX",
        "class_name": "CiSandbox"
      }
    ]
  },
  "workflows": [
    {
      "name": "<workflow-name>",
      "binding": "CI_WORKFLOW",
      "class_name": "CI"
    }
  ],
  "exports": {
    "CiSandbox": {
      "type": "durable-object",
      "storage": "sqlite"
    }
  },
  "r2_buckets": [
    {
      "binding": "BACKUP_BUCKET",
      "bucket_name": "<backup-bucket-name>"
    }
  ],
  "triggers": {
    "events": [
      {
        "type": "cf.artifacts.repo.pushed",
        // filter is optional. If you don't set repo_name, the same Workflow runs for every push to any repo in your Artifacts namespace
        "filter": {
          "namespace": "CI",
          "repo_name": "my-repo"
        },
        "targets": [
          {
            "type": "workflow",
            "workflow_name": "<workflow-name>"
          }
        ]
      }
    ]
  },
  "observability": {
    "enabled": true,
    "logs": {
      "enabled": true
    }
  }
}
"$schema" = "node_modules/wrangler/config-schema.json"
name = "<worker-name>"
main = "src/index.ts"
upload_source_maps = true
compatibility_date = "2026-06-16"
compatibility_flags = [ "nodejs_compat" ]

[[artifacts]]
binding = "ARTIFACTS"
namespace = "<artifacts-namespace>"

[[containers]]
class_name = "CiSandbox"
image = "./Dockerfile"
max_instances = 10
instance_type = "standard-4"

[[durable_objects.bindings]]
name = "SANDBOX"
class_name = "CiSandbox"

[[workflows]]
name = "<workflow-name>"
binding = "CI_WORKFLOW"
class_name = "CI"

[exports.CiSandbox]
type = "durable-object"
storage = "sqlite"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "<backup-bucket-name>"

[[triggers.events]]
type = "cf.artifacts.repo.pushed"

  [triggers.events.filter]
  namespace = "CI"
  repo_name = "my-repo"

  [[triggers.events.targets]]
  type = "workflow"
  workflow_name = "<workflow-name>"

[observability]
enabled = true

  [observability.logs]
  enabled = true

查看构建状态

Wrangler 配置中的 [observability] 设置会记录每次流水线运行的状态和日志。要确定哪个阶段失败,请在 Workflows 仪表板中检查该实例:

前往 Workflows ↗

每个 runner 都会显示自己的输入、输出和状态,因此您可以定位失败的命令。当 runner 失败时,Workflow 会记录其输出,并且不会启动需要其文件的后续阶段。

部署应用

要部署 Worker,请将 wrangler deploy 传给最后的 runner() 步骤,例如 workspace.runner({ name: "deploy", command: "wrangler deploy" })。

要部署 User Worker,请将 wrangler deploy --dispatch_namespace <DISPATCH_NAMESPACE> 传给最后的 runner() 步骤。

为命名空间中的每个存储库运行同一个 Workflow

trigger 中的 filter 是可选的。设置 repo_name 后,只有推送到该特定 repo 才会启动 Workflow。省略 repo_name 后,Cloudflare 会为推送到 Artifacts namespace 中任意 repo 的每次操作运行同一个 Workflow。

这对于编写并拥有单一 CI Workflow、并希望将其统一应用于命名空间中每个客户存储库的平台很有用。无需为每个存储库维护单独的触发器,一个共享 Workflow 即可在推送时构建、检查并部署每个存储库。

平台命名空间
Artifact 仓库 A
Artifact 仓库 B
Artifact 仓库 C
Artifact 仓库 D
Artifact 仓库 E
共享 CI workflow由平台编写和维护
构建lint测试类型检查
部署 A
部署 B
部署 C
部署 D
部署 E
分别部署每个仓库

要为 namespace 中的每个 repo 运行同一个 Workflow,请从 trigger 的 filter 中移除 repo_name,只保留 namespace:

{
    "triggers": {
        "events": [
            {
                "type": "cf.artifacts.repo.pushed",
                "filter": {
                    "namespace": "CI"
                },
                "targets": [
                    {
                        "type": "workflow",
                        "workflow_name": "ci-workflow"
                    }
                ]
            }
        ]
    }
}
[[triggers.events]]
type = "cf.artifacts.repo.pushed"

  [triggers.events.filter]
  namespace = "CI"

  [[triggers.events.targets]]
  type = "workflow"
  workflow_name = "ci-workflow"

每次推送仍会为发生变更的存储库、分支和提交启动各自的 Workflow 实例,因此您可以从同一份共享 Workflow 定义中为每个存储库部署单独的 Worker。

这篇文档对您有帮助吗?