Deploy Hooks

默认情况下，Workers Builds 在你向已连接的 Git 仓库推送提交时触发构建。Deploy Hooks 提供了另一种触发构建的方式。每个 hook 是一个唯一的 URL，在收到 HTTP POST 请求时为某个分支触发手动构建。使用 Deploy Hooks 将 Workers Builds 与工作流连接，例如：

无头 CMS 中内容更改时自动重新构建
使用外部 cron 服务按计划构建
根据特定条件从自定义 CI/CD 流水线触发部署

创建 Deploy Hook

创建 Deploy Hook 之前，请确保 Worker 已连接到 Git 仓库。

前往 Workers & Pages 并选择 Worker。
Go to Workers & Pages ↗
前往 Settings（设置） > Builds（构建） > Deploy Hooks（部署挂钩）。
输入名称并选择要构建的分支。
选择 Create（创建） 并复制生成的 URL。

触发 Deploy Hook

向 Deploy Hook URL 发送 HTTP POST 请求以启动构建：

curl -X POST "https://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/<DEPLOY_HOOK_ID>"

无需 Authorization 头。嵌入 URL 中的唯一标识符充当身份验证凭证。

示例响应：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "branch": "main",
    "worker": "my-worker"
  }
}

响应中的 build_uuid 可用于监控构建状态并检索日志。

验证构建

触发 Deploy Hook 后，你可以从仪表板验证：

在 Deploy Hooks（部署挂钩） 列表中，hook 显示上次触发时间。
在 Worker 的构建历史中，Triggered by（触发者） 列使用 hook 名称和 deploy hook 标签标识由 Deploy Hook 启动的构建。

如果需要以编程方式检查这些构建，请使用 Builds API 参考中的列出 Worker 的构建。由 hook 触发的构建记录为 build_trigger_source: "deploy_hook"。

CMS 集成

大多数无头 CMS 平台支持 webhooks，在内容更改时调用 Deploy Hook URL。各平台的通用设置相同：

在 CMS 中找到 webhooks 或集成设置。
创建新 webhook 并将 Deploy Hook URL 粘贴为目标 URL。
选择应触发 webhook 的事件（例如发布、取消发布或更新）。

请参阅 CMS 文档了解特定平台的说明。支持 webhook 的常用平台包括 Contentful、Sanity、Strapi、Storyblok、DatoCMS 和 Prismic。

幂等性

如果在前一个构建完全启动之前再次触发相同的 Deploy Hook，Workers Builds 不会创建重复构建。相反，它会返回已在进行中的构建。

如果外部系统快速连续发送相同的 Deploy Hook：

第一个请求创建构建。
如果第二个请求在该构建仍处于 queued 或 initializing 状态时到达，则不会创建第二个构建。
相反，响应返回现有的 build_uuid 并将 already_exists 设置为 true。

返回现有待处理构建时的示例响应：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "created_on": "2026-01-21T18:50:00Z",
    "already_exists": true
  }
}

一旦较早的构建超过 initializing 阶段，后续的 POST 将正常创建新构建。这使得 Deploy Hooks 可以安全地用于重试 webhook 或发出内容更新事件突发的系统。

示例

从 Slack 斜杠命令部署

接收 Slack /deploy 命令并触发构建的 Worker：

export default {
	async fetch(request, env) {
		const body = await request.formData();
		const command = body.get("command");
		const token = body.get("token");

		if (token !== env.SLACK_VERIFICATION_TOKEN) {
			return new Response("Unauthorized", { status: 401 });
		}

		if (command === "/deploy") {
			const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
			const { result } = await res.json();
			return new Response(`Build started: ${result.build_uuid}`);
		}

		return new Response("Unknown command", { status: 400 });
	},
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.formData();
    const command = body.get("command");
    const token = body.get("token");

    if (token !== env.SLACK_VERIFICATION_TOKEN) {
      return new Response("Unauthorized", { status: 401 });
    }

    if (command === "/deploy") {
      const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
      const { result } = await res.json<{ result: { build_uuid: string } }>();
      return new Response(`Build started: ${result.build_uuid}`);
    }

    return new Response("Unknown command", { status: 400 });
  },
};

按计划重新构建

带有 Cron Trigger 的 Worker，每小时重新构建：

export default {
	async scheduled(event, env) {
		await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
	},
};

export default {
  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
    await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
  },
};

安全注意事项

将 Deploy Hook URL 存储在环境变量或密钥管理器中，切勿存储在源代码或公共配置文件中。
将 URL 访问权限限制为仅需要的系统。
如果 URL 泄露或怀疑未经授权使用，请立即删除 Deploy Hook 并创建新的。旧 URL 在删除后立即失效。

使用 Builds API 进行身份验证触发

如果你的外部系统支持自定义头，可以使用 Authorization 头中的 API 令牌调用手动构建端点。这为你提供基于令牌的身份验证以及按请求选择分支的能力。有关分步演练，请参阅触发手动构建。

限制

Deploy Hooks 的速率限制为每个 Worker 每分钟 10 次构建，每个账户每分钟 100 次构建。有关所有 Workers Builds 限制，请参阅限制与定价。