从 Kontent.ai 为 Gatsby 站点接入内容源：source 插件接入、GraphQL 查询与自动化构建实战

从 Kontent.ai 为 Gatsby 站点接入内容源：source 插件接入、GraphQL 查询与自动化构建实战

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

导读

本文基于 Gatsby 仓库中的官方指南 sourcing-from-kontent-ai.md，完整讲解如何将 Kontent.ai（托管式 CaaS 内容管理系统）接入 Gatsby 站点：从创建 Kontent.ai 项目、安装@kontent-ai/gatsby-source插件，到通过 GraphQL 将内容注入已有页面、按内容类型程序化生成页面，最后配置 Webhook 实现"内容发布即自动重新构建"的持续部署链路。读完本文，你将掌握一条可复现的"CMS 内容 → Gatsby GraphQL → 静态页面 → 自动更新"完整流水线，并了解仓库内 benchmarks/source-kontent 基准站点中真实可运行的等价实现。

Kontent.ai 与 CaaS 为什么适合 Gatsby

Kontent.ai 是一款托管式 CMS，以"内容即服务（Content as a Service，CaaS）"为核心：内容与展示分离，同一份内容既可以驱动 Gatsby 静态站点，也可以复用到移动 App 等其他渠道，内容资产因此具备未来兼容性。它同时提供易用的编辑界面与协作能力，业务人员可在同一处完成内容创作，无需每个用户都依赖技术协助。

在数据建模层面，Kontent.ai 支持多语言内容交付，以及通过 linked items（链接项）在内容之间建立关系。无论内容如何组织，Kontent.ai 的官方 Gatsby source 插件都会为你的站点创建对应的 GraphQL 节点，使 Gatsby 的数据层与 CMS 结构一一对应。

仓库的 headless-cms.md 在 headless CMS 对比清单中同样收录了 Kontent（Kontent by Kentico），可作为其作为 headless 内容源的定位佐证。

Setup：搭建数据源与站点骨架

第一步：准备 Kontent.ai 项目与内容

1. 在 Kontent.ai 官网注册账号，注册后会默认开启 30 天全功能试用；试用期内或之后，可以随时切换到 Developer 计划（始终从免费档起步）或更高阶计划。
2. 准备内容。你可以按自己的业务定义 content types（内容类型，即内容的模板），再基于它们创建 content items（内容项，即实际内容）。如果只想快速体验，可以使用 Sample Project 生成器创建 "Sample Project"，该向导会自动导入示例内容。本指南后续均以 Sample Project 为例。
3. Sample Project 是一个虚构咖啡品牌 Dancing Goat 的完整演示项目，覆盖了 Kontent.ai 的多种特性；你可以在该项目内的 Quickstart 页面查看它在不同渠道中的展示效果。
4. 本指南只需要用到一项关键信息：Project ID。在 Kontent.ai 中进入"Project settings"（项目设置）→ "API keys"即可找到。

第二步：创建 Gatsby 站点并安装 source 插件

假定你已经安装了 Gatsby CLI（参考 快速开始文档，当前仓库推荐使用npm init gatsby交互式创建站点），执行：

gatsby new kontent-guide cd kontent-guide

安装 Kontent.ai 官方 source 插件：

npm install @kontent-ai/gatsby-source

安装完成后，在站点根目录的gatsby-config.js中注册插件：

