使用 gatsby-source-wordpress 从 Starter 起步搭建 Gatsby WordPress 站点完整配置与大型站点优化指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读本文是gatsby-source-wordpress插件的官方入门实战指南完整覆盖从 WordPress 环境准备、安装 WPGraphQL / WPGatsby 两个必备插件、通过官方 WordPress Starter 创建 Gatsby 站点、修改gatsby-config.js接入 GraphQL 端点到首次构建与增量更新的完整流程。文中还针对大型站点给出type节点数量限制与develop.hardCacheMediaFiles媒体硬缓存两类性能优化配置并结合本仓库源码插件文档、官方 Starter、节点抓取实现说明其底层原理读完即可从零跑通一个基于 WordPress 数据源的 Gatsby 站点。为什么推荐从 Starter 开始对于需要接入 WordPress 的新 Gatsby 站点官方推荐的方式是直接基于 Starter 模板创建而不是从零手写整个工程。这样做的原因是Starter 已经内置了经过验证的最佳实践——正确的插件组合、合理的目录结构、可复用的页面模板与配置项你无需把时间浪费在重复实现基础架构上。本仓库中的 gatsby-starter-wordpress-blog 正是官方为 WordPress 场景准备的基础模板它已经配置好了gatsby-source-wordpress、gatsby-transformer-sharp、gatsby-plugin-sharp、gatsby-plugin-image以及 PWA 相关的gatsby-plugin-manifest开箱即可运行。其 gatsby-config.js 中插件的组织方式就是下面即将介绍的配置形态的实物样本。第一步准备 WordPress 环境如果你还没有 WordPress 站点官方建议使用 Local by FlywheelLocalWP在本机创建一个本地 WP 实例只要你的 WP 实例托管在某个可达的服务器上都可以直接进入下一步。安装两个必备插件登录 WordPress 后台访问/wp-admin/plugin-install.php搜索并安装以下两个插件插件作用WPGraphQL为 WordPress 提供 GraphQL API是gatsby-source-wordpress高效、灵活地拉取数据的通道。安装后默认在http://[yoursite.com]/graphql暴露 GraphQL 端点WPGatsby 与 Webhooks 能力用于在 WP 内容变化时触发构建服务重新构建其中 WPGatsby 之所以必须从源码角度可以看得更清楚它配合 WPGraphQL 记录的变更日志是gatsby-source-wordpress实现首次全量拉取、后续只拉增量这一缓存策略的前提。插件文档 caching.md 明确指出得益于 WPGatsby 对 WordPress 数据变更的追踪插件可以激进地使用缓存——第一次运行gatsby develop或gatsby build时拉取全部公开数据之后只拉取发生变化的数据。第二步准备 Gatsby 开发环境在继续之前请确保你的电脑上已安装Node.jsGatsby 的运行环境npmNode 包管理器Gatsby CLI用于执行gatsby new、gatsby develop等命令环境准备完成后即可进入站点创建环节。第三步创建并配置 gatsby-source-wordpress 站点使用官方 Starter 创建站点打开终端进入你希望存放站点的目录然后执行gatsby new my-wordpress-gatsby-site https://github.com/gatsbyjs/gatsby-starter-wordpress-blog该命令会拉取gatsby-starter-wordpress-blogStarter将其放到新建的my-wordpress-gatsby-site目录下并自动执行npm install安装依赖。你也可以直接在本仓库的 starters/gatsby-starter-wordpress-blog 中查看这个模板的完整结构它包含src/ ├── components/ # 布局、SEO、作者简介等组件 ├── pages/ # 404 页面等 ├── templates/ # post.js、page.js、blog-post-archive.js 页面模板 ├── normalize.css └── style.cssStarter 的 gatsby-node.js 展示了如何从 WP 数据生成页面它通过 GraphQL 查询allWpPost/allWpPage用 WordPress 的uri作为 Gatsby 页面路径这样 WP 内部链接和菜单可以无缝工作并额外创建了基于 WPreadingSettings.postsPerPage的分页归档页面。修改 gatsby-config.js 接入 GraphQL 端点站点创建完成后用 IDE 或文本编辑器打开项目根目录下的gatsby-config.js。在plugins数组的开头你会看到 Starter 预置的 WordPress 源插件配置{ /** * First up is the WordPress source plugin that connects Gatsby * to your WordPress site. * * visit the plugin docs to learn more * https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/README.md * */ resolve: gatsby-source-wordpress, options: { // the only required plugin option for WordPress is the GraphQL url. url: process.env.WPGRAPHQL_URL || https://wpgatsbydemo.wpengine.com/graphql, }, },可以看到url是gatsby-source-wordpress唯一必需的插件选项其余参数全部可选完整选项清单见 plugin-options.md。Starter 默认使用环境变量WPGRAPHQL_URL未设置时回退到演示站点地址。你需要把它替换为第一步中 WPGraphQL 插件为你生成的/graphql端点地址{ resolve: gatsby-source-wordpress, options: { url: https://demo.wpgraphql.com/graphql, }, },实践建议把真实端点写进.env或 CI 环境变量如WPGRAPHQL_URL既便于多环境切换也能避免把演示地址误留在仓库里。官方演示端点https://demo.wpgraphql.com/graphql可用来快速体验。第四步运行站点并理解首轮构建行为在终端cd进入站点目录并执行gatsby develop启动后你会看到插件在终端输出一些日志显示它正在从 WPGraphQL 抓取哪些类型的数据。随后在浏览器打开http://localhost:8000即可预览站点。关于数据抓取需要理解两点关键行为见 caching.md首次构建gatsby develop或gatsby build插件从 WPGraphQL 抓取全部可公开访问的数据后续构建只抓取发生变化的数据以保持构建速度。注意如果远程 schema 发生变化整个缓存会失效插件将重新拉取全部数据。每次你新增 npm 包、修改gatsby-config.js或gatsby-node.js时Gatsby 都会清空缓存源插件随之需要重新抓取全部数据——这正是下面两个大型站点优化选项存在的意义。大型站点性能优化两个关键插件选项如果你的站点规模较大比如几千篇文章每次清缓存后的全量重抓会让gatsby develop等待时间很长。gatsby-source-wordpress提供了两个选项来缓解这个问题。选项一用type限制每个类型的抓取数量type选项用于按类型限制从 WordPress 抓取的对象数量。最常用的是特殊的__all类型它对所有节点类型生效{ resolve: gatsby-source-wordpress, options: { url: https://demo.wpgraphql.com/graphql, type: { __all: { limit: process.env.NODE_ENV development ? 50 : null } } }, },语义拆解limit表示该类型最多抓取多少个对象详见 type.__all.limit 的定义the maximum amount of objects of this type to fetch from WordPressprocess.env.NODE_ENV development ? 50 : null表示只在开发模式下限制为 50 条生产构建不受限null即不限制如果希望限制始终生效开发与生产都限制直接写limit: 50。也可以按具体类型分别设置比如只对Post和Page各取 50 条{ resolve: gatsby-source-wordpress, options: { url: https://demo.wpgraphql.com/graphql, type: { Post: { limit: 50 }, Page: { limit: 50 } } }, },围绕这一配置还有几个同层级、常搭配使用的选项见 plugin-options.mdtype.__all.where字符串作为 WPGraphQL 查询的where参数传入典型用法是只抓取特定语言的文章如where: language: zhtype.__all.exclude布尔值设为true时完全排除某类型既不抓取节点也不纳入 schematype.__all.excludeFieldNames按字段名排除某类型上的特定字段如[dateGmt, parent]type.__all.nodeInterface布尔值决定该类型是否被当作完全由其他 Gatsby 节点类型组成的接口。该功能的专项文档 limit-nodes-during-development.md 也给出了同样的示例当你有 1000 甚至 10,000 篇文章时通过limit让开发环境只拉取最新 50 篇可以让gatsby develop的启动时间从 20 分钟级降到 20 秒级。需要注意的是被limit截断的类型在开发环境中不会抓取全量数据因此页面模板只会基于已抓取的部分节点生成页面——这在本地调试样式与组件时完全够用但生产构建务必保持全量或设置足够的数值。选项二用develop.hardCacheMediaFiles硬缓存媒体文件每次 Gatsby 缓存被清空时源插件从 WordPress 下载到本地的所有图片文件都会被删除导致下次运行gatsby develop时必须全部重新下载。hardCacheMediaFiles选项可以把媒体文件硬缓存到 Gatsby 缓存目录之外从而消除开发环境下的重复下载{ resolve: gatsby-source-wordpress, options: { url: https://demo.wpgraphql.com/graphql, develop: { hardCacheMediaFiles: true, } }, },启用后图片会被存放在项目根目录的./.wordpress-cache/path/to/media/file.jpeg与 WP 中路径结构对应本地机器上每个媒体文件只需要下载一次。源码文档 plugin-options.md 中明确了两点注意事项该选项目前标记为experimental实验性默认值为false使用它时请务必把项目根目录下的.wordpress-cache目录加入.gitignore避免缓存文件进入版本控制。与它配套的还有两个同类选项可按需组合使用develop.hardCacheData实验性把 WordPress 数据硬缓存到./.wordpress-cache/caches避免缓存清空后重新拉取全部数据。该硬缓存会在远程 WPGraphQL schema 变化或你修改插件选项时自动清理production.hardCacheMediaFiles实验性与develop.hardCacheMediaFiles行为相同但作用于生产构建同样会把媒体硬缓存到./.wordpress-cache并建议 gitignore 该目录。在开发环境结合type.__all.limit与develop.hardCacheMediaFiles可以有效避免每次改动配置就要全量重抓的开发等待在 CI/CD 中把.wordpress-cache纳入缓存也能显著缩短生产构建时间。进一步定制与进阶资源Starter 只是起点。上手后你可以从以下几个方面继续深入理解 Starter 的页面生成逻辑阅读 starters/gatsby-starter-wordpress-blog/gatsby-node.js学习createPagesAPI 如何把 WP 文章/页面uri映射为 Gatsby 页面路径并生成带previous/next上下文的文章分页归档使用 WordPress 数据编写页面Starter 的src/templates/post.js、page.js、blog-post-archive.js展示了如何通过allWpPost、wpreadingSettings等查询并在模板中渲染数据配置 WPGatsby 的构建与预览参考 configuring-wp-gatsby.md在 WP 后台的GatsbyJS设置页/wp-admin/options-general.php?pagegatsbyjs填入 Builds Webhook / Preview Webhook即可在 WP 内容更新时触发构建服务重新构建查阅完整的插件选项所有可选参数verbose、debug.*、auth.*、schema.*、html.*、searchAndReplace、catchLinks等的字段类型、默认值与代码示例均收录于 plugin-options.md了解插件的数据抓取与媒体处理机制可继续阅读 features/index.md 下的缓存caching、媒体处理media-item-processing、预览preview等专题文档。小结从 Starter 搭建 Gatsby WordPress 站点的完整链路可以浓缩为四步准备 WP安装 WPGraphQL提供/graphql端点与 WPGatsby提供变更日志、Preview 与 Webhook创建站点gatsby new基于 gatsby-starter-wordpress-blog 生成工程接入数据在 gatsby-config.js 中把gatsby-source-wordpress的url指向你的 GraphQL 端点按需优化大型站点使用type.__all.limit限制开发期抓取量使用develop.hardCacheMediaFiles/develop.hardCacheData硬缓存媒体与数据避免清缓存后的全量重抓。以上所有配置均可在不写一行自定义插件代码的情况下完成让 WordPress 内容以 GraphQL 的方式高效流入 Gatsby 的数据层进而获得 Gatsby 带来的性能、可扩展性与安全性收益。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考