Gatsby 对接 Contentful CMS：基于 gatsby-source-contentful 构建数据驱动站点实战指南

Gatsby 对接 Contentful CMS基于 gatsby-source-contentful 构建数据驱动站点实战指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文以仓库中的 using-contentful 示例站点 为蓝本讲解如何让 Gatsby 从 Contentful CMS API 拉取内容并构建静态站点。读完本文你将掌握gatsby-source-contentful的完整配置方法、多语言本地化内容查询、基于文件路由的内容型动态页面以及 Contentful 图片资源在 Gatsby 中的三种布局与四种占位符用法可直接照搬搭建自己的 CMS 驱动站点。示例站点一览仓库中的examples/using-contentful是一个演示 如何构建从 Contentful CMS API 拉取数据的 Gatsby 站点 的完整示例。示例使用了一个公开的 Contentful 示例 Space空间内含**产品Product与分类Category**两类内容模型并预先为这些内容配置了英语en-US和德语de两种语言版本用于演示本地化能力。示例站点的数据流向可以概括为构建期gatsby-source-contentful通过 Contentful Content Delivery API 拉取 Space 中的 entry条目与 asset资源插件将数据转换为 Gatsby GraphQL 数据层中的ContentfulProduct、ContentfulCategory、ContentfulAsset等节点类型页面组件通过 GraphQL 查询这些节点并调用gatsby-plugin-image处理图片构建产出静态 HTML部署后即可访问。环境准备与本地运行示例的依赖与脚本定义在 package.json 中核心依赖包括gatsby主框架gatsby-source-contentfulContentful 数据源插件这是本示例的主角gatsby-plugin-image与gatsby-plugin-sharp图片处理gatsby-transformer-remark将 Contentful 中的 Markdown 富文本字段转换为可渲染 HTMLgatsby-plugin-typography、typography排版样式react/react-dom在示例目录下安装依赖后即可启动npm install npm run develop # 启动开发服务器 npm run build # 生产构建输出静态文件 npm run serve # 本地预览构建产物 npm run clean # 清理缓存.cache 与 public构建时插件会实时请求 Contentful API网络可达即可拉取到示例 Space 的全部内容并生成页面。插件配置gatsby-source-contentful 的核心参数示例的完整配置见 gatsby-config.jsmodule.exports { siteMetadata: { title: Gatsby with Contentful, }, plugins: [ gatsby-plugin-image, { resolve: gatsby-source-contentful, options: { spaceId: rocybtov1ozk, accessToken: 6f35edf0db39085e9b9c19bd92943e4519c77e72c852d961968665f1324bfc94, }, }, gatsby-transformer-remark, { resolve: gatsby-plugin-typography, options: { pathToConfigModule: src/utils/typography, }, }, ], }其中最关键的是gatsby-source-contentful的两个必填参数参数作用说明spaceId指定要拉取的 Contentful Space每个 Space 对应一套内容模型与内容数据示例使用的是公开演示 SpaceaccessTokenContent Delivery API 的访问令牌生产环境应通过环境变量注入避免将密钥写死在配置中提交到仓库此外该插件还支持host、environment环境默认 master、downloadLocal、typePrefix等更多选项生产项目建议至少将accessToken替换为环境变量引用如process.env.CONTENTFUL_ACCESS_TOKEN。配置完成后插件会在构建期创建以下三类核心节点供 GraphQL 查询ContentfulProduct对应内容模型 Product 的 entry含产品名、描述、价格、图片、品牌、分类等字段ContentfulCategory对应内容模型 Category 的 entryContentfulAssetSpace 中的媒体资源图片。由于示例使用了gatsby-transformer-remarkProduct 的productDescription字段还会产生childMarkdownRemark子节点从而可以在页面上通过dangerouslySetInnerHTML直接渲染 Markdown 解析后的 HTML。用 GraphQL 拉取 Contentful 内容首页产品列表首页 src/pages/index.js 演示了最基本的查询方式——通过allContentfulProduct获取全部产品节点query { us: allContentfulProduct(filter: { node_locale: { eq: en-US } }) { edges { node { id gatsbyPath(filePath: /products/{ContentfulProduct.id}) productName { productName } image { gatsbyImageData(layout: FIXED, width: 75) } } } } }这段查询有两个值得注意的细节别名alias同一页面内用us和german两个别名并发查询同一类型分别筛出英文与德文产品实现双语列表同屏展示gatsbyPath这是gatsby-source-contentful提供的便捷字段通过传入文件路由的filePath模板即可直接拿到该节点对应页面的真实路径无需手动拼接 URL页面内用它做Link to{node.gatsbyPath}跳转。本地化Localizationnode_locale 与逐语言建节点首页明确展示了插件对 Contentful 本地化特性的完整支持。Contentful 允许同一 entry 拥有多语言版本示例 Space 中的产品同时包含英文和德文内容。插件对本地化的处理规则是为每个语言版本分别创建独立的 entry 与 asset 节点缺失的翻译按 fallback 规则回退每个节点额外增加node_locale字段标识该节点所属语言因此可以通过filter: { node_locale: { eq: en-US } }或eq: de精确筛选单一语言的数据集。页面渲染部分据此把产品列表分成 en-US 与 de 两个区块展示const usProductEdges this.props.data.us.edges const deProductEdges this.props.data.german.edges // ...分别渲染 h3en-US/h3 与 h3de/h3 两组产品这一机制让 一 Space 多语言、站点按语言分流 成为开箱即用的能力。文件路由动态页面{ContentfulProduct.id} 与 gatsbyPath示例没有使用传统的createPagesAPI而是采用了 Gatsby 的**文件路由File System Route API**约定。两个动态页面模板位于src/pages/products/{ContentfulProduct.id}.js为每个产品生成/products/id页面src/pages/categories/{ContentfulCategory.id}.js为每个分类生成/categories/id页面。以产品页为例Gatsby 会自动将文件路由中的{ContentfulProduct.id}解析为查询参数$id模板通过contentfulProduct(id: { eq: $id })精确查询单个产品query($id: String!) { contentfulProduct(id: { eq: $id }) { productName { productName } productDescription { childMarkdownRemark { html } } price image { gatsbyImageData(width: 200) } brand { companyName { companyName } } categories { id gatsbyPath(filePath: /categories/{ContentfulCategory.id}) title { title } } } }页面渲染时解构出产品名称、价格、图片用dangerouslySetInnerHTML渲染 Markdown 描述并通过分类节点的gatsbyPath生成 查看其他分类 的链接。分类页模板与之对称查询contentfulCategory(id: { eq: $id })展示分类图标与关联产品列表产品链接同样由gatsbyPath(filePath: /products/{ContentfulProduct.id})提供。这种 文件路由 gatsbyPath 的组合把内容节点 → 页面路径的映射完全交给框架处理代码更简洁也避免手写 slug 逻辑出错。图片处理Contentful Image API 与 gatsby-plugin-image 集成示例站点专门用 src/pages/image-api.js 一页演示图片能力。Contentful 中的图片资源经插件进入ContentfulAsset节点后可直接通过gatsbyImageData字段调用gatsby-plugin-image的图片优化管线配合GatsbyImage组件渲染。页面在单个查询中同时请求多种处理形态query { allContentfulAsset(filter: { node_locale: { eq: en-US } }) { edges { node { title id constrained: gatsbyImageData(layout: CONSTRAINED, width: 186) fixed: gatsbyImageData(layout: FIXED, width: 100, height: 100) fullWidth: gatsbyImageData(layout: FULL_WIDTH) dominant: gatsbyImageData( layout: CONSTRAINED placeholder: DOMINANT_COLOR width: 186 ) blurred: gatsbyImageData( layout: CONSTRAINED placeholder: BLURRED width: 186 ) traced: gatsbyImageData( layout: CONSTRAINED placeholder: TRACED_SVG width: 186 ) } } } }三种布局layout布局行为适用场景CONSTRAINED默认以源图尺寸或传入的width/height为上限展示容器更小时按比例缩放并生成多档缩小版本供移动端按需加载常规内容图、网格图FIXED固定尺寸不随容器收缩尺寸由源图或width/height决定头像、图标等尺寸确定的场景FULL_WIDTH始终撑满容器宽度不受最大尺寸限制按屏幕断点生成多档图源适合 banner、hero 图全宽横幅、首屏大图可传breakpoints自定义断点四种占位符placeholder占位符原理适用场景DOMINANT_COLOR计算源图主色用纯色背景占位轻量、加载极快BLURRED生成极低分辨率模糊图作为背景占位默认推荐兼顾美观与性能TRACED_SVG生成简化扁平 SVG 占位简单图形、含透明通道的图片NONE不生成占位无需占位效果时示例页面把上述 6 种形态的图片逐一以GatsbyImage image{...} alt{title} /渲染并分别给出对应的 GraphQL 查询片段是查阅参数组合用法最直接的参照image-api.js。布局与排版整体页面的组织方式src/layouts/index.js 定义了全站通用布局顶部为标题栏链接回首页主体内容限定maxWidth: 650底部注明数据来源。各页面通过Layout包裹内容复用该结构。src/utils/typography.js 基于typography库自定义了排版主题baseFontSize: 18px、scaleRatio: 2.15并在平板/移动端媒体查询中调整字号由gatsby-plugin-typography的pathToConfigModule选项引入。小结从示例到生产落地对照本示例把 Gatsby 接到自有 Contentful Space 只需四步在gatsby-config.js中配置gatsby-source-contentful填入自己的spaceId与accessToken生产用环境变量定义内容模型后在页面中通过allContentfulXxx/contentfulXxx查询节点结合node_locale处理多语言用{ContentfulXxx.id}.js文件路由加gatsbyPath生成动态详情页对ContentfulAsset节点使用gatsbyImageData输出经优化的响应式图片。仓库中与本主题相关的深度资料还包括gatsby-source-contentful 插件源码可查看节点创建与本地化实现的完整逻辑、gatsby-plugin-image 文档以及 source-contentful 基准示例。若需复制此示例离线体验可git clone当前仓库后在 examples/using-contentful 目录下运行npm install npm run develop。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考