module.exports = { siteMetadata: { // ... }, plugins: [ // ... { resolve: `@kontent-ai/gatsby-source`, options: { projectId: `<YourProjectID>`, // 填入你的 Project ID // 注意：使用上面生成的 Sample Project 时，`en-US` 是项目默认语言， // 与这里的配置一致；如果是空白项目，这里需要填 `default` languageCodenames: [ `en-US`, // 或你项目中的语言（Project settings -> Localization） ], }, }, // ... ], }

两个配置项的要点：

• projectId：决定插件从哪个 Kontent.ai 项目拉取内容，必须与 API keys 页面中显示的值一致。
• languageCodenames：声明需要同步的语言编码列表。不同项目默认语言不同——Sample Project 为en-US，全新空白项目为default；多语言项目的完整语言列表可在 Project settings → Localization 中查看。

配置完成后即可启动开发服务器验证连通性：

gatsby develop

浏览器访问http://localhost:8000/___graphql打开 GraphiQL，即可浏览所有来自 Kontent.ai 的内容。插件自动生成的查询以kontentItem（查询单个节点）或allKontentItem（查询节点集合）为前缀。关于 GraphiQL 的详细用法可参考 running-queries-with-graphiql.md。

值得一提：仓库中的基准站点 benchmarks/source-kontent/gatsby-config.js 是这套接入的独立佐证——它通过dotenv从.env.${NODE_ENV}读取BENCHMARK_KONTENT_PROJECT_ID与BENCHMARK_KONTENT_LANGUAGE_CODENAMES（逗号分隔后转为数组）注入插件选项，说明 projectId 与 languageCodenames 这两个参数正是插件实际消费的核心配置；该站点使用的是旧版包名@kentico/gatsby-source-kontent，当前文档所采用的@kontent-ai/gatsby-source为其更名后的官方包。

Using the plugin：两种典型内容消费方式

方式一：把 CMS 内容填充进已有页面

以站点首页标题为例。默认模板的标题来自 site metadata，值为 "Gatsby Default Starter"。而 Sample Project 中恰好有一个 Home 类型的唯一内容项 "Home"，因此可以改造布局组件，用useStaticQuery查询该内容项的元数据并渲染为标题：

// ... const Layout = ({ children }) => { const data = useStaticQuery(graphql` query SiteTitleQuery{ kontentItemHome { elements { metadata__meta_title { value } } } } `) return ( <> <Header siteTitle={data.kontentItemHome.elements.metadata__meta_title.value} /> // ...

刷新http://localhost:8000/后，标题会变为 "Dancing Goat–Freshest coffee on the block!"。此后在 Kontent.ai 中修改该标题并重新运行gatsby develop，站点即可重建反映新值（如需全自动，见下文"持续部署"一节）。

这段示例同时演示了 source 插件节点结构的两条规律：

• 单个内容项以kontentItem+ 内容类型驼峰名查询（如kontentItemHome）；
• 元素字段统一挂在elements下，字段名即 Kontent.ai 中的元素 codename（此处为metadata__meta_title），通过.value读取实际内容。

方式二：按内容类型程序化生成页面

CaaS 的一大价值在于：页面可以在 Kontent.ai 中定义，由 Gatsby 在构建期自动生成。下面以 Sample Project 中的 Article 类型为例，三步完成"文章页自动生成"。

第一步：从 URL pattern 元素生成 slug 字段。利用onCreateNode为 Article 节点挂载fields.slug：

exports.onCreateNode = ({ node, actions: { createNodeField } }) => { if (node.internal.type === `kontent_item_article`) { createNodeField({ node, name: `slug`, value: node.elements.url_pattern.value, }) } }

第二步：在createPages中查询所有文章并创建页面。页面路径取自 slug，模板指向src/templates/article.js，并通过context把 slug 传给模板供其查询使用：

const path = require(`path`) exports.onCreateNode = ({ node, actions: { createNodeField } }) => { if (node.internal.type === `kontent_item_article`) { createNodeField({ node, name: `slug`, value: node.elements.url_pattern.value, }) } } exports.createPages = async ({ graphql, actions }) => { const { createPage } = actions // 从 Kontent 查询数据 const result = await graphql(` { allKontentItemArticle { nodes { fields { slug } } } } `) // 创建页面 result.data.allKontentItemArticle.nodes.forEach((node) => { createPage({ path: node.fields.slug, component: path.resolve(`src/templates/article.js`), context: { slug: node.fields.slug, }, }) }) }

第三步：编写文章模板。模板接收context.slug作为查询变量，拉取对应文章后渲染标题与正文：

import React from "react" import { graphql } from "gatsby" import Layout from "../components/layout" const Article = ({ data }) => { const item = data.kontentItemArticle.elements return ( <Layout> <h1>{item.title.value}</h1> <div dangerouslySetInnerHTML={{ __html: item.body_copy.value }} /> </Layout> ) } export default Article export const query = graphql` query articleQuery($slug: String!) { kontentItemArticle(fields: { slug: { eq: $slug } }) { fields { slug } elements { body_copy { value } title { value } } } } `

重新运行gatsby develop后，每篇 Article 都对应一个可访问的页面；访问任意不存在的 URL（如http://localhost:8000/asdf）触发 404 页面，可以查看全部已生成路径的列表。

富文本与 schema 的进阶处理

注意body_copy来自 Kontent.ai 的 rich text（富文本）元素。默认情况下，富文本中的链接和内联链接项（如嵌入视频）不会被解析。若需要解析，可以按结构化形式查询所需数据，自己编写 React 组件渲染；也可以使用官方@kontent-ai/gatsby-components包中的 Rich text element 组件来简化这一工作。

此外，由于 Kontent.ai source 插件为 Kontent 数据定义了 GraphQL schema，你完全可以基于该 schema 按需扩展（例如为节点补充派生字段、接入图片处理等），官方示例仓库中提供了一系列可参考的用法。仓库中 configuring-usage-with-plugin-options.md 也引用了 Kontent source 插件基于pluginOptionsSchema声明配置项的做法——这意味着插件选项受 Gatsby 配置校验保护，误传参数会在启动时得到明确报错。

仓库里的完整对照实现

如果你希望看到上述流程的完整可运行版本，可以直接研究基准站点 benchmarks/source-kontent。它与文档示例的差异正好展示了同一思路的多种写法：

• gatsby-node.js 中，createPages直接通过allKontentItemArticle查询elements.slug.value生成路径，并在查询出错时用reporter.panicOnBuild中止构建，是对"失败快速暴露"的工程化处理。
• src/templates/article.js 展示了富文本content、标题title与图片image的联合查询，其中图片通过gatsby-image的fluid字段与...KontentAssetFluidfragment 处理——说明 source 插件还负责把 Kontent 资产接入 Gatsby 的图片处理管线。
• update-article.js 通过@kentico/kontent-management管理客户端模拟"内容更新"：随机选中一篇文章，创建新语言变体版本、追加一个!修改标题并重新发布。这一脚本用于在构建基准测试中反复触发内容变更，也侧面印证了"CMS 内容更新 → 重新构建"这一持续部署心智模型的可行性。

Continuous deployment：内容发布即自动构建

静态站点的优势在于性能与安全，但要保证内容始终新鲜，需要在已发布内容变更时自动触发重新构建。Gatsby Cloud 用户在 Gatsby Cloud 控制台 可直接配置与 Kontent.ai 的集成；下面以 Netlify 为例给出通用步骤：

1. 在 Netlify 创建 Build Hook：进入站点设置，新建一个 build hook，名称可设为 "Change in Kontent.ai content"，创建后复制生成的 URL。
2. 在 Kontent.ai 创建 Webhook：进入"Project settings" → "Webhooks"，新建 webhook，名称可设为 "Netlify build"，把上一步的 URL 粘贴到"URL address"字段。
3. 选择触发事件：在触发事件中选择 "DELIVERY API TRIGGERS" 下的内容项事件"Publish"与"Unpublish"即可（事件全集可参考 Kontent.ai 官方 Webhooks 参考文档）。

完成后，每当已发布内容发生变化，Kontent.ai 的 webhook 就会请求 Netlify 的 build hook，触发一次新的构建，保证静态内容始终同步到最新版本。这条"Delivery API 触发 → Webhook → 重建"的链路，与上述基准站点中update-article.js借助 Management API 修改并重新发布内容后等待站点重建的思路完全一致，可互为验证。

What's next：更深入的方向

至此，你已经完成了"Gatsby 站点接入 Kontent.ai + 内容变更自动重建"的完整闭环。Kontent.ai 还能支撑更多内容关系：用于分类的 taxonomies（分类法）、多语言内容、以及内容项之间的相互链接。进一步探索可以从三个方向入手：

• 查阅@kontent-ai/gatsby-source插件的 Available Options 文档，了解projectId、languageCodenames之外的更多可选配置（如 API 密钥、预览环境支持等）；
• 阅读 Kontent.ai 官方文档，探索 taxonomies、多语言、linked items 等在 GraphQL 节点中的表现形态；
• 参考 Kontent.ai Gatsby starter 站点，查看一个包含各类内容查询的完整示例站点，或对照仓库内 benchmarks/source-kontent 的基准实现，观察生产级写法与快速上手写法之间的差异。

总结

本文围绕 官方接入指南 完整还原了 Kontent.ai → Gatsby 的内容接入流程：准备 CMS 项目与 Project ID → 安装并配置@kontent-ai/gatsby-source→ 用kontentItem/allKontentItem查询把内容注入既有页面 → 通过onCreateNode与createPages按内容类型自动生成页面 → 通过 Webhook + Build Hook 实现内容发布即重建。同时结合仓库内 benchmarks/source-kontent 的源码印证了插件配置、页面生成、图片处理与内容更新模拟等底层细节，为你在真实项目中落地 CaaS 内容驱动架构提供了可直接参照的完整路径。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby