身份验证 · Cloudflare Artifacts docs

Artifacts 为每个接口使用不同的身份验证路径。请根据您的代码如何访问仓库来选择身份验证方法。

请先阅读命名空间（namespaces），然后在各个接口中一致地使用同一个命名空间名称。

比较身份验证方法

接口	身份验证方式	权限或范围	适用场景
Workers 绑定（binding）	已配置的 `artifacts` 绑定（binding）	Wrangler 身份验证仅用于本地 Wrangler 命令（例如 `dev` 和 `deploy`）。	调用 `env.ARTIFACTS` 的 Worker 代码
REST API	`Authorization: Bearer ...` 中的 Cloudflare API 令牌	只读路由使用 Artifacts > Read，写入路由使用 Artifacts > Edit。	控制面 HTTP 请求
Git 协议	仓库范围的 Artifacts 令牌	`read` 用于 clone、fetch 和 pull。`write` 用于 push。	基于 HTTPS 的标准 Git

Cloudflare API 令牌用于验证控制面访问。仓库范围的 Artifacts 令牌用于验证 Git 访问。

验证 Workers 绑定（binding）

Workers 绑定（binding）使用您在 Wrangler 中配置的 artifacts 绑定（binding）。您的 Worker 代码在调用 env.ARTIFACTS 时不需要传递令牌。

在您的 Wrangler 配置中添加绑定（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"

在运行时，已部署的 Workers 会直接使用配置的绑定（binding）。对于本地 Wrangler 命令（例如 wrangler dev、wrangler deploy 或 wrangler types），请先对 Wrangler 进行身份验证。对于本地 OAuth 身份验证，请参阅 wrangler login。对于 CI 或无头（headless）环境，请参阅在 CI/CD 中运行 Wrangler。

验证 REST API

REST API 在 Authorization 标头中使用 Cloudflare API 令牌。

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

读取仓库元数据：

curl "$ARTIFACTS_BASE_URL/repos/starter-repo" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

创建仓库：

curl --request POST "$ARTIFACTS_BASE_URL/repos" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "starter-repo"
  }'

验证 Git 协议

Git 使用仓库范围的 Artifacts 令牌，而不是 Cloudflare API 令牌。您可以从 Workers 绑定（binding）或 REST API 铸造（mint）这些令牌，然后在仓库的 remote URL 中使用它们。

令牌范围	允许的命令
`read`	`git clone`, `git fetch`, `git pull`
`write`	`git clone`, `git fetch`, `git pull`, `git push`

使用 Workers 绑定（binding）或 REST API 返回的准确仓库 remote 值：

export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_CREATE_OR_GET_RESPONSE>"

使用 read 令牌进行克隆：

git -c http.extraHeader="Authorization: Bearer <YOUR_READ_TOKEN>" clone "$ARTIFACTS_REMOTE" artifacts-clone

使用 write 令牌进行推送：

git -c http.extraHeader="Authorization: Bearer <YOUR_WRITE_TOKEN>" push "$ARTIFACTS_REMOTE" HEAD:main

有关令牌处理和已认证远程仓库的更多信息，请参阅 Git 协议。