使用 Gatsby 从 GraphCMS 拉取内容:Headless CMS 数据接入完整指南
使用 Gatsby 从 GraphCMS 拉取内容:Headless CMS 数据接入完整指南
GraphCMS 是一个 GraphQL 原生的 Headless CMS(无头内容管理系统),它允许开发者通过 GraphQL API 以编程方式将内容分发到任何平台。本文基于 Gatsby 官方文档《Sourcing from GraphCMS》,完整讲解如何将 GraphCMS 接入 Gatsby 站点:从创建项目、安装配置 gatsby-source-graphcms 插件,到通过 GraphiQL 检查生成的 Schema、编写页面查询与静态查询,并深入本仓库源码揭示其底层数据流与可参考实现。读完本文,你将能够独立完成「GraphCMS 后端 + Gatsby 前端」的完整数据管道搭建。
GraphCMS 是什么:GraphQL 原生 Headless CMS
GraphCMS 是一种 GraphQL 原生的无头内容管理系统。与传统单体 CMS(monolithic CMS)同时负责后端内容管理与前端内容分发不同,Headless CMS 与前端完全解耦,开发者可以使用任何最合适的技术栈来构建面向终端用户的体验。GraphCMS 的核心能力包括:
- 直观的 Schema 构建器:以可视化方式定义内容模型(Model);
- GraphQL Mutations API:支持以编程方式写入、更新内容;
- 开箱即用的本地化(localization):为多语言站点提供内容翻译支持。
借助这些能力,GraphCMS 让内容团队使用熟悉的编辑器创作内容,同时把内容通过 API 交付给 Gatsby 这样的前端框架。在 Gatsby 官方文档 headless-cms.md 中,GraphCMS 被列为受支持的 CMS 之一(文中表格还汇总了 Contentful、WordPress、Sanity、Drupal 等其他主流 CMS 的指南与插件入口)。
开始之前:前置条件
本指南假定你已经具备以下条件:
- 拥有一个处于激活状态的 GraphCMS 账号;
- 已创建一个 GraphCMS 项目(推荐使用 Blog Starter 模板创建)。
本文中所有 Schema 与数据引用均来自 GraphCMS 的 Blog Starter 模板,跟着示例操作可获得一致的结果。
创建新的 Gatsby 站点
使用 Gatsby 默认 starter 新建一个站点:
gatsby new gatsby-site
说明:
gatsby new不带参数时默认使用gatsby-starter-default,即本仓库 starters/default 目录所对应的起始模板;你也可以显式指定其他 starter。创建完成后,执行cd gatsby-site进入项目目录。
安装并配置 gatsby-source-graphcms 插件
为了从你的 GraphCMS 项目拉取数据,需要安装 gatsby-source-graphcms(该插件由 GraphCMS 团队维护,注意它并不是本仓库 packages/ 内的插件包)。
npm install gatsby-source-graphcms
在 gatsby-config.js 中配置插件
在项目根目录的 gatsby-config.js 中加入插件配置:
{
resolve: 'gatsby-source-graphcms',
options: {
// 你的 GraphCMS API 端点,可在项目设置中获取
endpoint: process.env.GRAPHCMS_ENDPOINT,
// 项目 PAT(Permanent Auth Token,永久认证令牌)。
// 当项目非公开访问,或需要将访问范围限定到特定内容阶段(如草稿内容)时必须提供
token: process.env.GRAPHCMS_TOKEN
},
},
核心配置参数:
| 参数 | 必填 | 说明 |
|---|---|---|
endpoint |
是 | GraphCMS 项目的 GraphQL API 端点,从项目设置中获取 |
token |
视情况 | PAT 永久认证令牌。项目非公开、或需要访问受限内容阶段(如 draft 草稿)时必须提供 |
推荐做法:建议使用环境变量保存 token 与 endpoint 的值,避免把凭据提交到版本库。Gatsby 官方提供了环境变量使用指南,见 environment-variables.md。这也是仓库内 gatsby-source-graphql 插件的既有约定——其 README 明确建议通过 dotenv 将环境变量暴露给构建过程,再用 process.env 引用(见 packages/gatsby-source-graphql/README.md)。
检查生成的 GraphQL Schema
配置完成后启动开发环境:
gatsby develop
运行成功后,在浏览器中访问 GraphiQL 探索器:
http://localhost:8000/___graphql
在这里你可以浏览 Gatsby 项目生成的完整 GraphQL Schema,并在线编写、验证查询。
类型命名与前缀约定
Gatsby 为 GraphCMS 项目模型生成的类型都会带上前缀。例如,GraphCMS 项目中的 Post 模型在 Gatsby 内对应 GraphCMS_Post 类型。此前缀是可配置的,通过插件 options 即可调整。
查询字段遵循同样的命名约定,与类型共用同一个前缀。Gatsby 会为每个类型生成两个根查询字段,以 Post 模型为例:
allGraphCmsPost:查询多条Post记录;graphCmsPost:查询单条Post记录。
查询 GraphCMS 内容
利用生成的 Schema,可以编写查询 Gatsby 数据的 GraphQL 查询。下面的查询会返回所有 GraphCMS_Post 节点:
{
allGraphCmsPost {
nodes {
id
content {
markdown
}
coverImage {
url
}
date
slug
title
}
}
}
对应的查询结果(节选):
{
"data": {
"allGraphCmsPost": {
"nodes": [
{
"id": "Post:ckadrcx4g00pw01525c5d2e56",
"content": {
"markdown": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ..."
},
"coverImage": {
"url": "https://media.graphcms.com/QEg7oQCTEeEjLSEPQJtg"
},
"date": "2020-05-05",
"slug": "technical-seo-with-graphcms",
"title": "Technical SEO with GraphCMS"
},
{
"id": "Post:ckadrfuu000pe0148kels2b5e",
"content": {
"markdown": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ..."
},
"coverImage": {
"url": "https://media.graphcms.com/gzYJIkMRRHCq0JLDOqgU"
},
"date": "2020-05-01",
"slug": "union-types-and-sortable-relations",
"title": "Union Types and Sortable Relations with GraphCMS"
}
// ...more results
]
}
}
}
从结果可以看出:id 字段携带类型前缀(如 Post:...),正文内容以 markdown 形式返回,封面图返回 CDN URL,date、slug、title 直接可用。
在组件中实现查询
Gatsby 提供两种数据查询方式:页面查询(page query) 与 静态查询(static query),分别见官方文档 page-query.md 与 static-query.md。
页面查询(Page Query)
页面查询在构建时执行,可以通过页面上下文(page context)接收 GraphQL 变量;如名称所示,它只能用于页面组件,不能用于非页面组件。查询结果通过页面 props 的 data 键提供:
import React from "react"
import { graphql } from "gatsby"
function IndexPage({ data: { posts } }) {
return (
<ul>
{posts.nodes.map(post => (
<li key={post.id}>
<h3>{post.title}</h3>
</li>
))}
</ul>
)
}
export const pageQuery = graphql`
query IndexPageQuery {
posts: allGraphCmsPost {
nodes {
id
content {
markdown
}
coverImage {
url
}
date
slug
title
}
}
}
`
export default IndexPage
注意这里使用了查询别名(posts: allGraphCmsPost),因此函数组件从 props 中解构的是 posts。
静态查询 Hook(useStaticQuery)
静态查询同样在构建时执行,但可以在任意组件中使用,通过 useStaticQuery hook 调用;代价是它不支持 GraphQL 变量:
import React from "react"
import { graphql, useStaticQuery } from "gatsby"
function IndexPage() {
const { posts } = useStaticQuery(graphql`
{
posts: allGraphCmsPost {
nodes {
id
content {
markdown
}
coverImage {
url
}
date
slug
title
}
}
}
`)
return (
<ul>
{posts.nodes.map(post => (
<li key={post.id}>
<h3>{post.title}</h3>
</li>
))}
</ul>
)
}
export default IndexPage
两种查询方式对比:
| 维度 | 页面查询 | 静态查询(useStaticQuery) |
|---|---|---|
| 执行时机 | 构建时 | 构建时 |
| 使用范围 | 仅页面组件 | 所有组件 |
| GraphQL 变量 | 支持(通过页面上下文传入) | 不支持 |
| 数据获取方式 | 页面 props 的 data 键 |
hook 返回值 |
源码视角:底层数据流与可参考实现
虽然 gatsby-source-graphcms 插件本体由 GraphCMS 团队维护,但本仓库提供了理解其底层机制的丰富素材。
gatsby-graphql-source-toolkit:GraphCMS 插件的基础设施
在 v3.5 发布说明 中明确提到:gatsby-graphql-source-toolkit 简化了从远程 GraphQL API 向 Gatsby 拉取数据的过程,它本身不是 source plugin,而是为编写自定义 GraphQL source 插件提供了一组便捷工具与约定,Craft CMS 与 GraphCMS 的 source 插件正是基于它构建的。这意味着 GraphCMS 数据接入遵循「远程 Schema 内省 + 节点化」这一通用范式。
仓库内 GraphCMS 示例:字段缝合与自定义 Resolver
本仓库 examples/using-gatsby-source-graphql 是一个直接面向 GraphCMS API 的可运行示例,其 gatsby-config.js 演示了通过 gatsby-source-graphql 连接 GraphCMS 的经典配置:
{
resolve: `gatsby-source-graphql`,
options: {
fieldName: `cms`,
url: `https://api-euwest.graphcms.com/v1/cjjr1at6d0xb801c3scjrm0l0/master`,
typeName: `GraphCMS`,
refetchInterval: 60,
},
},
其中 typeName: GraphCMS 定义了远程 Schema 的包装类型名(对应本文所述的 GraphCMS_ 前缀),fieldName: cms 指定远程 Schema 在 Gatsby 查询中挂载的字段名,refetchInterval: 60 则让插件每 60 秒定期重新拉取数据(关于 refetchInterval、batch、dataLoaderOptions、createSchema、createLink、transformSchema 等更多进阶选项,可查阅 gatsby-source-graphql/README.md)。
更有价值的是其 gatsby-node.js 中通过 createResolvers 对 GraphCMS 类型进行二次加工的两个典型案例:
createResolvers({
GraphCMS_BlogPost: {
createdAt: {
type: `String`,
resolve(source, args, context, info) {
return dateformat(source.date, `fullDate`)
},
},
post: {
resolve(source, args, context, info) {
return remark().use(html).processSync(source.post).contents
},
},
},
GraphCMS_Asset: {
imageFile: {
type: `File`,
resolve(source, args, context, info) {
return createRemoteFileNode({
url: source.url,
cache,
createNode,
createNodeId,
})
},
},
},
})
这里演示了两种 GraphCMS 内容接入的高频需求:一是内容转换——用 remark 把 GraphCMS 返回的 Markdown 正文同步渲染为 HTML(对应本文查询示例中的 content { markdown } 字段);二是远程资源本地化——用 gatsby-source-filesystem 的 createRemoteFileNode 将 GraphCMS 的媒体 URL 拉取为本地 File 节点,为后续接入 gatsby-plugin-sharp / gatsby-plugin-image 做图像优化铺路。该示例的 gatsby-config.js 同时启用了 gatsby-plugin-sharp 与 gatsby-transformer-sharp,印证了这一图像处理链路。
更多资源
继续深入学习可以参考仓库内的以下内容:
- 使用 Gatsby 从 GraphCMS 拉取内容(本文来源);
- 如何从 Headless CMS 拉取内容(各 CMS 集成总览);
- gatsby-source-graphql 插件文档(底层参考实现);
- GraphCMS 数据接入可运行示例;
- 页面查询指南 与 静态查询指南;
- Gatsby 环境变量指南。
总结
随着各规模项目转向 API-first 架构,通过 API 将内容的创建、丰富与分发接入 Gatsby 变得非常轻松。在后台接入 GraphCMS 这样的内容 API,意味着你可以在几分钟内获得一个可扩展的 CMS,并快速上线你的项目。本文从零完成了「GraphCMS 项目 → gatsby-source-graphcms 插件 → Gatsby GraphQL 数据层 → 页面渲染」的完整闭环:既给出了可直接复制的插件配置、GraphiQL 检查方法、查询示例与两种查询实现方式,也通过仓库源码揭示了其背后的类型前缀机制、gatsby-graphql-source-toolkit 基础设施,以及 Markdown 渲染、远程图片本地化等进阶落地技巧,可为你后续的 GraphCMS 站点开发提供坚实起点。