Cloudflare Artifacts：产品、概念、API 与最佳实践

Cloudflare Artifacts

AI 参与说明（Agent：Cursor）：本文根据 Cloudflare 官方文档、Changelog、产品博客，以及 Context7 库 /cloudflare/cloudflare-docs 整理。资料核对于 2026-09-10。Artifacts 当前是 closed beta。本地 Cloudflare skill 里的 Artifacts 参考仍可能写 artifacts.cloudflare.net/v1/api 与 gateway JWT；现行控制面以 Cloudflare v4 REST 为准。运行记录：模型 grok-4.6，提供方 xAI，执行入口 Cursor。reasoning effort 与 CLI 版本未取得运行记录。

场景补充（2026-09-11，Agent：Cursor）：补充公开 GitHub 某版本归档、离线分析与 Agent 接入；钉死版本用 commit SHA 或 GitHub source archive，不走 GitHub App / Origin。运行记录：模型 grok-4.6，提供方 xAI，执行入口 Cursor。reasoning effort 未取得运行记录。

结论：Artifacts 是你的 Cloudflare 账户拥有的可编程 Git 存储面，不是 GitHub / Origin 那种「某个用户或某个 installation 的 forge」。 应用代码自己创建 Namespace 与 repo、自己签发 repo-scoped token，再把 remote 交给任意 Git 客户端、Sandbox 或 Agent。官方一句话是 Versioned storage that speaks Git。适合 Lovable 式每用户 / 每会话仓；不适合替代团队主仓库上的 Pull Request、评审与安装级权限。Artifacts overview

Artifacts stores versioned file trees behind a Git-compatible interface. Create repositories programmatically, import existing repositories, and hand off a URL to any standard Git client. Artifacts overview

与 GitHub API、Cursor Origin API 的对照，以及何时毕业到 forge，见 Cursor Origin 与 Cloudflare Artifacts：代码协作平台与 Agent 可编程 Git 存储选型。

阅读前先看这几个词

它解决什么问题

GitHub、GitLab、Cursor Origin 面向人与团队：组织、安装、Pull Request、评审、检查。它们的 API 主语是某个用户、某个 org，或装进客户工作区的 App。你可以做 Code Review SaaS，但仓仍归客户所有。

Artifacts 面向 Agent 与自动化：Create a thousand, a million or ten million repos: one for every agent, for every upstream branch, or every user. 官方最佳实践写得更硬：If you have 10,000 agents, create 10,000 repos. Artifacts now in beta Best practices

适合用 Artifacts 的时候：

• 要存的是版本化文件树，而不是单个 R2 对象、KV 键或 SQL 行
• 需要把工作交给会 Git 的 Agent、Sandbox、CI
• 每个用户、会话、任务要隔离历史、清理和访问控制
• 从共享基线 fork，再 diff / merge 结果

不适合单独承担：

• 团队主仓库的长期评审、CODEOWNERS、安装级权限
• 私有 GitHub / Origin 仓的 OAuth 与细粒度授权（仍走 GitHub App / Origin App）
• 把开源社区协作直接建在 closed beta 存储层上

flowchart TB
  ask["需要存版本化文件树？"] --> q1{"仓归谁所有？"}
  q1 -->|客户的 GitHub / Origin 工作区| forge["客人进入客户的 forge"]
  q1 -->|你的 Cloudflare 账户| art["Artifacts"]
  art --> ns["Namespace"]
  ns --> repo["每用户 / 每会话 / 每 Agent 一个 Repository"]
  repo --> git["Git Smart HTTP"]
  repo --> rest["REST content 只读"]
  forge --> gh["GitHub App / Origin App"]

核心概念

Namespace

A namespace is the top-level container for repositories. Use it to separate environments, tenants, or shards. Repository names are unique within a namespace, not across the account. You can have app in both prod and staging. Namespaces

你可以显式 POST /artifacts/namespaces，也可以在还不存在的名字下创建第一个 repo，让平台隐式建 Namespace。需要把数据限制在 eu 或 us 时，必须在创建时带 jurisdiction；创建后不可改。Data localization

命名规则与 repo 相同：以字母或数字开头，后续可用字母、数字、.、_、-。

Wrangler binding、REST base URL、Git remote 必须使用同一个 Namespace 名。

Repository

Each repo is an isolated Git service with its own remote URL, tokens, and durable state. Like Durable Objects, a repo is a single logical instance that Cloudflare can route to from any region. How Artifacts works

同一仓有三套接口，指向同一份数据：

