跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

Workers

最后更新 查看 MarkdownAgent 设置

从 Worker 创建 Artifacts 存储库，并使用标准 Git 客户端推送和拉取内容。

在本指南结束时，您将创建一个 Worker，将其绑定（bind）到 Artifacts，通过 Workers 绑定（binding）创建一个存储库，推送一次提交，然后使用标准 Git 客户端将同一个存储库克隆回来。

首先阅读命名空间，然后选择您要使用的命名空间名称。本指南在示例中使用 default。

前提条件

  1. 注册 Cloudflare 账户 ↗。
  2. 安装 Node.js ↗。

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

您还需要：

  • 已安装 Wrangler。如果您在本指南中运行本地 Wrangler 命令，请先对 Wrangler 进行身份验证。关于本地 OAuth 身份验证或 CI 设置，请参阅 wrangler login 和 在 CI/CD 中运行 Wrangler。
  • 您的 Cloudflare 账户中拥有 Artifacts 的访问权限。
  • 命名空间名称，例如 default。
  • 本地 git 客户端。
  • jq（如果您想自动提取响应字段）。

1. 创建 Worker 项目

  1. 使用 C3 创建一个新的 Worker 项目：

    npm create cloudflare@latest -- artifacts-worker

    进行设置时，请选择以下选项：

    • 对于 What would you like to start with?，选择 Hello World example。
    • 对于 Which template would you like to use?，选择 Worker only。
    • 对于 Which language do you want to use?，选择 TypeScript。
    • 对于 Do you want to use git for version control?，选择 Yes。
    • 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

  2. 进入项目目录：

    cd artifacts-worker

2. 添加 Artifacts 绑定（binding）

打开您的 Wrangler 配置文件并添加 Artifacts 绑定（binding）：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "artifacts-worker",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-08-17",
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "default"
    }
  ]
}
name = "artifacts-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"
# 如果您希望 Wrangler 在本地开发中使用远程 Artifacts 服务，请设置 remote = true。

这会在您的 Worker 内部将 Artifacts 暴露为 env.ARTIFACTS。

如果您使用的是 TypeScript，请重新生成本地绑定（binding）类型：

npx wrangler types

Wrangler 会将 Artifacts 类型添加到您生成的 worker-configuration.d.ts file。

3. 编写您的 Worker

将 src/index.ts 替换为以下代码：

src/index.jsjs
export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (request.method === "POST" && url.pathname === "/repos") {
			// Read the repo name from the request body so the route is reusable.
			const body = await request.json().catch(() => ({}));

			const repoName = body.name ?? "starter-repo";

			// Create the repo and return the remote URL plus initial write token.
			const created = await env.ARTIFACTS.create(repoName);

			return Response.json({
				name: created.name,
				remote: created.remote,
				token: created.token,
			});
		}

		return new Response("Use POST /repos to create an Artifacts repo.", {
			status: 405,
			headers: { Allow: "POST" },
		});
	},
};
src/index.tsts
export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (request.method === "POST" && url.pathname === "/repos") {
			// Read the repo name from the request body so the route is reusable.
			const body = await request.json().catch(() => ({}));

			const repoName = body.name ?? "starter-repo";

			// Create the repo and return the remote URL plus initial write token.
			const created = await env.ARTIFACTS.create(repoName);

			return Response.json({
				name: created.name,
				remote: created.remote,
				token: created.token,
			});
		}

		return new Response("Use POST /repos to create an Artifacts repo.", {
			status: 405,
			headers: { Allow: "POST" },
		});
	},
};

此 Worker 将创建 Artifacts 存储库，并返回您的 Git 客户端推送和拉取所需的远程 URL 和令牌。

对于演示，Worker 返回初始的写入令牌。在生产环境中，请为克隆（clone）和拉取（pull）流程生成短期读取令牌，并仅为需要推送（push）访问权限的操作生成写入令牌。

4. 调用您的 Worker 来创建存储库

启动本地开发：

npx wrangler dev

然后，打开第二个终端并向您的 Worker 发送请求以创建新的 Artifacts 存储库：

curl http://localhost:8787/repos \
  --header "Content-Type: application/json" \
  --data '{
    "name": "starter-repo"
  }'

您的 Worker 将调用 env.ARTIFACTS.create() 并返回您在 Git 操作中需要的三个值：

{
	"name": "starter-repo",
	"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git",
	"token": "art_v1_0123456789abcdef0123456789abcdef01234567?expires=1760000000"
}
  • name：存储库名称。在命名空间内必须是唯一的。
  • remote：此存储库的 Git 远程 URL。<ACCOUNT_ID> 将是您实际的 Cloudflare 账户 ID。
  • token：用于 Git 操作的短期凭证。该令牌将其过期时间以 Unix 时间戳形式直接编码在 ?expires= 后缀中。

将 remote 和 token 值复制到本地 shell 变量中：

export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_RESPONSE>"
export ARTIFACTS_TOKEN="<PASTE_TOKEN_FROM_RESPONSE>"
RESPONSE=$(curl --silent http://localhost:8787/repos \
  --header "Content-Type: application/json" \
  --data '{"name":"starter-repo"}')

export ARTIFACTS_REMOTE=$(printf '%s' "$RESPONSE" | jq -r '.remote')
export ARTIFACTS_TOKEN=$(printf '%s' "$RESPONSE" | jq -r '.token')

5. 使用 git 推送您的第一次提交

在上一步中，您的 Worker 创建了一个空的 Artifacts 存储库。现在，您将创建一个本地 Git 存储库，添加一个文件，并将其推送到 Artifacts —— 就像您推送到任何 Git 远程端一样。

mkdir artifacts-demo
cd artifacts-demo
git init -b main
printf '# Artifacts demo\n' > README.md
git add README.md
git commit -m "Initial commit"
git remote add origin "$ARTIFACTS_REMOTE"
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin main

-c http.extraHeader 标志将令牌作为请求标头传递，从而使其保持在您的 Git 配置和 shell 历史记录之外。

如果您在运行短期命令时需要包含身份验证信息的完整远程 URL，请改用令牌密钥（token secret）构建一个：

export ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}"
export ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}"
git push "$ARTIFACTS_AUTH_REMOTE" HEAD:main

6. 使用常规 Git 客户端拉取存储库

将同一个存储库克隆到第二个目录中：

cd ..
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
git -C artifacts-clone log --oneline -1

您应该会看到您在上一步中推送的提交。

您也可以在运行短期命令时使用包含身份验证信息的完整远程 URL 进行克隆：

git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone

7. 部署您的 Worker

切换回您的 Worker 项目目录：

cd artifacts-worker

部署 Worker，以便您无需运行 wrangler dev 即可创建存储库：

npx wrangler deploy

Wrangler 会打印您的 workers.dev URL。对该 URL 发送相同的 curl 请求即可在生产环境中创建其他存储库。

后续步骤

最佳实践

有效地使用存储库隔离、最小权限令牌和命名空间隔离。

Git 协议

使用基于 URL 身份验证或 http.extraHeader 的标准 git-over-HTTPS 远程端。

这篇文档对您有帮助吗？