企业官网建设流程全解析

• 前端
• 静态站点
• Web框架

本篇文章基于当前仓库中的 Gatsby v4.11 官方版本发布说明（docs/docs/reference/release-notes/v4.11/index.md）展开，系统梳理该版本（2022 年 3 月第三次发布，版本号gatsby@4.11.0）的两大核心亮点：gatsby-source-shopify从 V6 升级到 V7 的破坏性变更与迁移要点，以及 Gatsby 对 React 18 SSR API 的 100% 兼容支持；同时覆盖本版本的若干重要 bugfix 与改进项。读完本文，你将掌握 Shopify 数据源插件 V7 的配置、查询与迁移方法，并了解 React 18 在 Gatsby 中的使用前提。

版本概览

gatsby@4.11.0发布于 2022 年 3 月 29 日，属于 2022 年 3 月的第三次发布（March 2022 #3）。本次发布的关键亮点集中在两方面：

• gatsby-source-shopifyv7：由社区成员 Byron Hill 主导的重写（PR #34049），带来媒体、presentment 价格、显式类型定义等一批重要能力；
• React 18 支持：React 18 最新 RC 版本在 SSR API 上引入了破坏性变更，本版本使 Gatsby 与之重新达到 100% 兼容，为官方 React 18 正式发布做好了准备。

此外还有一批值得关注的 bugfix 与改进（见下文“Notable bugfixes & improvements”小节）。

如果你希望提前体验尚未发布的新功能，可以安装gatsby@next版本。

gatsby-source-shopifyv7 重大版本更新

gatsby-source-shopify在 v7 中经历了一次重写，核心目标是与 Shopify 的 Admin API Schema 尽量对齐。其底层原理保持不变：该插件通过 Shopify 的Bulk Operations API批量拉取数据，从而能够处理大体量数据、保证构建过程的韧性（resilient），并支持增量构建——当你在 Shopify 后台修改数据时，站点可以快速重建。这一点在该插件仓库的 README 中有明确说明。

v7 带来的主要改进

根据发布说明，v7 版本引入了以下能力提升：

1. 媒体查询扩展：除了产品图片，现在还可以查询产品视频（含外部视频）或 3D 模型；
2. 字段顺序保持：Variants、Images 等字段会保持你在 Shopify 后台定义的顺序；
3. Metafield 类型合并：多种 metafield 类型合并为单一的 metafield 类型，与 Shopify Admin API Schema 更对齐（详见下文迁移指南）；
4. Presentment 价格查询：可以查询 presentment prices（即按展示渠道/货币展示的价格）；
5. 显式类型定义并禁用类型推断：即使你的商店没有任何产品，或大量字段为null，也不会破坏 Schema 或导致构建失败；
6. Schema 对齐 Shopify Admin API：绝大多数情况下可以直接参考 Shopify 的官方文档来编写查询。

显式类型定义（禁用类型推断）

第 5 点是 v7 架构层面的重要变化。在源码层面，插件通过createSchemaCustomization与@dontInfer指令为每个实体显式声明 GraphQL 类型。以产品类型为例，product-type.ts 中定义：

