将 Git 仓库连接到 Worker 时,可以自定义构建和部署 Worker 所需的配置。
当提交推送到已连接的仓库时,Workers Builds 运行两步流程:
- Build command(构建命令) (optional) - 编译项目(例如 Next.js 或 Astro 等框架的
npm run build) - Deploy command(部署命令) - 将 Worker 部署到 Cloudflare(默认为
npx wrangler deploy)
对于 Preview 构建,会改为运行 Preview command(预览命令)(默认为 npx wrangler preview),该命令创建或更新 Preview 而不将其提升为生产版本。
构建设置可在 Worker 内的 Settings(设置) > Build(构建) 中找到。
请注意,更新并保存构建设置后,更新的设置将应用于_下一次_构建。当你_重试_构建时,将应用重试构建时存在的构建配置。
| Setting | Description |
|---|---|
| Git account(Git 账户) | 选择要使用的 Git 账户。初始连接后,你可以继续使用此 Git 账户进行未来的项目。 |
| Git repository(Git 仓库) | 选择要连接到 Worker 的 Git 仓库。 |
| Git branch(Git 分支) | 选择希望 Cloudflare 监听新提交的分支。默认为 main。 |
| Build command(构建命令) (Optional) | 如果项目需要构建步骤,请设置构建命令(例如 npm run build)。例如,使用 Next.js 或 Remix 等前端框架 时需要此设置。 |
| Deploy command | 部署命令允许你设置用于部署 Worker 的特定 Wrangler 命令。部署命令默认为 npx wrangler deploy,但你可以自定义此命令。Workers Builds 将使用 package.json 中设置的 Wrangler 版本。 |
| Preview command | 设置用于 Preview 构建 的命令。默认为 npx wrangler preview。Workers Builds 将使用 package.json 中设置的 Wrangler 版本。 |
| Root directory(根目录) (Optional) | 指定项目路径。根目录定义构建命令运行的位置,在 monorepo 中有助于隔离仓库中的特定项目进行构建。 |
| API token (Optional) | API 令牌用于验证构建请求并授权 Worker 的上传和部署到 Cloudflare。默认情况下,使用 Workers Builds 时 Cloudflare 会自动为你的账户生成 API 令牌,并在所有后续构建中继续使用此 API 令牌。或者,你可以创建自己的 API 令牌,或选择已有的令牌。 |
| Build variables and secrets(构建变量和密钥) (Optional) | 添加仅构建时可访问的环境变量和密钥。构建变量在运行时将不可访问。如果要配置运行时变量,可以在 Settings(设置) > Variables & Secrets(变量和密钥) 中进行 |
你可以使用选择的包管理器运行部署命令。
如果你在 package.json 中将 Wrangler 部署命令添加为脚本,可以通过将其设置为部署命令来运行它。例如 npm run deploy。
你可以设置的其他部署命令示例包括:
| Example Command | Description |
|---|---|
npx wrangler deploy --assets ./public/ |
部署 Worker 以及指定目录中的静态资源。或者,你可以使用 assets 绑定(binding)。 |
npx wrangler deploy --env staging |
如果你有 Wrangler environment Worker,应使用环境标志设置部署命令。更多详情,请参阅高级设置。 |
npx wrangler deploy --containers-rollout=immediate |
此次部署的 Containers rollout 模式。请参阅 Rollouts。 |
npx wrangler deploy --containers-rollout=none |
仅部署 Worker。跳过容器镜像构建/推送和实例 rollout。 |
当你启用了 Preview 构建 时运行 Preview command。Preview 构建针对非生产分支运行。
它默认为 npx wrangler preview,会创建或更新 Preview 并生成 Preview URL。与构建和部署命令一样,可以自定义。
如果将此命令改为 npx wrangler versions upload,构建会创建 Worker 版本和 Version URL,而不是 Preview。Version URLs 使用为该 Worker 版本配置的资源,不会创建分支隔离资源。
你可以设置的其他 Preview command 示例包括:
| Example Command | Description |
|---|---|
yarn exec wrangler preview |
你可以自定义用于运行 Wrangler 的包管理器。 |
npx wrangler preview --env staging |
如果你有 Wrangler environment Worker,应使用环境标志设置 Preview command。更多详情,请参阅高级设置。 |
要配置 Preview 使用的变量、密钥和绑定(binding),请参阅 Preview 设置。
如果你的仓库没有 Wrangler 配置文件,部署命令(wrangler deploy)将触发自动项目配置。这会检测你的框架,创建必要的配置,并打开拉取请求供你审查。合并 PR 后,项目即已配置,后续构建将正常部署。
对于新的 Workers Builds 项目,Preview 构建默认使用 wrangler preview,并可以使用 Preview 设置 配置 Preview 专用绑定、变量、密钥和资源。
Workers Builds 中的 API 令牌定义授予 Workers Builds 与账户资源交互的访问权限。目前仅支持用户令牌,账户拥有的令牌支持即将推出。
选择 Create new token(创建新令牌) 时,将自动创建具有以下权限的新 API 令牌:
- Account: Account Settings (read), Workers Scripts (edit), Workers KV Storage (edit), Workers R2 Storage (edit)
- Zone: Workers Routes (edit),适用于账户中的所有 zone
- User: User Details (read), Memberships (read)
你可以通过导航到 My Profile(我的个人资料) > API Tokens(API 令牌) 来配置此 API 令牌的权限。
建议在所有 Worker 的上传和部署中始终使用相同的 API 令牌,以保持一致访问权限。
静态资源和框架现已在 Cloudflare Worker 中受支持。在框架指南中学习设置 Worker 项目和每个框架的命令:
你可以为构建提供自定义环境变量。
要通过仪表板添加环境变量:
- 在 Cloudflare 仪表板中,前往 Workers & Pages 页面。
- 在 Overview(概览) 中,选择 Worker。
- 选择 Settings(设置) > Environment variables(环境变量)。
要使用 Wrangler 添加环境变量,在 Wrangler 文件中通过 [vars] 配置定义文本和 JSON。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker-dev",
"vars": {
"API_HOST": "example.com",
"API_ACCOUNT_ID": "example_user",
"SERVICE_X_DATA": {
"URL": "service-x-api.dev.example",
"MY_ID": 123
}
}
}"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"
[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"
[vars.SERVICE_X_DATA]
URL = "service-x-api.dev.example"
MY_ID = 123以下系统环境变量默认注入(但可以覆盖):
| 环境变量 | 注入的值 | 示例用例 |
|---|---|---|
CI |
true |
在 CI 上运行时与本地运行时更改构建行为 |
WORKERS_CI |
1 |
在 Workers Builds 上运行时与本地运行时更改构建行为 |
WORKERS_CI_BUILD_UUID |
<build-uuid-of-current-build> |
将 Build UUID 传递给自定义工作流 |
WORKERS_CI_COMMIT_SHA |
<sha1-hash-of-current-commit> |
将当前提交 ID 传递给错误报告,例如 Sentry |
WORKERS_CI_BRANCH |
<branch-name-from-push-event |
根据分支自定义构建,例如在 production 上禁用调试日志 |