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

部署挂钩(Deploy Hooks)

最后更新 查看 MarkdownAgent 设置

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

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

创建 Deploy Hook

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

  1. 前往 Workers & Pages 并选择 Worker。

    前往 Workers & Pages ↗
  2. 前往 Settings(设置) > Builds(构建) > Deploy Hooks(部署挂钩)。

  3. 输入名称 并选择要构建的分支。

  4. 选择 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。各平台的通用设置相同:

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

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

幂等性

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

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

  1. 第一个请求创建构建。
  2. 如果第二个请求在该构建仍处于 queued 或 initializing 状态时到达,则不会创建第二个构建。
  3. 相反,响应返回现有的 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 限制,请参阅限制与定价。

这篇文档对您有帮助吗?