【免费下载链接】autoskills
One command. Your entire AI skill stack. Installed.
导读
Cloudflare Artifacts 是一个以「版本化文件树」为核心的存储产品：它把 Git 风格的仓库接口暴露给 Workers 运行时、REST API 与标准 Git 客户端，让同一份内容可以从三种通道统一寻址。本文以本仓库 artifacts/configuration.md 为骨架，结合同目录下的 api.md 与 README.md，完整讲解 Wrangler 绑定声明、TypeScript 类型生成、命名空间与仓库隔离策略、REST 控制面配置、仓库令牌生命周期管理，以及 Git over HTTPS 客户端的接入方式。读完本文，你将能在一个 Worker 项目中从零配置好 Artifacts 绑定，并设计出一套「控制面与数据面分离、令牌最小权限」的自动化工作流。
一、Artifacts 的定位：什么时候该用它
在深入配置之前，先明确 Artifacts 与 Cloudflare 其他存储产品的边界。根据 README.md 的判断表：
| 需求 | 选型 | 原因 |
|---|---|---|
| 版本化文件树：仓库、构建产物、检查点、生成资产 | Artifacts | 存储并共享的是版本化文件系统内容 |
需要clone/fetch/pull/push的 Git 兼容工作流 | Artifacts | 对外暴露git-over-HTTPS remote与仓库级令牌 |
| 同一份内容需要同时被 Workers、HTTP API、开发工具访问 | Artifacts | 同时提供Workers binding、REST API、Git 兼容接口 |
| 按对象键存大文件、按键存配置、关系型应用数据 | R2 / KV / D1 | 需要的只是对象、键值或 SQL 行，而非版本化文件树 |
这一判断逻辑也体现在 Cloudflare 平台技能总览 的存储决策树中：Artifacts 专门承接「版本化文件树（repos、build outputs、checkpoints）」这一类需求。典型场景包括：每 agent、每会话、每任务的独立仓库，构建产物与部署包，检查点与生成资产，以及在开发者工具与 Workers 之间传递的共享文件树。
二、Worker Binding：在 Wrangler 配置中声明 Artifacts
在 Worker 项目中使用 Artifacts，第一步是在wrangler.toml（或wrangler.jsonc）中声明 binding：
[[artifacts]] binding = "ARTIFACTS" namespace = "default"关键字段说明：
binding：绑定名称，决定该绑定在 Worker 运行时暴露为env.ARTIFACTS。你可以按需改名（如MY_ARTIFACTS），但需保持与代码、类型定义一致。namespace：命名空间名称，用于在控制面与数据面上隔离环境、团队或高频率负载。示例使用default，多租户场景应替换为各自的命名空间名。
配置完成后，env.ARTIFACTS即为可用的绑定对象。值得注意的是，若你通过wrangler login认证，当前文档提示 Wrangler 默认会请求artifacts:write权限——这意味着登录态下 Wrangler 默认具备写入能力，生产环境请结合令牌策略（见第五节）控制实际权限边界。
绑定对象在 Worker 中可用的方法，来自 api.md 的绑定参考：
| 方法 | 用途 |
|---|---|
create(name, opts?) | 创建仓库，返回初始 remote 与令牌 |
get(name) | 解析仓库句柄，用于仓库级操作 |
list(opts?) | 列出命名空间内的仓库 |
delete(name) | 删除仓库 |
从 Worker 内创建仓库的最小示例：
const created = await env.ARTIFACTS.create("starter-repo", { description: "Repository for automation experiments", setDefaultBranch: "main" }); // created.remote -> git remote URL // created.token -> initial repo token const repo = await env.ARTIFACTS.get("starter-repo"); const page = await env.ARTIFACTS.list({ limit: 10 });三、TypeScript：用wrangler types生成绑定类型
添加绑定后，需要重新生成 Worker 类型：
npx wrangler types这一命令从你的 Wrangler 配置生成类型定义文件。在 workers/configuration.md 中，推荐做法是安装@cloudflare/workers-types后将生成目录纳入 tsconfig：
{ "compilerOptions": { "target": "ES2022", "lib": ["ES2022"], "types": ["@cloudflare/workers-types"] }, "include": [".wrangler/types/**/*.ts", "src/**/*"] }随后在环境定义中使用生成的绑定类型：
interface Env { ARTIFACTS: Artifacts; }要点：
Artifacts类型由 Wrangler 根据 binding 自动生成，不要手写。- 把生成的
worker-configuration.d.ts视为当前环境类型的唯一事实来源（source of truth）。 - 修改绑定后必须重新执行
npx wrangler types；workers/gotchas.md 也将「修改绑定后类型未更新」列为常见坑，解决方案同样是重跑该命令。 - 若生成出的类型暴露了
import()或不同形态的get()，api.md 提醒：在依赖这些方法前先核对实时文档，避免把实验性接口固化进代码。
四、结构仓库实现隔离：命名空间、仓库与分支的取舍
Artifacts 最适合「自主工作相互隔离」的场景。configuration.md 给出了明确的组织原则：
- 一个仓库对应一个 agent、会话、沙箱或任务：当工作应当彼此分离时，为每个独立工作单元建独立仓库。
- 从已审查的基线 fork，而不是复制 starter 文件：需要大量仓库共享同一套初始文件或提示词时，先建一个经审查的基线仓库，再 fork——这样后续对基线的改进可以持续传播，而不是在每份拷贝中各自漂移。
- 仅在协作者共享同一生命周期、需要在同一仓库内协作时使用分支：分支适合「同生命周期协作」，不适合「隔离」。
- 用命名空间分离环境、团队或高频率负载：命名空间是比仓库更高一层的隔离边界，适合承接环境（dev/prod）、团队或吞吐量差异大的工作负载。
这条原则在 README.md 的推荐工作流中再次被强调（one repo per agent / session / user workspace / task，fork from a stable baseline）。
五、REST 配置：命名空间基址与网关 JWT
外部系统接入 Artifacts 时，使用命名空间作用域的基址与网关 JWT：
export ARTIFACTS_NAMESPACE="default" export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>" export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.net/v1/api/namespaces/$ARTIFACTS_NAMESPACE"几点必须注意：
- 基址形态：标准控制面路径为
https://artifacts.cloudflare.net/v1/api/namespaces/<namespace>；部分环境还暴露/edge/v1/api/...基路径。部署到哪个 host、用哪条 base path，务必以你所处 Artifacts 环境的实时文档为准（wrangler types生成的类型、api.md 也反复强调这一点）。 - 认证方式：标准
/v1/api/...路由使用gateway JWT + Bearer认证。 - 凭证管理：通过环境变量或密钥管理器注入，不要把网关 JWT 或仓库令牌硬编码进代码或提交进仓库。
REST 控制面的路由全景（来自 api.md）：
仓库路由
| 路由 | 用途 |
|---|---|
POST /repos | 创建仓库 |
GET /repos | 列出仓库 |
GET /repos/:name | 读取仓库元数据与 remote |
DELETE /repos/:name | 删除仓库 |
POST /repos/:name/fork | Fork 仓库 |
POST /repos/:name/import | 从公开 HTTPS remote 导入 |
创建仓库的 curl 示例：
curl --request POST "$ARTIFACTS_BASE_URL/repos" \ --header "Authorization: Bearer $ARTIFACTS_JWT" \ --header "Content-Type: application/json" \ --data '{"name":"starter-repo"}'导入路由的补充细节：POST /repos/:name/import接受完整的 HTTPS remote URL（如 GitHub、GitLab），并支持branch、depth、read_only等选项；仓库元数据包含描述、默认分支、时间戳以及 Gitremote字段。从既有 HTTPS remote 导入仓库时，应使用 REST API 而非 Workers 绑定——这也是 README.md 的明确建议。
令牌路由
| 路由 | 用途 |
|---|---|
GET /repos/:name/tokens | 列出仓库令牌 |
POST /tokens | 为仓库创建令牌 |
DELETE /tokens/:id | 按 ID 撤销令牌 |
令牌审计与清理类工作流需要列表过滤与按令牌状态分页，具体查询参数形态请从实时文档取回。
六、仓库令牌：控制面与数据面分离
Artifacts 工作流通常涉及两类凭证，二者职责必须分清（configuration.md）：
- 控制面凭证：通过Workers binding或REST API + gateway JWT来创建仓库、铸造令牌、管理命名空间。
- 数据面凭证：仓库作用域令牌（repo-scoped token）只用于针对返回的
remote执行 Git 操作，例如clone、fetch、pull、push。它们不能认证 REST 控制面请求。
推荐的处理策略：
- 铸造最小作用域令牌：只申请你需要的范围——
read或write。read令牌用于克隆、抓取、拉取与索引类工作流；只有需要 push 或修改仓库时才用write令牌。 - 跨系统交接优先用短期令牌：在系统之间传递时使用短生命周期令牌，缩小暴露窗口。
- 及时撤销不再需要的令牌：撤销方式包括绑定方法
revokeToken(tokenOrId)（按 ID 或令牌值撤销）与 REST 路由DELETE /tokens/:id。
仓库句柄上可用的令牌与仓库管理方法（api.md）：
| 方法 | 用途 |
|---|---|
info() | 读取仓库元数据，包括 remote URL |
createToken(scope?, ttl?) | 铸造仓库级 read/write 令牌 |
listTokens() | 查看活跃令牌 |
validateToken(token) | 检查令牌是否仍有效 |
revokeToken(tokenOrId) | 按 ID 或值撤销令牌 |
fork(name, opts?) | 把仓库 fork 成另一个仓库 |
const repo = await env.ARTIFACTS.get("starter-repo"); if (!repo) throw new Error("Repo not found"); const info = await repo.info(); const token = await repo.createToken("read", 3600); const forked = await repo.fork("starter-repo-copy", { defaultBranchOnly: true });在构建长期自动化之前，请到https://developers.cloudflare.com/artifacts/核对当前的令牌行为与认证指引（令牌格式、有效期语义可能随产品演进）。
七、Git 消费者：标准 git-over-HTTPS 客户端接入
只要拿到仓库remote与访问令牌，Artifacts 即可配合标准 git-over-HTTPS 客户端工作。优先使用 header 认证，让完整令牌不进入 remote URL：
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-cloneread令牌支持clone、fetch、pull；git push需要write令牌。- 仅当需要自包含 URL 的短生命周期命令时，才使用把凭据嵌入 URL 的 Basic-auth remote——例如一次性脚本，避免令牌残留在 shell 历史或日志中。
- 对于启动时间比完整克隆更关键的大型仓库，Artifacts 还文档化了ArtifactFS，提供挂载式（mount-style）访问；需要时从实时文档取回当前细节。
八、配置后的检索清单：不要凭记忆依赖任何细节
Artifacts 是一个仍在快速演进的产品面，configuration.md 明确要求在依赖以下任何一点前先核对实时文档：
- 当前的 Workers 绑定方法面（binding surface）
- 确切的令牌格式
- 可用性（availability）与产品状态
- import、fork、令牌管理流程的路由细节
- 你的环境对应的控制面 host 或
/edge/v1base path - 平台限制（limits）与定价
这与 README.md 的阅读顺序建议一致：决定产品选型只看 README；从 Worker 创建/管理仓库按 README → configuration.md → api.md 顺序阅读；外部系统集成直接看 api.md；搭建 agent 或沙箱工作流以 configuration.md 为主；核验精确的认证、路由、限制与定价则一律以https://developers.cloudflare.com/artifacts/的实时文档为第一来源。本仓库 SKILL.md 也持有同样的原则：参考文件只是起点，不是事实来源，当参考文件与文档冲突时，以文档为准。
九、完整配置流程速览
把以上各节串成一个可落地的操作序列：
- 在
wrangler.toml中声明[[artifacts]]binding，绑定到env.ARTIFACTS。 - 运行
npx wrangler types生成类型，以生成的worker-configuration.d.ts为环境类型唯一来源。 - 在
Env接口中引用ARTIFACTS: Artifacts，修改绑定后重跑类型生成。 - 按隔离需求规划命名空间与仓库：每 agent/会话/任务一个仓库，从审查过的基线 fork，跨环境用命名空间隔离。
- 外部系统通过
ARTIFACTS_BASE_URL+ gateway JWT 走 REST 控制面；用read/write仓库令牌走 Git 数据面。 - Git 客户端优先使用
-c http.extraHeader="Authorization: Bearer ..."认证，令牌短期化、最小化、及时撤销。 - 上线前按检索清单核对绑定方法面、令牌格式、路由与限额的当前状态。
更多实现细节可继续查阅本仓库中的 artifacts/api.md（绑定与 REST 路由全表）与 artifacts/README.md（选型与阅读顺序），以及 workers/configuration.md（Worker 类型生成的整体实践）。
【免费下载链接】autoskills
One command. Your entire AI skill stack. Installed.
相关推荐
Open-Sora 2.0 单卡图生视频实战指南：从 0 开始把一张图变成 5 秒视频
Open Sora 2.0 单卡图生视频实战指南：从 0 开始把一张图变成 5 秒视频 手上有一张静态图，想让它动起来变成一段 5 秒视频，又不想按调用付费去调
人工智能大模型媒体生成音视频预训练分布式训练Cloudflare Browser Rendering API 实战指南：REST 接口与 Workers 绑定（Puppeteer/Playwright）全解析
Cloudflare Browser Rendering API 实战指南：REST 接口与 Workers 绑定（Puppeteer/Playwright）全
人工智能AI 技能AI 插件Cloudflare Workers 完整配置指南：wrangler.jsonc 绑定、环境与 TypeScript 实战
Cloudflare Workers 完整配置指南：wrangler.jsonc 绑定、环境与 TypeScript 实战 本文以 Cloudflare Wor
人工智能AI 技能AI 插件
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