The Workers binding and the REST API are control-plane interfaces. The Git protocol is the data-plane interface. Binding 可以建仓，但不能在仓里写文件；写入走 Git（本地 git、Sandbox 里的 git，或 Worker 里的 isomorphic-git）。Repositories isomorphic-git example

常见顺序：

1. binding 或 REST 建仓 / import / fork
2. 记下 remote
3. 签发 repo-scoped token
4. 用 remote + token 做 Git 读写

Token

Artifacts tokens are repo-scoped. A token minted for one repository does not grant access to another repository, even in the same namespace.

格式：art_v1_<40 hex>?expires=<unix_seconds>。create / import / fork 返回 token 字符串，过期写在 ?expires=。createToken / POST /tokens 额外返回 expiresAt / expires_at。REST 的 ttl：最短 60 秒，最长 31,536,000 秒（约一年），默认 86,400 秒。默认 scope 是 write。

三类凭证不要混：

Cloudflare API tokens authenticate control-plane access. Repo-scoped Artifacts tokens authenticate Git access. Authentication

它怎么工作

flowchart TB
  subgraph control [Control Plane]
    W[Worker env.ARTIFACTS]
    API[Cloudflare v4 REST]
    CLI[wrangler artifacts]
    Dash[Dashboard]
  end
  subgraph store [Account-owned storage]
    NS[Namespace]
    R[Repository / Durable Object]
    NS --> R
  end
  subgraph data [Data Plane]
    Git[Git Smart HTTP]
    Content[REST /file /log /tree]
    IFS[isomorphic-git in Worker]
    SB[Sandbox git]
  end
  W --> NS
  API --> NS
  CLI --> NS
  Dash --> NS
  R --> Git
  R --> Content
  IFS --> Git
  SB --> Git

Durability is the default. Cloudflare replicates repo data synchronously across multiple data centers and copies it asynchronously to object storage and snapshots. You do not build your own replication pipeline. How Artifacts works

官方博客（实现细节，不是 SLA）：每个 repo 是 Durable Object；Git server 用 Zig 写成约 100KB WASM；对象落 SQLite，超过行大小限制则分块；大对象可 snapshot 到 R2；token 跟踪可用 KV。Artifacts: versioned storage that speaks Git

Git remote 形态：

https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/<namespace>/<repo>.git

以 create / get 返回的 remote 为准，不要手拼 changelog 里的旧 URL。2026-04-16 changelog 出现过 https://artifacts.cloudflare.net/v1/api/... 与不含 account 前缀的 clone URL；现行 REST 文档更新于 2026-08-13，控制面走 https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts/...。REST API Git protocol

协议能力：clone / fetch 支持 Git protocol v1 与 v2；push 只支持 v1 receive-pack。部分可选 v1 capability（如 filter、include-tag）未支持。

产品入口

Dashboard 管理于 2026-06-17 进入文档。未开通 beta 时先填 申请表。Manage Artifacts from the Cloudflare dashboard

怎么用：从零到第一仓

前置：Workers Paid 账户、Artifacts closed beta 已开通、Cloudflare API Token 具备 Artifacts Edit（REST）或已 wrangler login（binding / CLI）。

1. 选定 Namespace

学习阶段用 default。生产按环境拆：staging / prod。需要数据驻留时显式创建：

export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export ARTIFACTS_ACCOUNT_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts"

curl --request POST "$ARTIFACTS_ACCOUNT_BASE_URL/namespaces" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "namespace": "prod",
    "jurisdiction": "us"
  }'

2. Worker 绑定

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "artifacts-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-10",
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "prod"
    }
  ]
}

artifacts 在 named Wrangler environment 里不可继承，每个环境都要重复声明。本地 wrangler dev 可加 remote = true 打到远端 Artifacts。然后 npx wrangler types，把生成的 Artifacts 类型当 source of truth。Workers binding

3. 创建并交给 Git 客户端

interface Env {
  ARTIFACTS: Artifacts;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 生产环境必须先鉴权调用方，再建仓或返回 token。
    const created = await env.ARTIFACTS.create("starter-repo", {
      description: "Repository for automation experiments",
      readOnly: false,
      setDefaultBranch: "main",
    });

    return Response.json({
      name: created.name,
      remote: created.remote,
      token: created.token,
    });
  },
} satisfies ExportedHandler<Env>;

开发机克隆（推荐把完整 token 放在 header，不要写进 URL）：

export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_CREATE>"
export ARTIFACTS_TOKEN="<PASTE_TOKEN_STRING>"

