本指南介绍如何使用 Workers Builds REST API 将 Worker 连接到 Git 仓库、管理构建设置和预览,以及监控构建。示例使用可直接在终端中运行或改写为您偏好的编程语言的 curl 命令。部分示例通过管道将输出传递给 jq ↗,以筛选 JSON 响应。
Builds API 需要用户范围的 API 令牌。不支持账户范围的令牌,使用此类令牌会返回“Invalid token”错误。
在 dash.cloudflare.com/profile/api-tokens ↗ 创建具有以下权限的令牌:
| 权限 | 访问级别 | 需要此权限的原因 |
|---|---|---|
| Workers Builds Configuration | 编辑 | 管理构建设置和预览,以及处理构建 |
| Workers Scripts | 读取 | 仅在获取 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 连接到仓库,并为生产分支和预览设置构建配置。
-
安装 Cloudflare GitHub App。 在 Cloudflare 仪表板 ↗中,转到 Workers & Pages,选择任意 Worker,然后转到 Settings > Builds > Connect。选择 GitHub,并授权该应用访问您的账户或组织。您只需执行一次此操作。
-
获取 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' -
获取构建令牌 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- Workers Builds REST API 参考 - 完整的端点文档
- 构建配置 - 构建设置和选项
- 预览 - Worker 的分支隔离预览
- Deploy Hooks - 从外部系统启动构建
- 构建故障排除 - 常见的 Builds API 错误