Gatsby × Agility CMS 基准构建实战:从 CMS 内容拉取到 `gatsby build` 的完整链路解析
Gatsby × Agility CMS 基准构建实战:从 CMS 内容拉取到 gatsby build 的完整链路解析
本指南以 Gatsby 官方仓库中的 benchmarks/source-agilitycms 基准站点为研究对象,系统讲解如何将一个以 Agility CMS 为内容源的 Gatsby 站点从初始化(npm run setup)、内容同步(npm run data-update)一路走到生产构建(gatsby build)。读完本文,你将掌握该基准项目的脚本体系、@agility/gatsby-source-agilitycms 插件配置、GraphQL 内容查询与模块化页面渲染流水线,并理解它被用于“WILL IT BUILD”构建性能基准测试的工程意图。
项目定位:一个用来验证“能不能构建”的基准站点
benchmarks/source-agilitycms 是 Gatsby 官方仓库(根目录见 README.md)中 benchmarks/ 目录下的一员,其核心目标正如标题 "Gatsby + Agility CMS : WILL IT BUILD" 所示:在真实的内容管理系统(CMS)数据源下,反复验证 Gatsby 能否稳定、高效地完成生产构建,从而为构建性能回归测试提供标准化的基准负载。
它并不是一个功能完整的企业级 Starter,而是一个刻意保持精简的基准站点——package.json 的自述将其描述为 "A simplified bare-bones starter for Gatsby"。它的完整目录结构如下:
- gatsby-config.js —— 站点与 Agility CMS 数据源插件的核心配置
- gatsby-node.js —— GraphQL Resolver 与远程图片节点的扩展
- package.json —— 全部脚本与依赖声明
- src/AgilityPage.js —— 主页面模板(master page template)
- src/agility/ —— 页面视图模型构建与动态渲染工具
- src/modules/ —— 博客列表、博客详情等内容模块组件
- src/pageTemplates/ —— CMS 驱动的页面模板
三步核心工作流:Setup → Data Update → Build
原文档将整个使用流程浓缩为三个命令,这也是该基准站点的生命周期主干。完整脚本定义在 package.json 中:
| 阶段 | 命令 | 说明 |
|---|---|---|
| 首次初始化(仅一次) | npm run setup |
从 Agility CMS 拉取初始内容,一般由 Agility CMS 官方人员完成 |
| 内容增量更新 | npm run data-update |
从 CMS 更新内容数据,供每次基准构建前刷新数据源 |
| 生产构建 | gatsby build |
执行完整的生产构建,即基准测试的核心被测环节 |
首次初始化:npm run setup
npm run setup
该命令实际执行 NODE_ENV=development node bin/setup.js,即强制以 development 环境变量运行 bin/setup.js 脚本。原文档特别注明 "For the first time setup only (this has been done by Agility CMS staff)"——此步骤只应在第一次配置时执行一次,且通常由具备 Agility CMS 凭据的人员(示例中即 Agility CMS 官方人员)代为完成,因为它需要向内容平台发起一次全量数据初始化。
从 CMS 更新内容:npm run data-update
npm run data-update
对应脚本为 NODE_ENV=development node bin/update.js。在基准测试语境下,这一步的作用是在每次构建前把 CMS 中的最新内容同步到本地,保证构建负载的数据规模与结构保持一致。NODE_ENV=development 是刻意为之:它会让后续的 dotenv 加载 .env.development 环境文件(详见下文配置解析),确保数据更新过程使用开发环境的 API 凭据。
生产构建:gatsby build
gatsby build
这是整个基准站点的最终落点——用最新的 CMS 数据跑一遍完整的 Gatsby 生产构建。基准站点围绕它反复执行,以测量 gatsby build 在真实内容源下的耗时与稳定性,这正是 "WILL IT BUILD" 想要回答的问题。
其他可用脚本
除上述三步外,package.json 还声明了常规开发脚本:
npm run develop/npm start—— 启动gatsby develop开发服务器npm run serve—— 启动gatsby serve预览生产构建产物npm run format—— 用 Prettier 格式化src/**/*.{js,jsx}npm test—— 占位测试命令
配置解析:环境变量与 @agility/gatsby-source-agilitycms 插件
基于 NODE_ENV 的环境文件加载
gatsby-config.js 的第一件事就是通过 dotenv 按环境加载凭据:
require("dotenv").config({
path: `.env.${process.env.NODE_ENV}`,
})
这意味着不同环境读取不同的环境文件:gatsby build(NODE_ENV=production)读取 .env.production,而 setup / data-update 脚本强制使用 NODE_ENV=development,因此读取 .env.development。这是为了让 Agility API 凭据不硬编码进仓库,原文档与代码注释中均强调“keep your agility api credentials secure”。站点依赖三个关键环境变量:
| 环境变量 | 用途 |
|---|---|
BENCHMARK_AGILITY_GUID |
Agility Content Fetch API 的实例 Guid |
BENCHMARK_AGILITY_API_KEY |
Agility Content Fetch API 密钥 |
BENCHMARK_AGILITY_API_ISPREVIEW |
是否使用 Preview API Key(字符串 'true'/'false') |
它们在 gatsby-config.js 中被聚合成 agilityConfig 对象,再透传给数据源插件。
数据源插件完整配置
基准站点的内容全部来自 @agility/gatsby-source-agilitycms 插件(版本 ^1.5.0),其完整配置如下(见 gatsby-config.js):
{
resolve: "@agility/gatsby-source-agilitycms",
options: {
guid: agilityConfig.guid,
apiKey: agilityConfig.apiKey,
isPreview: agilityConfig.isPreview,
debug: false,
languages: [{
name: "English",
code: "en-us",
path: "en"
}],
channels: [{
referenceName: "website"
}],
masterPageTemplate: "./src/AgilityPage.js"
},
},
各配置项的作用:
guid/apiKey:Content Fetch API 的实例标识与访问密钥,来自环境变量,用于安全地建立与 Agility CMS 的连接;isPreview:设为true时使用 Preview API Key,配合下文的前端 Preview Bar 实现“内容预览模式”;debug:设为true可在构建日志中输出更详细的跟踪信息,便于排查数据拉取问题;languages:声明要抓取内容的语言。示例配置了一个语言——名称English、Agility CMS 内的语言码en-us、URL 路径前缀en。path字段决定该语言在 URL 中如何体现,是多语言站点的关键;channels:声明要包含的渠道(Channel)。示例只包含referenceName: "website"的网站渠道,决定了从 CMS 同步哪些站点结构;masterPageTemplate:渲染 Agility CMS 页面的主模板,指向 src/AgilityPage.js。
其余插件还包括 gatsby-plugin-netlify、gatsby-plugin-react-helmet、gatsby-plugin-sharp、gatsby-transformer-sharp,以及将本地 src/img 目录纳入文件节点的 gatsby-source-filesystem(见 gatsby-config.js)。
页面渲染流水线:从 GraphQL 查询到模块组件
插件将 CMS 内容以 GraphQL 节点的形式注入 Gatsby 数据层,而渲染侧的入口是主模板 src/AgilityPage.js。它接收插件传入的 pageContext(包含 pageID、contentID、languageCode、isPreview 等),并执行一次 GraphQL 查询:
query($pageID: Int!, $contentID: Int!, $languageCode: String!) {
agilitypage(languageCode: { eq: $languageCode }, itemID: { eq: $pageID }) {
pageJson
}
agilityPost(languageCode: {eq: $languageCode}, contentID: {eq: $contentID}) {
contentID
customFields {
title
content
imageLocalImg {
childImageSharp {
fluid(quality: 90, maxWidth: 480, maxHeight: 350) {
...GatsbyImageSharpFluid
}
}
}
}
}
}
该查询展示了两个关键节点类型:
agilitypage:返回 CMS 页面的序列化 JSON(pageJson),包含页面结构、内容区(Zone)与模块布局;agilityPost:动态页面条目(如博客文章),查询其contentID与customFields。注意imageLocalImg—— 它是由gatsby-node.js注入的本地图片节点,再经childImageSharp.fluid交给gatsby-image做响应式图片处理(质量 90、宽 480、高 350)。
查询结果经 src/agility/utils.js 的 buildPageViewModel 组装为视图模型:解析 pageJson,若存在 agilityPost 则用文章标题覆盖页面标题,并把 dynamicPageItem、isPreview、languageCode、isMultiLanguage 一并打包。
动态模板解析:AgilityPageTemplate
src/agility/components/AgilityPageTemplate.js 是模板路由的关键:它读取 props.page.templateName,经正则 replace(/[^0-9a-zA-Z]/g, '') 清洗后,用 require(\../../pageTemplates/${pageTemplateName}.js`)` 动态加载对应的页面模板组件。也就是说,CMS 里给某个页面配的模板名称,会直接决定前端渲染用哪一个 React 组件——这是典型的“CMS 驱动页面结构”设计。
示例页面模板 src/pageTemplates/MainTemplate.js 很简单:渲染一个名为 Main 的内容区(ContentZone),由 src/agility/components/ContentZone.js 负责。
内容区与模块的动态装配
ContentZone.js 实现了模块化的内容装配逻辑:
- 从
page.zones[name]取当前内容区挂载的模块列表; - 对每个模块条目,读取其
properties.definitionName; - 用
require(\../../modules/${moduleDefName}.js`)` 动态加载对应的模块 React 组件; - 将
dynamicPageItem与item(模块数据)作为 props 传入渲染。
若内容区不存在或模块组件缺失,组件会向控制台输出明确的错误提示(如 Cannot render modules for zone "Main"... / No react component found for the module "xxx"),便于定位 CMS 与前端组件之间的映射错位。
该基准站点内置了两个典型模块:
- src/modules/PostListing.js —— 博客列表模块,通过
StaticQuery查询allAgilityPost(过滤properties.referenceName为posts),借助sitemapNode.pagePath为每篇文章生成Link链接; - src/modules/PostDetails.js —— 博客详情模块,用
gatsby-image的<Img fluid={post.customFields.imageLocalImg.childImageSharp.fluid} />渲染处理过的图片,并通过dangerouslySetInnerHTML输出富文本content。
数据层扩展:Resolver 与远程图片节点
gatsby-node.js 负责在数据层之上补充 GraphQL 能力,是本基准站点最核心的“源码级”工程点。
createResolvers:为 agilityPost 扩展 sitemapNode
exports.createResolvers = (args) => {
const { createResolvers, getNode, createNodeId, createNode, createContentDigest, configOptions } = args;
const resolvers = {
agilityPost: {
sitemapNode: agility.getDynamicPageItemSitemapNode(),
},
}
createResolvers(resolvers)
}
它为每个 agilityPost 节点增加一个 sitemapNode 字段,用于“获取代表该条目的 sitemap 节点,进而得到条目的 URL”——PostListing 模块正是通过它拿到 pagePath 来生成文章链接。其底层实现位于 src/agility/utils.js:调用 context.nodeModel.runQuery,按 contentID + languageCode 过滤 agilitySitemapNode 类型节点并取首个结果。
同一文件还提供了两个被注释掉的扩展示例,展示如何在需要时打通“链接内容”(Linked Content)查询:
getLinkedContentItem:为agilityAuthor之类的关联条目解析单个链接内容字段(utils.js);getLinkedContentList:为类似“轮播图模块的 slide 列表”解析一组链接内容(utils.js)。
它们演示了同一个模式:在 Resolver 中通过 context.nodeModel.runQuery / findAll 在 GraphQL 节点层完成跨类型关联。
onCreateNode:远程图片本地化
exports.onCreateNode = async ({ node, actions: { createNode }, store, cache, createNodeId }) => {
if (node.properties && node.properties.referenceName.toLowerCase() === `posts`) {
let field = "image"
let imageUrl = node.customFields[field]
if (imageUrl) {
let fileNode = await createRemoteFileNode({
url: imageUrl,
parentNodeId: node.id,
createNode,
createNodeId,
cache,
})
if (fileNode) {
node.customFields[`${field}LocalImg___NODE`] = fileNode.id
}
}
}
}
该钩子对 referenceName 为 posts 的内容条目,将其 customFields.image 中的远程图片 URL 交给 gatsby-source-filesystem 的 createRemoteFileNode 下载为本地文件节点,并把节点 ID 挂到 imageLocalImg___NODE 上。这正是 AgilityPage.js 查询里 imageLocalImg.childImageSharp.fluid 的数据来源——远程图片得以进入 gatsby-plugin-sharp 的响应式图片管线。
预览模式:Preview Bar 与动态预览跳转
基准站点还包含一套轻量的预览机制,与插件配置中的 isPreview 联动:
- src/components/PreviewBar.js:当
isPreview === 'true'时在页面顶部渲染“Preview Mode”提示条,并提供?AgilityPreview=0的退出预览入口; - src/agility/components/DynamicPreviewPage.js:在浏览器端解析 URL 查询参数
ContentID,通过pageContext.redirects将预览中的内容条目重定向到真实页面路径(如/posts/some-post-title);若未匹配到条目,则回退到父级列表页。
这套机制让内容编辑者在发布前即可预览 CMS 中的未发布内容,同时不干扰正常的生产构建路径。
小结:一个可复用的“CMS 驱动构建基准”范式
回看整个 benchmarks/source-agilitycms 基准站点,它的工程脉络非常清晰:
- 凭据安全:
dotenv+ 按NODE_ENV区分的.env.*文件 +BENCHMARK_AGILITY_*环境变量,保证 API 凭据不落入源码; - 数据同步:
npm run setup(一次性初始化)与npm run data-update(内容刷新)构成构建前的数据准备环节; - 标准构建:
gatsby build在真实 CMS 内容之上执行,作为基准测试的被测对象; - 渲染体系:
@agility/gatsby-source-agilitycms插件注入 CMS 节点,主模板 → 页面模板 → 内容区 → 模块组件逐级动态装配,形成“CMS 配置驱动前端”的渲染链路; - 数据层增强:
createResolvers扩展跨节点查询、onCreateNode实现远程图片本地化,展示了对内容节点做深度加工的通用手法。
对读者而言,这套代码库本身就是一份绝佳的参考实现:无论你是想自建一个 Agility CMS 驱动的 Gatsby 站点,还是想为 CMS 类数据源设计一套可复现的构建性能基准,都可以直接对照 gatsby-config.js、gatsby-node.js 与 src/agility/ 下的组件实现进行移植与扩展。
License
本基准站点基于 MIT License 分发,详见 LICENSE。