git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" \
  clone "$ARTIFACTS_REMOTE" artifacts-clone

短时一次性命令才把 secret 放进 Basic auth 密码位；用户名任意非空即可，常用 x。先去掉 ?expires=：

export ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}"
export ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}"
git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone

4. 从公开 Git remote 导入

const imported = await env.ARTIFACTS.import({
  source: {
    url: "https://github.com/cloudflare/workers-sdk",
    branch: "main",
    depth: 100,
  },
  target: { name: "workers-sdk" },
});

REST 等价路径是 POST .../repos/:name/import，body 为 { url, branch?, depth?, read_only? }。url 必须是完整 HTTPS Git remote。仓仍在 importing / forking 时可能 409，按错误信息重试。Import repositories

私有 GitHub 仓的授权不在 Artifacts 控制面里；导入文档面向公开 HTTPS remote。官方把 branch 写成 Branch to import，没有承诺 tag 或 commit SHA 可作为该字段。要钉死某个版本，用下面的归档场景，不要把 tag 名塞进未文档化的 branch。

API 速查

Workers binding：Namespace 方法

opts：readOnly、description、setDefaultBranch。

Workers binding：repo handle

先 await env.ARTIFACTS.get(name)。

没有 writeFile。Worker 内写入用 isomorphic-git 官方示例（MemoryFS + git.push，onAuth 的 password 是去掉 ?expires= 的 secret）。

REST：账户级 Namespace

Base：https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts

REST：Namespace 内 repo 与 token

Base：.../artifacts/namespaces/$ARTIFACTS_NAMESPACE

Successful blob, file, and raw responses return file bytes directly instead of JSON. 错误仍走 v4 envelope。这些 content 路由用 Cloudflare API Token，不是 Git token。REST API

Wrangler

npx wrangler artifacts namespaces list
npx wrangler artifacts namespaces get default
npx wrangler artifacts repos create starter-repo --namespace default
npx wrangler artifacts repos list --namespace default
npx wrangler artifacts repos get starter-repo --namespace default
npx wrangler artifacts repos issue-token starter-repo --namespace default --scope read --ttl 3600
npx wrangler artifacts repos delete starter-repo --namespace default

Wrangler commands

最佳实践

下面先复述官方规则，再给出可执行场景。官方原文：Best practices。

官方规则（必须对齐）

