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

Builds API 参考

最后更新 查看 MarkdownAgent 设置

本指南介绍如何使用 Workers Builds REST API 将 Worker 连接到 Git 仓库、管理构建设置和预览,以及监控构建。示例使用可直接在终端中运行或改写为您偏好的编程语言的 curl 命令。部分示例通过管道将输出传递给 jq ↗,以筛选 JSON 响应。

开始之前

创建 API 令牌

Builds API 需要用户范围的 API 令牌。不支持账户范围的令牌,使用此类令牌会返回“Invalid token”错误。

在 dash.cloudflare.com/profile/api-tokens ↗ 创建具有以下权限的令牌:

权限 访问级别 需要此权限的原因
Workers Builds Configuration 编辑 管理构建设置和预览,以及处理构建
Workers Scripts 读取 仅在获取 Worker 标记时需要

获取 Worker 标记

Builds API 通过 Worker 的标记(由 Cloudflare 分配且不可变的 ID)而不是名称来识别 Worker。在 API 请求和响应中,此值显示为 script_tag。

要查找 Worker 的标记,请调用 Workers Scripts API:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'
{
    "name": "my-worker",
    "tag": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
}

将 Worker 连接到仓库

只需一个请求,即可将 Worker 连接到仓库,并为生产分支和预览设置构建配置。

前提条件

  1. 安装 Cloudflare GitHub App。 在 Cloudflare 仪表板 ↗中,转到 Workers & Pages,选择任意 Worker,然后转到 Settings > Builds > Connect。选择 GitHub,并授权该应用访问您的账户或组织。您只需执行一次此操作。

  2. 获取 GitHub 账户和仓库 ID:

    curl -s "https://api.github.com/users/<GITHUB_USERNAME>" | jq '.id'
    curl -s "https://api.github.com/repos/<GITHUB_USERNAME>/<REPO_NAME>" | jq '.id'
  3. 获取构建令牌 UUID。 在 Worker 的 Settings > Builds > API token 中选择或创建构建令牌,或者使用 GET /builds/tokens 端点列出构建令牌:

    curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" \
      --header "Authorization: Bearer <API_TOKEN>" \
      | jq '.result[] | {build_token_uuid, build_token_name}'

创建构建配置

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "script_tag": "<WORKER_TAG>",
    "git_repository": {
      "provider_type": "github",
      "provider_account_id": "<GITHUB_USER_ID>",
      "provider_account_name": "<GITHUB_USERNAME>",
      "repo_id": "<GITHUB_REPO_ID>",
      "repo_name": "<REPO_NAME>",
      "branch": "main"
    },
    "production_settings": {
      "build_command": "npm run build",
      "deploy_command": "npx wrangler deploy",
      "build_token_uuid": "<BUILD_TOKEN_UUID>",
      "environment_variables": {
        "NODE_ENV": {"value": "production", "is_secret": false}
      }
    },
    "previews_enabled": true,
    "previews_base_config": {
      "build_command": "npm run build",
      "deploy_command": "npx wrangler preview",
      "build_token_uuid": "<BUILD_TOKEN_UUID>",
      "environment_variables": {
        "NODE_ENV": {"value": "development", "is_secret": false}
      }
    }
  }'

现在,推送到 main 会使用 wrangler deploy 部署 Worker。推送到其他任何分支则使用 wrangler preview 创建或更新预览,而不会影响实时部署。若要在不启用预览的情况下连接 Worker,请将 previews_enabled 设置为 false。

字段 说明
git_repository 要连接的仓库。branch 是您的生产分支。
production_settings 推送到生产分支时使用的构建设置
previews_enabled 推送到其他分支时是否创建或更新预览
previews_base_config 复制到每个新预览的构建设置。deploy_command 是您的预览命令。

production_settings 和 previews_base_config 接受相同的字段:

字段 类型 说明
build_command 字符串 构建项目的命令(例如 npm run build)
deploy_command 字符串 部署 Worker 的命令(例如 npx wrangler deploy 或 npx wrangler preview)
build_token_uuid 字符串 用于部署 Worker 的构建令牌 UUID
root_directory 字符串 项目相对于仓库根目录的路径。默认为 /。
path_includes 数组 会启动构建的文件路径模式
path_excludes 数组 不会启动构建的文件路径模式
build_caching_enabled boolean 构建是否复用缓存的依赖项和构建产物。默认为 true。
environment_variables object 构建时变量。将 is_secret 设置为 true 可在构建日志中隐藏值。

查看和更新构建设置

获取构建设置

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}" \
  --header "Authorization: Bearer <API_TOKEN>"

响应包含您在创建构建配置时设置的相同 git_repository、production_settings、previews_enabled 和 previews_base_config 字段。

更新构建设置

仅发送要更改的字段。例如,要更改生产构建命令并添加预览构建变量:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "production_settings": {
      "build_command": "npm run build:prod"
    },
    "previews_base_config": {
      "environment_variables": {
        "API_URL": {"value": "https://staging.example.com", "is_secret": false},
        "OLD_VARIABLE": null
      }
    }
  }'
  • 要删除环境变量,请将其设置为 null。
  • 要更改生产分支,请发送 {"git_repository": {"branch": "<BRANCH_NAME>"}}。
  • 要开启或关闭预览,请发送 {"previews_enabled": true} 或 {"previews_enabled": false}。
  • 对 previews_base_config 的更改适用于之后创建的预览。若还要更新所有现有预览,请在 URL 中添加 ?patch_existing_previews=true。

管理预览

启用预览后,首次推送到非生产分支时会为该分支创建预览。每个预览都会获得自己的 previews_base_config 副本。

列出预览

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {preview_id, branch, auto_build, auto_delete}'
字段 说明
preview_id 预览的标识符
branch 预览跟踪的 Git 分支
auto_build 推送到该分支时是否构建此预览。无论此设置如何,手动构建和 Deploy Hooks 都会运行。
auto_delete 删除 Git 分支时是否也删除此预览

要获取单个预览及其构建设置,请向 /builds/workers/{worker_tag}/previews/{preview_id} 发送 GET 请求。

更新预览

仅发送要更改的字段。例如,要停止通过推送构建预览并更改其构建命令:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews/{preview_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "auto_build": false,
    "settings": {
      "build_command": "npm run build:preview"
    }
  }'

构建预览

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews/{preview_id}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "feature-branch"}'

要列出预览的构建,请向同一 URL 发送 GET 请求。

使用构建

启动生产构建

要在不推送提交的情况下启动生产构建,请为生产分支创建 Deploy Hook,并向其 URL 发送 POST 请求。

列出构建

使用 GET /builds/workers/{worker_tag}/builds 端点:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_uuid, status, build_outcome, branch: .build_trigger_metadata.branch, created_on}'

不会返回超过 90 天的构建。请参阅限制与定价。

获取构建日志

使用 GET /builds/builds/{build_uuid}/logs 端点,并使用列出构建中的 build_uuid:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" \
  --header "Authorization: Bearer <API_TOKEN>"

构建完成后,构建日志会保留 90 天。若要保留更长时间,请保存响应。

取消构建

使用 PUT /builds/builds/{build_uuid}/cancel 端点:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request PUT

相关资源

这篇文档对您有帮助吗?