gatsby-source-wordpress 预览（Preview）配置完全指南：在 WordPress 中接入 Gatsby 实时内容预览-北京尧图网络

gatsby-source-wordpress 预览Preview配置完全指南在 WordPress 中接入 Gatsby 实时内容预览【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本文基于 gatsby-source-wordpress 插件的官方教程文档configuring-previews-legacy.md完整讲解如何在 WordPress 后台wp-admin配置 Gatsby 内容预览Preview功能让编辑在 WordPress 编辑器中点击预览时直接看到由 Gatsby 渲染的实时页面。读完本文你将掌握预览功能的前置条件页面如何携带 node id、WPGatsby 设置页中 4 个预览相关字段的含义与填写方法、如何从 Gatsby Cloud 获取预览实例地址与 Webhook、以及预览失败时的调试与排错手段。文中所有原理说明均以当前仓库源码为佐证可直接对照源码深入阅读。预览Preview是什么gatsby-source-wordpress 插件完整支持内容预览当 WordPress 管理员编辑内容后点击预览按钮打开的将不再是 WordPress 自身的预览模板而是由 Gatsby 渲染的页面。插件在设计上尽量让预览体验与 WordPress 原生体验一致——编辑更新内容、按下预览、预览模板打开并展示最新内容全程无缝衔接。关于预览的整体工作原理、编写预览友好模板的注意事项以及预览调试方法可参见预览功能说明文档。需要注意的是本文讲解的是Legacy传统预览模式的配置方式。较新版本的 WPGatsby 已切换到 Gatsby Cloud 的 Content Sync 服务来处理预览的加载视图、错误处理和跳转对于历史版本的 WPGatsby 或自托管预览实例预览加载逻辑位于 WordPress 侧其配置方式正是本文主题。若你使用的是新版 WPGatsby 与 Gatsby Cloud请参考配置 WPGatsby 教程中的 Content Sync 配置章节。前置条件Gatsby 页面必须携带对应 node id预览功能开箱即用的前提是你的 Gatsby 页面在创建时已将 WordPress 节点的 id 作为pageContext的一部分传入。插件在预览模式下会通过pageContext.id找到页面所依赖的节点从而在 WordPress 中的内容被更新后重建对应页面并向 WordPress 回传预览状态。在仓库的 WordPress 博客 startergatsby-node.js中可以看到标准写法createPages查询所有 WordPress 文章后调用createPage创建页面并在context中写入id: post.idgatsbyUtilities.actions.createPage({ path: post.uri, component: path.resolve( ./src/templates/${post.__typename.replace(Wp, ).toLowerCase()}.js ), context: { // we need to add the post id here // so our blog post template knows which blog post // the current page is (when you open it in a browser) id: post.id, previousPostId: previous ? previous.id : null, nextPostId: next ? next.id : null, }, })从源码层面看插件在onCreatePage生命周期中会读取page.context.id并通过getNode解析出依赖节点再将该页面路径与节点 id 的映射关系保存到内部 store见 on-create-page.ts。这正是页面与节点建立依赖的核心机制没有pageContext.id预览回调将无法定位到需要重建的页面。连接预览实例Connecting Preview开始配置前需要先准备好一个可用的 Gatsby 预览实例。有两种选择在 Gatsby Cloud 上创建一个 Preview 实例Gatsby Cloud 提供免费试用期无需信用卡即可开始试用自托管self-hosted一个 Gatsby 预览服务。打开 WordPress 中的 GatsbyJS 设置页登录你的 WordPress 实例后通过以下任一方式进入 GatsbyJS 设置页直接在浏览器地址栏访问/wp-admin/options-general.php?pagegatsbyjs或在 WordPress 后台左侧菜单悬停Settings设置点击GatsbyJS。进入后可以看到 4 个与 Gatsby 预览相关的字段字段用途Enable Gatsby Preview?启用 Gatsby 预览总开关勾选后覆盖 WordPress 原生预览行为Preview Instance预览实例你的 Gatsby 预览实例的公开前端 URLPreview Webhook预览 Webhook预览构建触发的 Webhook 地址Preview JWT secret预览 JWT 密钥用于签发预览鉴权 JWT 令牌的密钥注意如果你看不到这个设置页或页面中没有这 4 个字段请确认你的 WordPress 实例中安装了最新版本的 WPGatsby 插件WPGatsby 是让 WordPress 与 Gatsby 协同工作的必需插件负责启用构建与预览能力。第 1 步勾选 Enable Gatsby Preview? 复选框勾选此复选框后WPGatsby 将覆盖 WordPress 页面/文章编辑界面中预览按钮的功能。点击预览虽然仍会打开常规的 WordPress 预览模板但 WP 前端会被替换为你的 Gatsby 预览实例用户在浏览器中看到的是 Gatsby 渲染的页面。第 2 步填写 Preview Instance 字段该字段应填写你的 Gatsby 预览实例的公开前端 URL。查找方法如下在 Gatsby Cloud 站点面板中切换到 Preview 标签页等待第一次预览构建完成从页面中央构建历史列表上方的位置复制前端 URLfrontend URL。第 3 步填写 Preview Webhook 字段预览 Webhook 的查找方法进入 Gatsby Cloud 站点面板的 Site Settings站点设置通过左侧菜单进入 Webhooks复制其中的Preview webhook地址填入 WordPress 设置页。这个 Webhook 是 WordPress 向 Gatsby 推送预览请求的入口编辑点击预览时WPGatsby 会把带 JWT 令牌的请求 POST 到这个地址触发 Gatsby 端拉取待处理的预览。第 4 步核对 Preview JWT secret 字段该字段在安装 WPGatsby 时应已自动填充一个密码学安全的密钥。如果该字段为空可以从 WordPress salts 生成器中复制一个 salt 作为 JWT 密钥。安全提醒此密钥用于签发查看预览时所需的短时 JWT 令牌因此必须使用足够强的密钥防止出现安全问题。使用你的预览Using your Preview完成上述配置后即可使用预览进入一个你想要预览的页面或文章像平时一样编辑内容点击编辑界面右上角的预览按钮一个新的标签页会打开展示你的预览实例与预览内容。预览背后的工作机制源码视角理解配置字段的意义还需要了解预览的完整链路。根据 features/preview.md 与插件源码src/steps/preview/index.ts其工作流程如下按下预览按钮WPGatsby 生成一个 JWT过期时间为 1 小时将其 POST 到 Gatsby 预览实例的 Webhook拉取待处理预览Gatsby 预览实例使用这个短时 JWT 向 WordPress 请求所有用户的待处理预览列表。在sourcePreviews中插件会通过 WPGraphQL 查询actionMonitorActions条件为previewStream: true、status: PRIVATE并且只处理最近 60 分钟内产生的预览动作见 index.ts 中的Date.now() - 1000 * 60 * 60——因为每个已处理的预览动作都会被删除这个时间窗口主要是为了覆盖冷启动构建期间的预览请求逐条处理预览对每条预览动作调用sourcePreview使用fetchAndCreateSingleNode拉取并创建单个节点isPreview: true同时注册一个页面创建完成回调见 index.ts页面重建与状态回传当onCreatePage触发且检测到页面依赖的节点已更新时插件会通过wpGatsbyRemotePreviewStatusmutation 把PREVIEW_SUCCESS等状态回传给 WordPress见 on-create-page.ts前端跳转在 Legacy 模式下WordPress 会自动打开已被 WPGatsby 覆盖的 WP 预览模板由 WPGatsby 负责加载/错误状态处理并在预览构建完成后将用户重定向到正确页面。插件还定义了 4 种预览状态用于向 WordPress 报告预览处理结果见 index.tsPREVIEW_SUCCESS预览构建成功NO_PAGE_CREATED_FOR_PREVIEWED_NODE预览节点没有对应的页面被创建GATSBY_PREVIEW_PROCESS_ERROR预览处理过程中出错RECEIVED_PREVIEW_DATA_FROM_WRONG_URL收到了来自错误 WordPress 地址的预览数据插件会校验 webhook 中remoteUrl与gatsby-config.js中配置的url是否为同一主机名不一致时拒绝处理并给出警告见 index.ts。预览模式下的插件预设PREVIEW_OPTIMIZATION为了加速预览构建插件内置了一个预览优化预设当 Gatsby 站点处于预览模式时会禁用 HTML 字段中的静态资源转换并限制冷启动构建时最初拉取的节点数量。你可以通过将presets设为null来关闭该预设自己设置的选项会覆盖预设值{ resolve: gatsby-source-wordpress, options: { url: https://your-site.com/graphql, presets: null } }该预设的实现位于 src/models/gatsby-api.ts{ // 内部名称 presetName: PREVIEW_OPTIMIZATION, // 该预设被启用的条件 useIf: () inDevelopPreview || inPreviewRunner, // 这些选项会合并进全局默认选项你的自定义选项会覆盖它们 options: { html: { useGatsbyImage: false, createStaticFiles: false, }, type: { __all: { // 冷启动时所有节点限制为 50 个 limit: 50, }, Comment: { // 所有评论被排除 limit: 0, }, // 以下三种类型在冷启动时无限制 Menu: { limit: null }, MenuItem: { limit: null }, User: { limit: null }, }, }, }源码中的inPreviewMode判定逻辑见 index.ts为NODE_ENV development且设置了ENABLE_GATSBY_REFRESH_ENDPOINT或RUNNER_TYPE为PREVIEW/INCREMENTAL_PREVIEWS或设置了IS_GATSBY_PREVIEW。另外注意在 Gatsby v4 及以上版本中由于无法在 resolver 中拉取节点type.limit相关设置将不再应用以避免连接字段引用未拉取节点导致的数据缺失源码中有明确注释说明这一点。关于预设机制的更多细节presets[].presetName、presets[].useIf、presets[].options以及type.__all.limit等选项的完整说明可查阅插件选项文档中的presets与type.__all.limit章节。此外schema.previewRequestConcurrency默认值为 5见 gatsby-api.ts控制预览拉取期间并发发出的 GraphQL 请求数如果多个用户同时预览导致 WordPress 服务器崩溃可以调低该值。调试预览构建过程如果你需要排查预览构建问题可以在插件选项中开启options.debug.preview{ resolve: gatsby-source-wordpress, options: { url: https://your-site.com/graphql, debug: { preview: true, }, }, }将其设为true后预览构建过程中会输出额外的日志信息包括发送给 Gatsby 的 webhook 请求体内容、预览节点数据、以及从 WordPress 拉取的预览动作列表见 index.ts源码中还会额外检查WP_GATSBY_PREVIEW_DEBUG环境变量。同时建议查看插件选项文档中debug.preview一节的说明。常见的破坏预览的 gatsby-node.js 问题以下两类写法会导致预览失效需要特别注意。问题 1查询节点时把被预览的节点过滤掉了在process.env.NODE_ENV development时不要在你的gatsby-node.js节点查询中做过滤。例如下面按状态过滤的写法会破坏预览exports.createPages async ({ graphql }) { const graphqlResult await graphql(/* GraphQL */ query { allWpPost(filter: { status: { eq: publish } }) { edges { node { id uri } } } } ) }按分类过滤同样会破坏预览因为 WordPress 中给文章添加分类这一动作本身是不可预览的exports.createPages async ({ graphql }) { const graphqlResult await graphql(/* GraphQL */ query { allWpPost( filter: { categories: { nodes: { elemMatch: { name: { eq: Blog } } } } } ) { edges { node { id uri } } } } ) }问题 2使用了 createPagesStatefully创建页面应使用 Gatsby 的createPagesNode API使用createPagesStatefully会导致预览无法工作。预览安全注意事项在 Legacy 预览模式下为了支持多个用户同时预览或内容更新与预览同时发生WPGatsby 需要生成一个用户无关的 JWT 令牌并发送给 Gatsby以便拉取任意用户的全部待处理预览。这意味着该 JWT 可以以任何用户的身份认证你的 Gatsby 实例被信任的级别等同于 WordPress 核心代码或插件/主题。因此在安全方面应做到只允许可信的个人或团队拥有 WP 服务器代码/主机与 Gatsby 代码/主机的代码级访问权限始终为 WordPress 主机与 Gatsby 预览实例启用 SSL在 Gatsby Cloud 上该工作由平台自动完成该 JWT 仅在预览过程中 POST 到你的 Gatsby 预览实例时可用JWT 的 POST 目标地址只能由管理员通过 WPGatsby 设置页或拥有 WP 实例代码级访问权限的人配置。另外Gatsby Preview 本身没有用户访问角色的概念任何拥有预览实例前端、GraphiQL 或代码级访问权限的人都能看到所有已处理的 Gatsby 预览内容。因此请妥善管理预览实例的访问权限。进一步阅读预览功能整体说明预览工作原理、预览友好模板编写注意事项、调试方法、Gutenberg 与 ACF 的已知限制配置 WPGatsby 教程包含使用 Gatsby Cloud Content Sync 的新版预览配置方式以及构建BuildsWebhook 的配置插件选项文档debug.preview、schema.previewRequestConcurrency、type.__all.limit、presets等预览相关选项的完整说明WordPress 博客 starterpageContext.id的标准用法示例预览核心实现源码src/steps/preview/index.ts、src/steps/preview/on-create-page.ts、src/models/gatsby-api.ts。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

gatsby-source-wordpress 预览（Preview）配置完全指南：在 WordPress 中接入 Gatsby 实时内容预览

相关推荐

候车室底层逻辑拆解：从入门到精通应对API大改

低显存跑长上下文：Spark-X2.5-1.7B 内存优化与 KV-Cache 调优实战

青岛游实战：3步搞定项目避坑，保姆级教程详解

更多资讯

3个坑搞定创造价值源码解析面试

2026最新office怎么用：源码视角拆解办公自动化底层逻辑

电脑开机找不到硬盘排查从入门到精通：3分钟定位根源

疯狂猜图帽子进阶用法

11月王者轮回：面试必问的移动端调试死磕指南

3步搞定2026最新快速止牙疼技术选型避坑指南

今日更新

OneUptime 自定义探针（Custom Probe）部署实战：私网监控、代理配置与断连排障全指南

大众TL52625前端框架材料要求详解：从性能测试到落地执行

TiXL 浮点运算算子库 Lib.numbers.float 完全指南：44 个算子的参数详解、源码原理与实战串联

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？