Gatsby CMS Previews 完整指南在 Gatsby Cloud 中配置与使用 CMS 内容实时预览【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsbyCMS Previews 是 Gatsby Cloud 提供的核心协作能力它把“内容编辑 → 站点构建 → 页面更新”的链路压缩到近乎实时让内容编辑人员无需离开 CMS、也无需等待完整生产构建就能看到自己在 CMS 中保存的改动如何呈现在 Gatsby 站点页面上。本文基于 cms-previews.md 官方文档结合本仓库中gatsby-source-wordpress、gatsby-source-datocms等源码插件的实现细节系统讲解 CMS Previews 的触发机制、增量预览与旧版预览两种构建模式、支持的 CMS 与插件版本要求、预览扩展Preview Extensions的可用范围以及禁用预览的正确方式。读完本文你将能判断自己的站点与 CMS 组合适合哪种预览方案知道如何配置环境变量与 Webhook并能从源码层面理解“预览状态回传”这一关键闭环是如何实现的。什么是 CMS Preview在 Gatsby Cloud 中当你添加一个站点后可以在站点概览Site Overview的CMS Preview标签页下找到 CMS Previews 功能。从本质上说一个 CMS Preview 就是你的站点的一个开发构建development build你在 CMS 中修改内容输入、保存或发布改动会实时反映到这个预览站点上供内容编辑者、审阅者与开发者共同查看和协作。使用 CMS Previews 有一个前置条件你的站点必须已连接到一个受支持的 CMS。官方支持的 CMS 集成分为两类支持 Quick Connect 自动配置的 CMSContentful、Cosmic、DatoCMS、Sanity需要手动配置的 CMSAgility、Contentstack、Drupal、Flotiq、Kontent、Strapi、WordPress。连接完成后CMS 中的内容更新既可以触发生产构建Production Build也可以触发 CMS Previews具体取决于站点配置。这一配置工作通常在 Gatsby Cloud 的站点设置中完成详见官方 Connecting to a Content Management System 系列教程。CMS Previews 的触发方式一份 CMS Preview 构建build可以由以下任一事件触发触发事件说明CMS 内容变化例如在 CMS 中打字时的自动保存autosave、手动保存save或发布publish动作Git 提交对 Site Settings 中配置的生产分支production branch发起的 Git 提交手动触发在 Gatsby Cloud 用户界面中点击Trigger Build触发构建或Restart Preview重启预览按钮Preview Webhook向预览 Webhook 发送POST请求其中Restart Preview 按钮对应到界面中紫色按钮见上文截图当预览构建失败、卡死或需要强制重建时非常有用而 Preview Webhook 则为 CI/CD 或自定义脚本提供了一条完全自动化的触发通道——你可以把 Webhook 地址配置到任意自动化流程中例如在内容流水线处理完毕后再统一触发一次预览构建。从源码层面看触发后真正“消费”预览数据的动作由各 source 插件完成。以 WordPress 为例packages/gatsby-source-wordpress/src/steps/preview/index.ts 中的sourcePreviews会拉取 WPGatsby 记录的actionMonitorActions按previewStream: true、最近 60 分钟内、按修改时间倒序过滤再逐个调用sourcePreview把单条预览数据合入 Gatsby 数据层。预览请求之间通过PQueue并发队列previewRequestConcurrency来自插件schema.previewRequestConcurrency选项串行调度避免并发风暴压垮构建进程。增量预览Incremental Preview默认的预览构建方式增量预览是当前默认的预览构建器default preview builder。它本质上是对站点做一次生产构建production build但数据源使用由环境变量指定的预览数据preview data——例如指向 CMS 的预览环境或草稿draft内容端点而不是生产数据。增量预览的主要优势首次构建后更新极快由于底层复用了增量构建缓存后续每次预览更新只重建发生变化的部分图片处理可并行化Parallelized Image Processing 让大量图片资源的处理不再成为构建瓶颈所有成功的预览构建始终可用历史成功构建不会被清理方便回看和对比支持预览状态指示器preview status indicator在 Gatsby v3 及更高版本上内容编辑器可以直接看到“本次预览是否成功生成”的状态反馈。下图展示了增量预览模式下数据更新记录上的 CLOUD 徽章——带有该徽章的更新条目即代表它是通过增量预览云侧增量处理完成的需要指定 source 插件版本的 CMS除少数例外所有受支持的 CMS 集成都支持增量预览。其中以下三个 CMS 需要特定最低版本的 source 插件才能启用增量预览CMS所需 source 插件最低版本WordPressgatsby-source-wordpress ≥ 5.2.3DatoCMSgatsby-source-datocms ≥ 2.6.15Sanitygatsby-source-sanity ≥ 7.3.2当前仓库中的源码版本均高于上述门槛。以 WordPress 为例packages/gatsby-source-wordpress/package.json 中声明的主版本为7.18.0-next.0完全满足增量预览的版本要求。若你的项目锁定在低于门槛的旧版本升级插件后再连接 Gatsby Cloud 即可获得增量预览能力。从源码理解增量预览的“预览模式”开关在gatsby-source-wordpress中判断是否处于预览模式并非依赖环境变量硬编码而是集中在一个函数里inPreviewMode 综合了三种信号开发模式NODE_ENV development且开启了ENABLE_GATSBY_REFRESH_ENDPOINT运行器类型为PREVIEW或INCREMENTAL_PREVIEWSRUNNER_TYPE环境变量——后者正是 Gatsby Cloud 增量预览运行器注入的环境变量存在IS_GATSBY_PREVIEW环境变量。这从源码上印证了文档中的描述增量预览依然是“一次构建”只不过它跑在专门标记为预览的运行器runner上并使用预览数据源。生产构建与预览构建共享同一套 Gatsby 构建管线因此增量缓存、并行图片处理等能力天然可用。旧版预览Legacy Preview仅在无法使用增量预览时的回退方案旧版预览构建器只在增量预览不可用的情况下才会被使用。它与本地开发时的gatsby develop行为类似属于持续运行long-running的开发服务器式构建。这意味着它有两个明显短板受资源超时限制长驻进程可能因资源占用或超时而被终止超时后预览不可用一旦发生超时预览将处于不可用状态必须等下一次构建完成后才能恢复访问。因此只要你的 CMS source 插件版本满足增量预览条件Gatsby Cloud 都会优先走增量预览路径旧版预览仅作为兼容性回退。预览扩展Preview Extensions在 CMS 内部直接预览部分 CMS 支持预览扩展Preview Extension内容编辑人员可以在不离开 CMS 界面的情况下直接在编辑器内查看 CMS Preview 构建的渲染结果省去在标签页间切换的成本。目前提供预览扩展的 CMS 包括ContentfulCosmicDatoCMSWordPressSanity其中需要注意WordPress 的预览加载器preview loader不支持受密码保护的预览实例password-protected preview instances。如果你的 WordPress 预览站点开启了密码保护请关闭该保护或改用其他访问控制方式否则预览扩展将无法正常工作。各 CMS 预览扩展的具体安装与配置步骤参见官方 Preview Extensions 教程。预览扩展背后的状态闭环以 WordPress 为例预览扩展之所以能做到“CMS 内即时反馈”是因为 source 插件会把构建结果回传给 CMS。在 createPreviewStatusCallback 中可以看到完整闭环预览构建启动后插件向 WPGraphQL 发起MUTATE_PREVIEW_NODEmutation携带status如PREVIEW_SUCCESS、NO_PAGE_CREATED_FOR_PREVIEWED_NODE、GATSBY_PREVIEW_PROCESS_ERROR、RECEIVED_PREVIEW_DATA_FROM_WRONG_URL之一、pagePath、parentDatabaseId以及modified时间戳等字段通过请求头WPGatsbyPreviewJWT token与WPGatsbyPreviewUser完成鉴权WordPress 侧WPGatsby收到状态后即可在编辑器中展示“预览已就绪”或失败原因。这正是预览状态指示器preview status indicator能在 Gatsby v3 上工作的底层支撑。同理若预览数据来自与插件配置url不一致的远端 WordPress插件会以RECEIVED_PREVIEW_DATA_FROM_WRONG_URL状态拒绝并警告sourcePreviews 中的 URL 校验逻辑防止误连到错误的站点实例。环境变量与预览数据源配置增量预览使用“由环境变量指定的预览数据”因此正确的环境变量配置是预览可用的前提。在 Gatsby Cloud 中环境变量需要在站点级别进行配置相关配置入口与增量预览构建器所需的变量可参考本仓库的配套文档Gatsby Cloud 环境变量说明了解站点级环境变量的作用域与行为管理环境变量掌握在 Gatsby Cloud UI 中新增、更新、加密环境变量的操作Quick Connect通过自动连接快速完成 CMS 数据源集成从而省去手动填写的环节。对于 WordPress 场景插件层面还支持通过环境变量WP_GATSBY_PREVIEW_DEBUG开启预览调试日志sourcePreviews 中的调试分支在排查“预览未触发 / 未更新”问题时非常有效。其他 CMS 的 source 插件也各自提供了预览相关的选项如 Sanity 的watchMode、overlayDrafts等请以对应插件的 README 与版本要求为准。禁用 Preview 与自动停用机制当不需要预览功能时可以通过以下方式关闭进入Site Settings Preview取消勾选Enable CMS Preview builds启用 CMS 预览构建。此外Gatsby Cloud 还有一条自动停用机制如果预览连续10 次构建失败Gatsby Cloud 会自动禁用该站点的 Preview。这意味着预览失败不会无限重试消耗资源站点若因环境变量缺失、插件版本过旧或 CMS 凭证失效等原因持续构建失败会进入“已禁用”状态此时需要排查上述失败原因并重新启用 Preview而不是仅仅点击重试。总结与排查要点把 CMS Previews 部署到生产协作流程中关键决策点可以归纳如下连接受支持的 CMS优先使用 Quick Connect 支持的四家Contentful、Cosmic、DatoCMS、Sanity其余 CMS 按对应文档手动配置确认插件版本WordPress、DatoCMS、Sanity 三个源插件需分别满足≥ 5.2.3、≥ 2.6.15、≥ 7.3.2以获得增量预览默认构建器的快速更新能力配置预览数据环境变量确保预览构建运行时的环境变量指向 CMS 预览/草稿数据端点这是“用预览数据构建”的根本选择触发方式CMS 自动保存/保存/发布、生产分支 Git 提交、UI 按钮、Preview WebhookPOST请求四者按需组合善用预览扩展Contentful、Cosmic、DatoCMS、WordPress、Sanity 支持在 CMS 内直接预览注意 WordPress 预览扩展不支持密码保护的预览实例关注失败与禁用预览连续失败 10 次会自动停用结合 source 插件的调试开关如WP_GATSBY_PREVIEW_DEBUG定位根因后重新启用。如需深入源码了解预览数据如何合入数据层、状态如何回传 CMS可以继续阅读 gatsby-source-wordpress/src/steps/preview/index.ts、预览状态模型 以及 预览清理逻辑关于 Gatsby Cloud 的构建、部署与环境变量体系可参见 production-builds-and-pull-request-builds.md 与 hosting-and-data-source-integrations.md。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考