type ${prefix}Product implements Node @dontInfer { id: ID! shopifyId: String! legacyResourceId: String! featuredMedia: ${prefix}Media @link(from: "_featuredMedia", by: "id") media: [${prefix}Media!]! @link(from: "media___NODE", by: "id") metafields: [${prefix}Metafield!]! @link(from: "metafields___NODE", by: "id") options: [${prefix}ProductOption!]! priceRangeV2: ${prefix}ProductPriceRangeV2! variants: [${prefix}ProductVariant!]! @link(from: "variants___NODE", by: "id") # ...更多字段 }

@dontInfer意味着 Gatsby 不再根据节点数据动态推断字段，而是完全以这份显式 Schema 为准。这带来的直接收益正是发布说明中提到的：空商店、全null字段都不会再导致 Schema 生成失败或构建中断，构建过程因此更加稳健。媒体类型则通过interface ${prefix}Media联合ShopifyMediaImage、ShopifyExternalVideo、ShopifyVideo、ShopifyModel3d等具体类型，见 media-type.ts，其中MediaContentType枚举覆盖了VIDEO、EXTERNAL_VIDEO、MODEL_3D、IMAGE四种媒体内容类型。

快速上手配置

v7 插件的基础安装与配置（来自 README）：

npm install gatsby-source-shopify gatsby-plugin-image

require("dotenv").config() module.exports = { plugins: [ { resolve: "gatsby-source-shopify", options: { password: process.env.SHOPIFY_APP_PASSWORD, storeUrl: process.env.GATSBY_MYSHOPIFY_URL, salesChannel: process.env.SHOPIFY_APP_ID, // 可选但推荐 }, }, "gatsby-plugin-image", ], }

其中GATSBY_MYSHOPIFY_URL是登录 Shopify 账号时使用的商店地址，格式为my-unique-store-name.myshopify.com。

插件选项详解

v7 插件的选项校验定义在 plugin-options-schema.ts，全部选项如下：

注意：salesChannel选项默认取process.env.GATSBY_SHOPIFY_SALES_CHANNEL的值；如果该值未设置，插件只会拉取发布到online store销售渠道的数据。

构建优先级判定

由于 Shopify Bulk API 的限制，同一时间一个 Shopify App 只能运行一个 bulk operation。为此插件内置了构建优先级判定逻辑：通过环境变量判断当前是否为 Gatsby Cloud 或 Netlify 上的生产构建，优先级构建可以暂停非优先级构建：

const isGatsbyCloudPriorityBuild = CI === `true` && GATSBY_CLOUD === `true` && GATSBY_IS_PR_BUILD !== `true` const isNetlifyPriorityBuild = CI === `true` && NETLIFY === `true` && CONTEXT === `production` return pluginOptions.prioritize !== undefined ? pluginOptions.prioritize : isGatsbyCloudPriorityBuild || isNetlifyPriorityBuild

如果你在gatsby-config中显式设置prioritize为true或false，将覆盖环境变量的判定结果。

图片与媒体查询

v7 默认使用 Shopify CDN 配合gatsby-plugin-image。产品页面常见的媒体预览查询：

query { products: allShopifyProduct { nodes { media { preview { image { gatsbyImageData } } ... on ShopifyExternalVideo { embeddedUrl host } ... on ShopifyVideo { sources { format height url width } } } } } }

如果希望在构建期下载图片（同源提供、运行时加载更快但增加构建时长），需要开启downloadImages: true并额外安装gatsby-plugin-sharp与gatsby-transformer-sharp：

{ resolve: "gatsby-source-shopify", options: { password: process.env.SHOPIFY_APP_PASSWORD, storeUrl: process.env.GATSBY_MYSHOPIFY_URL, downloadImages: true, }, }, "gatsby-plugin-image", "gatsby-plugin-sharp", // downloadImages 为 true 时必选 "gatsby-transformer-sharp", // downloadImages 为 true 时必选

V6 到 V7 迁移指南要点

迁移的核心是Schema 变更。v7 中所有来自 Shopify API 的id字段都被映射为shopifyId，id始终是 Gatsby 内部 ID；Schema 完全静态类型化，并尽可能贴近 Shopify GraphQL API。主要破坏性变更如下：

1.ShopifyProduct.images→ShopifyProduct.media

旧版本在ShopifyProduct上暴露images字段，导致无法支持视频与 3D 渲染；新版本改为直接暴露media字段。迁移前：

shopifyProduct { images { gatsbyImageData } }

迁移后：

shopifyProduct { nodes { media { ... on ShopifyMediaImage { image { gatsbyImageData } } } } }

注意media字段返回的数据结构与images不同，消费这些查询的组件代码通常也需要相应调整。

2.ShopifyProductOption.id→shopifyId

shopifyProduct { options { # 每个 option 的类型为 "ShopifyProductOption" shopifyId } }

3. Metafield 类型合并为单一ShopifyMetafield

旧版本存在ShopifyProductMetafield、ShopifyCollectionMetafield、ShopifyProductVariantMetafield三种类型，现在合并为单一的ShopifyMetafield类型；同时Metafield.ownerType从string变为与 Shopify API 对齐的enum类型。查询方式由：

allShopifyProductMetafield { nodes { id value description ownerType } }

改为（语义等价）：

allShopifyMetafield(filter: {ownerType: {eq: PRODUCT}}) { nodes { id value description value } }

4. Locations 字段调整

由于 Shopify API 内部 bug 导致 legacy locations 抛错，ShopifyLocation.fulfillmentService.callbackUrl字段被移除，待 Shopify 侧修复后重新加回。

使用建议：由于同一 Shopify App 同一时间只能运行一个 bulk operation，官方建议每个商店至少准备两个 Shopify App——一个用于生产、一个用于本地开发，以避免构建冲突。

React 18 支持

React 18 的最新 RC 版本在SSR API 中引入了破坏性变更。Gatsby 4.11.0 通过跟进这些变更，重新达到 100% 兼容，时机正好赶上 React 18 的官方正式发布（2022 年 3 月 29 日）。

在 React 18 下，你可以开始使用：

• Suspense：声明式地处理异步组件加载；
• React.lazy：组件级代码分割，配合 Gatsby 已有的按页面/路由分割进一步优化加载；
• Concurrent Mode（并发模式）：新的渲染机制，有助于提升大型 Gatsby 站点的交互响应速度。

需要说明的是，文章所依据的 v4.11 发布说明记录了当时 React 18 处于 RC 阶段、Gatsby 恢复兼容这一事实；在当前仓库时间点，React 18 已正式发布多年，且本仓库还包含专门的 e2e-tests/react-19 测试目录，说明生态已持续演进。若要在你自己的项目中使用 React 18 的这些能力，请以当前gatsby包支持范围及 React 官方发布博客 中记录的能力边界为准。

Notable bugfixes & improvements

v4.11.0 还包含以下重要修复与改进：

• gatsby
  • 修复 Windows 上清除缓存时的eperm问题（PR #35154）；
  • 改进 Functions 的编译错误提示（PR #35196）；
• gatsby-plugin-utils：为 Image Service 增加对aspect ratio的支持（PR #35087）；
• gatsby-source-mongodb：新增可选的typePrefix选项，用于覆盖默认的 dbName 前缀（PR #33820）；
• gatsby-cli：显式解析 babel preset ts（PR #35153）；
• gatsby-plugin-preact：修复 preact alias（PR #35156）。

其中gatsby-source-mongodb的typePrefix选项在源码中得到验证：在 gatsby-node.js 中，节点类型的生成使用pluginOptions.typePrefix ?? dbName，即未配置typePrefix时回退到数据库名作为前缀；其选项说明也出现在该插件的 README 中。该选项适用于需要以自定义前缀组织实体类型、避免多个数据库节点类型冲突的场景。

总结

Gatsby v4.11.0 是一个兼顾“能力升级”与“兼容性”的版本：gatsby-source-shopifyv7 通过显式 Schema、媒体类型支持与 metafield 合并，把 Shopify 数据源插件推向更接近 Shopify Admin API 的现代形态（迁移时需重点处理images→media、id→shopifyId、metafield 合并三处 Schema 变更）；同时 Gatsby 及时跟进 React 18 RC 的 SSR API 变化，为随后到来的 React 18 正式版铺平了道路。若需了解更完整的变更清单，可查阅仓库根目录的 CHANGELOG.md 以及上一版本发布说明 v4.10 Release Notes。

• 前端
• 静态站点
• Web框架