使用 Gatsby 从 GraphCMS 拉取内容:Headless CMS 数据接入完整指南

原创2026-09-20 15:57:371,688 阅读
文章标签:前端静态站点Web框架

使用 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,印证了这一图像处理链路。

更多资源

继续深入学习可以参考仓库内的以下内容:

总结

随着各规模项目转向 API-first 架构,通过 API 将内容的创建、丰富与分发接入 Gatsby 变得非常轻松。在后台接入 GraphCMS 这样的内容 API,意味着你可以在几分钟内获得一个可扩展的 CMS,并快速上线你的项目。本文从零完成了「GraphCMS 项目 → gatsby-source-graphcms 插件 → Gatsby GraphQL 数据层 → 页面渲染」的完整闭环:既给出了可直接复制的插件配置、GraphiQL 检查方法、查询示例与两种查询实现方式,也通过仓库源码揭示了其背后的类型前缀机制、gatsby-graphql-source-toolkit 基础设施,以及 Markdown 渲染、远程图片本地化等进阶落地技巧,可为你后续的 GraphCMS 站点开发提供坚实起点。

登录后查看全文
gatsby