1. 一单位工作一仓。Create one repo for each unit of autonomous work. If you have 10,000 agents, create 10,000 repos. 不要用一个共享仓当多个 Agent 的队列。只有协作者共享同一生命周期时才用 branch。
2. 名字带稳定 ID。仓名在 Namespace 内唯一。用 ${agentName}-${sessionId}-${repoName}，不要所有人抢 docs-site。
3. 从已审查基线 fork。比手工往每个新仓拷模板更安全，下游 diff 也更短。
4. 最小权限、短时 token。检索 / 审查用 read；只有必须 push 的会话才发 write。每次会话重新签发，不要给所有 Agent 同一张长期 write token。
5. 提示词进 git notes。git notes 挂在 commit 上，不改 working tree。跨系统同步时记得 push / fetch refs/notes/*。
6. 用 Namespace 切环境与限流。控制面限额是每个 Namespace 2,000 请求 / 10 秒。热路径拆 agents-batch / agents-realtime，不要把所有仓堆进 default。

场景：Lovable 式租户工作区

目标：SaaS 给每个登录用户一份可 fork 的应用仓，Agent 在仓里改代码并 push，平台在 push 后跑检查。

本文建议（不是官方硬性 API）：租户身份放在你自己的鉴权层（Clerk 等）；Artifacts 只存文件树。仓名不要用邮箱原文，用你系统里的稳定 tenantId。

Worker 侧 fork 与发牌（示意，须先鉴权）：

interface Env {
  ARTIFACTS: Artifacts;
}

async function openTenantWorkspace(
  env: Env,
  tenantId: string,
  workspaceAlreadyExists: boolean,
) {
  const name = `app-${tenantId}`;

  if (workspaceAlreadyExists) {
    const repo = await env.ARTIFACTS.get(name);
    return {
      name,
      remote: repo.remote,
      token: (await repo.createToken("write", 3600)).plaintext,
    };
  }

  const baseline = await env.ARTIFACTS.get("starter-app");
  const forked = await baseline.fork(name, {
    description: `Workspace for ${tenantId}`,
    defaultBranchOnly: true,
    readOnly: false,
  });

  return {
    name: forked.name,
    remote: forked.remote,
    token: forked.token,
  };
}

get() 在仓不存在或尚未 ready 时会抛错。官方 Sandbox 示例要求：用应用侧记录判断「刚创建还是复用」，直接按 ID 查找，不要扫 list()，也不要用宽泛 catch 把缺仓、鉴权和校验失败吞成同一种重试。Sandbox SDK + Artifacts

repo.remote 与 createToken() 的返回形状以 npx wrangler types 生成文件为准。

条件变化时：

• 只要索引、不要改代码：步骤 4 改 createToken("read", 900)。
• 控制面打满 2,000 / 10s：按租户哈希把新仓分到 prod-a / prod-b Namespace。
• 需要团队评审或对外开源：把仓毕业到 GitHub / Origin，而不是在 Artifacts 上模拟 forge。

场景：归档公开 GitHub 的某个版本，再做离线 / Agent 分析

目标：把某个开源仓的 一个确定版本 存下来，本机离线读，或交给 Agent。公开仓不需要 GitHub App，也不需要 Origin。GitHub App / Origin App 是给私有仓授权、webhook 和回写 PR / check 用的。

分析记录绑定 owner/repo@commitSha，不要用 branch 名或浮动 tag 当 ID。GitHub 说明：An archive of a commit ID will always have the same file contents；tag 和 branch 可以移动。可复现归档用 40 位 commit SHA。Downloading source code archives

flowchart TB
  pub["公开 GitHub HTTPS？"] --> yes{"只要这一版的文件树？"}
  yes -->|是，一次性离线| gh["git clone --branch TAG 或 GitHub archive URL"]
  yes -->|要长期给 Agent 复用| art["Artifacts import 公开 remote"]
  art --> pin["status ready 后 checkout 目标 SHA，read_only"]
  pub --> no["私有仓才需要 GitHub App / PAT"]

路径 1（官方 Git，零 Cloudflare）

# 先把 tag 解析成 SHA，再按 SHA 克隆，避免 tag 被移动
git ls-remote --tags https://github.com/facebook/react.git 'v18.3.1^{}'

git clone --filter=blob:none --no-checkout \
  https://github.com/facebook/react.git react-v18.3.1
git -C react-v18.3.1 fetch --depth 1 origin <COMMIT_SHA>
git -C react-v18.3.1 checkout --detach <COMMIT_SHA>

只要工作树、不要历史时，GitHub 直接提供 source archive（公开仓匿名可下）：

# tag 快照（tag 可能被移动，不适合当长期 ID）
curl -L -o react-v18.3.1.tar.gz \
  https://github.com/facebook/react/archive/refs/tags/v18.3.1.tar.gz

# commit 快照（可复现）
curl -L -o react-<COMMIT_SHA>.tar.gz \
  https://github.com/facebook/react/archive/<COMMIT_SHA>.tar.gz

Source code archive URLs

路径 2（要给 Agent 一个可 fork 的真源：Artifacts）

这是官方 import 的用途：a baseline repo that agents fork from。本文建议把导入结果当成冻结基线，而不是继续跟踪上游 main。

const imported = await env.ARTIFACTS.import({
  source: {
    url: "https://github.com/facebook/react",
    branch: "main",
  },
  target: {
    name: "archive-react-18-3-1",
    opts: { readOnly: true },
  },
});

导入返回后仍可能 409。list() 里 status 为 ready，并且 GET .../repos/archive-react-18-3-1/commit/<COMMIT_SHA> 成功，才算这版进了 Artifacts。浅克隆 depth: 100 很可能不含两年以前的 release；归档旧版本时不要设很小的 depth，或改走路径 1 的 archive URL。

Sandbox / 本机 Agent 也可以 直接 git clone https://github.com/owner/repo.git，公开 HTTPS 不需要 token。容器不是持久盘：分析要复现，把 checkout 后的树或 tarball 放到 Artifacts / R2，而不是留在 Sandbox 磁盘。大仓启动慢时，ArtifactFS 可以对 GitHub remote 做 blobless clone，不限于 Artifacts。ArtifactFS

本文建议不要走 Origin 的原因：公开仓没有「安装到客户工作区」这件事。Origin Partner API 不能按 namespace 自助开仓，mirror 还受 GitHub inbound 限制。为读一版开源树去装 Origin App，成本高于 import 或 GitHub archive。

条件变化时：

• 仓是私有的：才需要 PAT 或 GitHub App；Artifacts import 文档不覆盖私有 HTTPS。
• 只要 Issues / PR / Actions：仍在 GitHub 上读，Artifacts 只存文件树。
• 上游还在推：基线仓保持 read_only；新版本另一次 import 到新名字，例如 archive-react-<shortSha>，不要在同一仓里 git pull 冲掉旧 SHA。

场景：Sandbox 一仓一 ID

官方模板 git-repo-per-sandbox：Sandbox ID 与 Artifacts repo 名相同；新建则 create(sandboxId)，复用则 get + createToken("write", 3600)；把 token secret 嵌进 URL 后写入 ARTIFACTS_GIT_REMOTE。短时 token，且只在会话已授权 push 之后注入。Sandbox SDK + Artifacts

容器不是持久盘。Sandbox 休眠后工作树会丢，跨生命周期的真源应在 Artifacts（或 R2 备份）。见 Sandbox SDK：命令、文件、进程与会话 API 实战。

场景：push 后构建并部署

cf.artifacts.repo.pushed 可触发 Workflow。官方 Wrangler 注释：If you don’t set repoName we will run the same workflow for every push on any repo in your Artifacts namespace. 这是平台 Namespace 模式：一份 CI 覆盖该 Namespace 里每一个客户仓，并可把产物部署到 Worker 或 Workers for Platforms User Worker。Build and deploy

通过标准：一次 push 产生 Workflow 实例；检查失败则不部署；部署步骤才使用收窄后的 API Token。

事件

2026-05-19 起可订阅。Event subscriptions

账户级（source artifacts）：

仓级（source artifacts.repo，需 namespace + repoName）：

ArtifactFS

ArtifactFS mounts a Git repository as a local filesystem without waiting for a full clone. It starts with a blobless clone, then hydrates blobs through FUSE. 适用于大仓；小仓直接 git clone 更简单。它可用于 Artifacts remote，也可用于 GitHub / GitLab 等任意 Git remote。Agent 仍用 commit + push，没有另一套写回 API。ArtifactFS

限额、定价与 beta

整理日期 2026-09-10。overview 标注 closed beta（2026-05-05）；定价页 2026-04-21；限额页 2026-05-04。

Limits

Operations 包括 create、push、pull、clone 等。Storage 按账户内所有仓的 GB-mo，算法与 Durable Objects SQL storage 相同。Replicas do not add storage charges. Repos remain stored until you explicitly delete them. 博客写 Free 计划会在 beta 推进中开放；当前定价页仍标 Unavailable。Pricing

「tens of millions of repos」是产品叙事。设计应对齐限额、定价与账户开通状态，而不是把营销句当成 SLA。

和站内其它存储怎么选

Cloudflare 平台 skill 的决策树把 versioned file trees 指向 Artifacts，把 objects / KV / SQL 留给 R2、KV、D1。这与官方 docs 一致。

关联阅读

• Cursor Origin 与 Cloudflare Artifacts：代码协作平台与 Agent 可编程 Git 存储选型：API 主语、调用链与场景分流
• Workers：运行时 API、Bindings 与执行模型：binding 与控制面 Token 的职责边界
• Sandbox SDK：命令、文件、进程与会话 API 实战：容器不是持久盘；可与 Artifacts 一 ID 一仓组合
• Durable Objects 使用方式与接口整理：Artifacts repo 背后的隔离实例模型
• Workflows：实例、步骤、事件与恢复 API 实战：cf.artifacts.repo.pushed 触发 CI

参考资料

• Artifacts（overview，closed beta，更新于 2026-05-05）
• Get started
• Namespaces（更新于 2026-08-13）
• Repositories
• How Artifacts works
• Best practices
• Authentication
• Workers binding（更新于 2026-06-11）
• REST API（现行 v4 控制面，更新于 2026-08-13）
• Git protocol
• Wrangler commands
• Import repositories
• Downloading source code archives
• Event subscriptions
• Build and deploy
• Data localization
• ArtifactFS
• isomorphic-git
• Sandbox SDK + Artifacts
• Limits
• Pricing
• Artifacts now in beta
• Event subscriptions changelog
• Dashboard management changelog
• Artifacts: versioned storage that speaks Git

Context7 核查：通过 /cloudflare/cloudflare-docs 核对了 Workers binding（含 import()）、REST v4 base URL、token TTL、Git http.extraHeader、best practices 的 fork / 短时 token / Namespace 分片，以及 cf.artifacts.repo.pushed 可省略 repoName 的平台 Namespace 模式。changelog 中的 artifacts.cloudflare.net/v1/api 只作历史线索。