Gatsby Cloud 构建与预览 Webhooks 使用指南：触发生产构建、指定数据源与清除缓存

Gatsby Cloud 构建与预览 Webhooks 使用指南触发生产构建、指定数据源与清除缓存【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文围绕 Gatsby 仓库中 build-and-preview-webhooks.md 这一官方参考文档展开系统讲解 Gatsby Cloud 为每个站点提供的Build Webhook构建 Webhook与Preview Webhook预览 Webhook的区别、调用方式、校验方法与高级用法指定数据源、清除缓存。读完本文你将掌握如何用curl、Postman、Zapier 等任意工具向 Gatsby Cloud 发送POST请求触发构建并能借助 HTTP 头精确控制刷新范围与缓存行为从而把构建流程无缝接入自己的自动化体系。背景Gatsby Cloud 中的构建与预览在深入 Webhook 之前先明确其作用对象。根据仓库中的 what-is-gatsby-cloud.md 说明build 是对站点源代码进行编译后产生的一个站点版本而 preview 是开发阶段用于预览最终效果的一种特殊构建。Gatsby Cloud 将构建与预览细分为三类Production Builds生产构建针对生产分支的构建适合部署上线Pull Request BuildsPR 构建针对非生产分支PR 分支的构建用于合并前评估代码变更的影响CMS PreviewsCMS 预览连接 CMS 后用于实时查看内容变更的开发构建。Webhook 正是连接外部事件CMS 内容更新、CI 流程、自动化脚本与上述构建/预览的关键桥梁。每个站点都有两个 WebhookGatsby Cloud 会为每个站点提供两个 WebhookWebhook触发目标典型场景Build Webhook触发一次 Production Build生产构建代码变更后重建生产站点Preview Webhook触发一次 CMS Preview 构建CMS 内容保存/发布后刷新预览获取方式非常简单进入站点的Site Settings站点设置在侧边栏菜单中选择General Webhook即可看到两个 Webhook 的 URL 及复制按钮。下图展示了 Gatsby Cloud 控制台中的 Webhook 设置界面其中Preview Webhook与Builds Webhook两个 URL 均可一键复制当你把内容管理系统CMS连接到站点时无论是手动配置还是通过Quick ConnectCMS 正是使用这两个 Webhook 来触发构建的。仓库中的 quick-connect.md 也印证了这一点Quick Connect 在授权完成后会自动为你的 CMS 配置好 webhooks、环境变量以及适用场景下的预览扩展。用任意工具触发 WebhookWebhook 本质上就是一个 HTTP 端点因此任何能发送 HTTPPOST请求的工具Postman、Zapier、CI 脚本、编程语言 HTTP 客户端等都可以触发它。以curl为例向某站点的 Preview Webhook 发送请求的结构如下curl -X POST https://webhook.gatsbyjs.com/hooks/data_source/site id其中site id是站点的唯一标识符可从 Webhook 设置页面复制得到完整的 URL。Build Webhook 的调用方式与之相同只是 URL 指向生产构建端点。实践提示请求方法必须为POSTGET等其它方法不会触发构建无需鉴权请求体基础触发场景下URL 本身即携带站点标识直接发送空请求体即可可组合自动化例如在 Zapier 中监听表单提交或数据库记录变化成功后向 Webhook URL 发POST请求即可实现数据一变、站点即重建的无服务器自动化链路。如何确认 Webhook 是否生效触发请求发出后判断是否成功生效的方式是检查构建卡片build card若构建由Build Webhook触发构建卡片会显示Triggered by Gatsby Build Webhook由 Gatsby 构建 Webhook 触发字样若构建由官方支持的 CMS 集成触发即 CMS 侧的 Webhook 机制构建卡片则会显示该 CMS 的名称例如下图中的 WordPress因此通过构建卡片上的触发来源标识你可以快速区分是手动 Webhook 触发还是CMS 自动集成触发从而排查自动化链路是否按预期工作。指定数据源x-gatsby-cloud-data-source 请求头默认情况下Webhook 触发的是全量刷新。但如果你希望精确控制本次要刷新的数据源可以在请求中携带x-gatsby-cloud-data-sourceHTTP 头。例如假设你的 source plugin 名为gatsby-source-awesome则在 Webhook 请求中加入如下请求头curl -X POST https://webhook.gatsbyjs.com/hooks/data_source/site id \ --header x-gatsby-cloud-data-source: gatsby-source-awesome注意事项请求头的值必须包含 gatsby-source 字样才会被视为合法的数据源名称该机制的价值在于多数据源站点如同时接入 CMS 与数据库可以只刷新指定来源避免无关数据源的内容导致不必要的重建开销。这一设计与 Gatsby 的插件体系一脉相承站点内安装的gatsby-source-*系列 source plugin可参考仓库 packages 目录下的 gatsby-source-filesystem、gatsby-source-contentful、gatsby-source-wordpress 等各自负责从对应数据源拉取内容而 Webhook 头的存在让云端构建可以按需只刷新其中一个。清除缓存后构建x-gatsby-cache 与 x-runner-type有时你需要在构建前清除缓存例如怀疑缓存导致内容未更新或需要强制冷构建。此时不再使用data_source端点而是向构建触发端点发送POST请求并携带x-gatsby-cache: false头curl -X POST https://webhook.gatsbyjs.com/hooks/builds/trigger/site id --header x-gatsby-cache: false该请求会触发一次无缓存no cache的构建。如果你希望在预览场景下也清除缓存则需要额外追加一个头x-runner-type: PREVIEWcurl -X POST https://webhook.gatsbyjs.com/hooks/builds/trigger/site id \ --header x-gatsby-cache: false \ --header x-runner-type: PREVIEW参数速查表HTTP 头取值作用x-gatsby-cloud-data-source含gatsby-source字样的数据源名指定本次刷新的数据源x-gatsby-cachefalse触发无缓存构建清除缓存后构建x-runner-typePREVIEW将构建类型指定为预览构建配合缓存清除使用在完整构建生态中的位置Webhook 是自动化的核心入口Webhook 并非孤立功能它是 Gatsby Cloud 构建触发事件体系的核心入口之一。结合仓库文档可以梳理出构建/预览被触发的完整事件链根据 production-builds-and-pull-request-builds.md生产构建可能在以下情况被触发创建新站点、向生产分支推送提交或合并 PR、点击控制台的Trigger Build按钮、向 Build Webhook 发送POST请求、连接 CMS 后收到数据更新取决于配置、或修改环境变量与托管配置根据 cms-previews.mdCMS Preview 构建可能在以下情况被触发CMS 内容变化如输入时的自动保存、保存或发布操作、向生产分支提交 Git 提交、手动点击Trigger Build/Restart Preview按钮、或向 Preview Webhook 发送POST请求。可见Build Webhook 与 Preview Webhook 分别对应生产构建与 CMS 预览两条触发链路的程序化入口让外部系统CMS、CI、自动化平台得以与云端构建无缝衔接。面向 source plugin 开发者的延伸Content Sync 中的 Webhook 角色如果你正在开发自定义 source plugin仓库中的 创建 source plugin 教程 Part 7 展示了 Preview Webhook 在Content Sync特性中的具体用法从 Gatsby Cloud 站点设置页面即上文所述 Webhook 设置处可获取两个 URLPreview Webhook URL格式https://webhook.gatsbyjs.com/hooks/data_source/id与Content Sync URL格式https://gatsbyjs.com/content-sync/siteIdCMS 扩展extension需要在内容变更后向 Preview Webhook URL 发送POST请求以触发预览构建并将用户引导至 Content Sync 等待页面该教程特别强调必须确保内容编辑后无论点击 Open Preview 按钮之前或之后Preview Webhook 都会被发送到 Gatsby Cloud这是预览能实时反映内容变更的前提。这进一步说明无论使用官方 CMS 集成自动配置 Webhook还是自研插件/CMS 扩展手动发送 Webhook 请求Webhook 都是驱动内容变更 → 预览/构建这条自动化链路的通用协议。总结本文完整覆盖了 Gatsby Cloud 构建与预览 Webhooks 的全部核心用法两个 WebhookBuild Webhook 触发生产构建Preview Webhook 触发 CMS 预览构建均可在 Site Settings General Webhook 中找到并复制触发方式用curl、Postman、Zapier 等任意工具向https://webhook.gatsbyjs.com/hooks/data_source/site id发送POST请求即可生效验证通过构建卡片上的触发来源标识Triggered by Gatsby Build Webhook 或对应 CMS 名称确认是否成功精确控制用x-gatsby-cloud-data-source头指定刷新数据源用x-gatsby-cache: false清除缓存构建配合x-runner-type: PREVIEW将其应用于预览场景。借助这些能力你可以将 Gatsby Cloud 的构建与预览流程无缝嵌入任何自动化体系实现内容即改即见、发布即重建的高效工作流。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考