Gatsby项目中使用Sanity作为数据源的完整指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00057/article/details/148325471

Gatsby项目中使用Sanity作为数据源的完整指南

gatsby The best React-based framework with performance, scalability and security built in. 项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

什么是Sanity.io？

Sanity.io是一个现代化的结构化内容管理平台，它提供了一个基于React构建的开源编辑器。Sanity提供了强大的实时API，既可以读取数据也可以写入数据。作为一个无头CMS（Headless CMS），它允许内容创作者在友好的环境中工作，同时也可以作为应用程序的纯数据后端。

Sanity的核心优势在于其灵活性和可扩展性，使开发者能够轻松地将内容复用到多个渠道，包括网站、移动应用、印刷品、语音助手等。

准备工作

在开始集成Sanity之前，你需要确保已经设置好一个Gatsby项目。如果是从零开始，可以参考Gatsby的快速入门指南创建一个基础项目。

安装与基础配置

首先需要安装gatsby-source-sanity插件：

npm install gatsby-source-sanity

然后在gatsby-config.js文件中进行基本配置：

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-sanity",
      options: {
        projectId: "你的项目ID",
        dataset: "你的数据集名称",
      },
    },
  ],
}

配置选项详解

| 选项名称 | 类型 | 默认值 | 说明 | |----------------|---------|----------|----------------------------------------------------------------------| | projectId | string | 无 | 必填项，你的Sanity项目ID | | dataset | string | 无 | 必填项，要从中获取数据的数据集名称 | | token | string | 无 | 用于从私有数据集获取数据的认证令牌 | | overlayDrafts | boolean | false | 设置为true时，草稿将覆盖已发布版本 | | watchMode | boolean | false | 设置为true可开启实时监听模式，内容变更会立即反映 |

常见问题解决方案

字段缺失错误

当遇到类似"无法查询字段'allSanityBlogPost'"或"未知字段'preamble'"的错误时，通常是因为Gatsby无法识别这些类型和字段。解决方案是为你的数据集部署GraphQL API，这样插件就能了解哪些类型和字段是可用的。

图像处理

Sanity中的图像字段可以通过field.asset.url获取URL，但更推荐使用gatsby-plugin-image来实现响应式图像和高级加载技术。它支持三种布局模式：

约束布局(Constrained)：默认模式，图像会根据容器大小缩放
固定布局(Fixed)：当你知道图像的确切大小时使用
全宽布局(Full Width)：当图像需要填满整个容器宽度时使用

高级功能

草稿覆盖功能

开发过程中，你可能需要查看未发布内容的预览效果。通过设置overlayDrafts: true，草稿版本将覆盖已发布的文档，在Gatsby节点中，草稿会替换已发布的文档。

监听模式

开发时开启watchMode: true可以实时获取内容更新，无需手动重启构建过程。结合环境令牌和草稿覆盖功能，可以实现内容的实时预览。

页面生成策略

Sanity本身没有"页面"的概念，但在Gatsby中你可以通过gatsby-node.js文件创建页面。例如，为Sanity中的"project"文档类型生成页面：

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions
  const result = await graphql(`
    {
      allSanityProject(filter: { slug: { current: { ne: null } } }) {
        edges {
          node {
            title
            slug { current }
          }
        }
      }
    }
  `)
  
  result.data.allSanityProject.edges.forEach(({ node }) => {
    createPage({
      path: `/project/${node.slug.current}`,
      component: require.resolve("./src/templates/project.js"),
      context: { slug: node.slug.current },
    })
  })
}

富文本处理

Sanity中的富文本通常以Portable Text（以前称为Block Content）格式存储。为了简化查询，可以使用_raw<FieldName>字段获取原始JSON表示。例如，body字段会有对应的_rawBody字段。

推荐使用@sanity/block-content-to-react包来序列化Portable Text，它允许你使用自定义React组件来渲染内容。

环境变量配置

为了安全起见，建议将敏感信息如项目ID和令牌存储在环境变量中：

创建.env文件：

SANITY_PROJECT_ID=你的项目ID
SANITY_DATASET=数据集名称
SANITY_TOKEN=你的令牌

在配置中引用：

require("dotenv").config()

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-sanity",
      options: {
        projectId: process.env.SANITY_PROJECT_ID,
        dataset: process.env.SANITY_DATASET,
        token: process.env.SANITY_TOKEN,
      },
    },
  ],
}

通过以上配置，你可以安全地将Sanity与Gatsby项目集成，同时保护敏感信息不被泄露。