Gatsby 从 v4 迁移到 v5 完整指南:依赖升级、破坏性变更与源码级迁移要点

原创2026-09-19 12:02:421,734 阅读
文章标签:前端静态站点Web框架

Gatsby 从 v4 迁移到 v5 完整指南:依赖升级、破坏性变更与源码级迁移要点

导读:本文以 Gatsby 官方《Migrating from v4 to v5》迁移指南为核心骨架,结合本仓库(gatsbyjs/gatsby)中 gatsby-codemods、gatsby-config 配置文档与核心源码,系统讲解如何将站点从 Gatsby 4 平滑升级到 Gatsby 5。读完本文,你将掌握 Node 18 / React 18 的环境升级流程、sort 与聚合字段 GraphQL 新语法的 codemod 自动化迁移原理、trailingSlash 等配置项的变更细节,以及插件维护者需要同步更新的 peerDependencies 要求。

Gatsby 5 引入了 Slice API(共享组件增量构建,官方宣称对高频共享组件的内容变更可将构建时长最高降低 90%)和 Partial Hydration(Beta)(只向浏览器下发必要的 JavaScript)。绝大多数站点只需少量改动即可完成升级:更新到 Node 18、切换到 React 18,以及用 codemod 改写 GraphQL 查询。本文逐项拆解这些步骤与背后的实现依据。

一、升级前准备:先处理 v4 的弃用告警

在动手升级到 v5 之前,强烈建议先把 gatsby(以及所有插件)升级到 最新的 v4 版本。原因在于:Gatsby 5 要求的部分改动(如 GraphQL 查询语法)可以在最新 v4 上提前增量应用,这会让最终的 v5 升级体验平滑得多。

# 交互式选择要升级的依赖到最新版
npm outdated
# 或使用 yarn
yarn upgrade-interactive

升级到最新 v4 后,运行 gatsby build,在构建日志中查找 deprecation(弃用)提示,并按提示逐一修复。这些提示正是 v5 中将要变成硬性要求(破坏性变更)的预演。

二、更新依赖:Gatsby、React 与官方插件

官方推荐的升级顺序是:先升级 Node 到 18,再更新依赖,以确保安装到的包内容是正确版本(部分包的 engines 字段限制了 Node 版本)。

2.1 升级 Node.js 到 18

Gatsby 5 的最低 Node.js 版本是 18.0.0,不再支持 Node 14 和 16——原因是最新版 Node 14 在 Gatsby 5 生命周期内会到达 EOL,而 Node 18 的 "Active LTS" 时间与 Gatsby 5 几乎同步,因此直接跳到 Node 18。建议参考 Node 官方 releases 文档确认各版本状态。

2.2 更新 Gatsby 主包

将 package.json 中 gatsby 更新为 v5 系列:

{
  "dependencies": {
    "gatsby": "^5.0.0"
  }
}

或直接运行:

npm install gatsby@latest

npm 7+ 注意事项:如果你使用 npm 7 或更高版本,本指南中的所有安装命令都建议加上 --legacy-peer-deps 选项,例如:

npm install gatsby@latest --legacy-peer-deps

原因见下文「社区插件」一节:v5 的插件生态尚未全部更新 peerDependencies,npm 7 默认的严格 peer 依赖解析会直接报错。

2.3 更新 React 与 react-dom

Gatsby 5 放弃了对 React 16/17 的官方支持,最低要求 React 18——这是 Partial Hydration 功能的前提条件。

{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

或:

npm install react@latest react-dom@latest --legacy-peer-deps

2.4 更新所有 gatsby-* 相关包

所有由 gatsbyjs/gatsby 官方仓库维护的、包名以 gatsby- 开头的插件都在 v5 中做了 major 版本号提升,需要同步更新到 latest。例如 gatsby-plugin-image:

{
  "dependencies": {
-   "gatsby-plugin-image": "^2.0.0"
+   "gatsby-plugin-image": "^3.0.0"
  }
}

注意:该规则仅适用于官方仓库管理的插件。社区插件可能尚未升级,需要到其各自仓库查看当前兼容状态。

2.5 社区插件的兼容警告

升级后终端可能出现类似警告:

warning Plugin gatsby-plugin-acme is not compatible with your gatsby version 5.0.0 - It requires gatsby@^4.10.0

使用 npm 7 时,该警告可能直接升级为安装错误:

npm ERR! ERESOLVE unable to resolve dependency tree

原因在于插件尚未把 gatsby@^5.0.0 加入其 peerDependencies(详见本文「插件维护者」一节)。多数情况下插件仍可正常工作,可用 --legacy-peer-deps 忽略该警告强行安装。若构建在 Gatsby Cloud 上失败,可以通过项目级 .npmrc 固定该配置:

npm config -L project set legacy-peer-deps true

三、处理破坏性变更(Breaking Changes)

以下变更在 v5 中属于硬性要求,升级时必须解决。其中部分在 v4 中已有弃用提示。另外需注意:自 Gatsby 5 起,Gatsby 2 和 Gatsby 3 已不再受支持(详见仓库中的 Gatsby 版本支持文档:Gatsby 5 处于 Active Long-term Support,Gatsby 4 仅剩 Maintenance 支持至 Q4 2023)。

3.1 最低 Node.js 版本:18.0.0

如 2.1 所述,Node 14/16 不再支持。请在开发机、CI 与构建环境中统一使用 Node 18 或更高版本。

3.2 最低 React 版本:18

React 16/17 不再被官方支持,请确保 react 与 react-dom 均为 18.x。

3.3 非 ESM 浏览器默认不再打 polyfill

Gatsby 的 browserlist 配置默认新增了 supports es6-module 条件,这意味着 Internet Explorer 等不支持 ES 模块的浏览器不再被 polyfill。若仍需支持此类浏览器,请参考浏览器支持配置文档调整 browserlist 配置。作为收益,这一变更大幅加快了"构建生产环境 JS/CSS bundle"阶段——webpack 不再需要为大量旧浏览器代码做 polyfill。

3.4 GraphQL schema:sort 与聚合字段语法变更(重点)

依据 RFC: Change to sort and aggregation fields API中也被列为性能改进项。

3.4.1 使用官方 codemod 一键转换

官方提供 gatsby-codemods 中的 sort-and-aggr-graphql 转换器。在项目根目录执行:

npx gatsby-codemods@latest sort-and-aggr-graphql .

该命令会对项目所有文件应用转换;若只想转换部分文件/目录,把最后的 . 换成具体路径:

npx gatsby-codemods@latest sort-and-aggr-graphql <filepath>

从源码看,该 codemod 的实现位于 packages/gatsby-codemods/src/transforms/sort-and-aggr-graphql.ts:

  • 它基于 Babel/recast 遍历 AST,只处理 graphql 标签模板表达式、graphql() 调用与普通模板字符串,并自动跳过 node_modules、.cache、public 目录(源码第 13–19 行的守卫逻辑);
  • 核心转换逻辑在 processGraphQLQuery 中:遍历 GraphQL AST 的 Argument 节点,识别 sort 参数(旧式 { fields: [...] , order: [...] } 对象,见 isOldSortObject)和聚合的 field 枚举参数,通过 pathSegmentsToAst 将旧式 frontmatter___date 三段式路径按 ___ 分割、逐层还原为嵌套对象,并默认排序方向为 ASC(源码第 274 行:props.order?.[i] ?? \ASC``);
  • 多个排序字段会被转换为对象列表(graphql.Kind.LIST)。

该 codemod 与 JSCodeshift 兼容,也可以手动指定转换脚本运行:jscodeshift -t node_modules/gatsby-codemods/transforms/... <path>,支持 -d(dry-run 试跑)与 -p(打印输出对比)选项,详见 gatsby-codemods 说明文档。

3.4.2 新旧语法对比

排序(Sort):

转换前:

{
  allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
    nodes {
      ...fields
    }
  }
}

转换后:

{
  allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
    nodes {
      ...fields
    }
  }
}

聚合(Aggregation):

转换前:

{
  allMarkdownRemark {
    distinct(field: frontmatter___category)
  }
}

转换后:

{
  allMarkdownRemark {
    distinct(field: { frontmatter: { category: SELECT } })
  }
}

注意:旧语法仍能继续运行——Gatsby 构建时会自动应用上述 codemod 逻辑并转换你的查询,但会在终端输出弃用提示;而且旧语法查询无法在 GraphiQL 中运行(GraphiQL 只认新语法)。官方强烈建议将查询永久迁移到新语法。

3.5 trailingSlash 默认值改为 always

Gatsby 4 中 trailingSlash 的默认值是 legacy;Gatsby 5 移除了 legacy 选项,新默认值为 always——即所有 URL 都会带有结尾斜杠。此变更同样会影响你的重定向(redirects)配置,务必保持一致。建议在 gatsby-config.js 中显式声明你的期望行为:

module.exports = {
  trailingSlash: `always`,
}

该选项支持三个取值(见 gatsby-config 参考文档):

  • always:为每个 URL 追加结尾斜杠,如 /x → /x/(默认);
  • never:移除所有结尾斜杠,如 /x/ → /x;
  • ignore:不做任何自动修改。

(该选项自 gatsby@4.7.0 起可用,Gatsby Cloud 会自动处理;自托管或其他托管商需按 RFC 的"Redirects"要求自行处理重定向行为。)

3.6 useNavigate hook 被移除

官方更新了 @gatsbyjs/reach-router fork 以兼容 React 18 与 React Server Components,同时移除了 useNavigate hook。请改用 navigate:

- import { useNavigate } from "@gatsbyjs/reach-router"
+ import { navigate } from "gatsby"

3.7 移除默认开启的功能 flags 与环境变量

Gatsby 3/4 时代曾用 feature flags 增量发布功能。Gatsby 5 中所有默认已启用的 flags 及对应环境变量(形如 process.env.GATSBY_EXPERIMENTAL_%FLAG-NAME%)被一并移除,在 gatsby-config 中配置它们不再有任何效果,应删除:

  • QUERY_ON_DEMAND
  • LAZY_IMAGES
  • PRESERVE_WEBPACK_CACHE
  • DEV_WEBPACK_CACHE
  • LMDB_STORE
  • PARALLEL_QUERY_RUNNING
  • GRAPHQL_TYPEGEN(例外:可通过 gatsby-config 的 graphqlTypegen 选项开启,见 gatsby-config 参考文档)

3.8 shouldOnCreateNode 转为稳定 API

此前不稳定的 unstable_shouldOnCreateNode 更名为 shouldOnCreateNode,并被视为稳定 API。功能完全一致,只需重命名。若你之前在 onCreateNode 内部用类似判断做 early return,官方建议彻底切换到 shouldOnCreateNode(并删除 onCreateNode 里的判断)。该 API 的典型用法可参见 api-node-docs.ts 中的文档注释,例如:

exports.shouldOnCreateNode = ({ node }, pluginOptions) => node.internal.type === 'Image'

它作为 onCreateNode 的守门人,避免不必要的节点创建回调触发。

3.9 nodeModel.runQuery 与 nodeModel.getAllNodes 被移除

v4 中已标记弃用的 nodeModel.runQuery 和 nodeModel.getAllNodes 在 v5 中被移除,请改用 nodeModel.findOne 与 nodeModel.findAll。findAll 支持组合更复杂的查询,例如从 api-node-docs.ts 的示例可以看到:

const { entries } = await context.nodeModel.findAll({ type: `BlogPost` })

具体的替换步骤可参考仓库中 v3 到 v4 迁移指南的相关章节。

3.10 内部 graphql 依赖升级到 v16

内部 graphql 依赖从 v15 升级到 v16。绝大多数情况下此变更对用户不可见、无需操作;但如果你直接深入 gatsby/graphql,或依赖 graphql v15 的 TypeScript 类型,需要查阅 graphql v16 的发布说明。

3.11 GraphQL Playground 被移除

Gatsby 5 将 GraphiQL 升级到 v2,实现了与 GraphQL Playground 的功能对齐(支持暗色模式、多标签页、基于 localStorage 的状态持久化、文档浏览器搜索与 Markdown 支持、插件生态等,详见 v5.0 发布说明)。因此移除了 GATSBY_GRAPHQL_IDE 环境变量和 GraphQL Playground。GraphiQL v2 的使用方法见 GraphiQL 指南。

3.12 官方插件的破坏性变更

gatsby-plugin-sitemap

output 选项的默认值从 /sitemap 改为 /,即 sitemap-index.xml 现在会生成在站点根目录。

gatsby-plugin-mdx

gatsby-plugin-mdx 默认集成了 remark-unwrap-images。此前 gatsby-plugin-mdx 与 gatsby-remark-images 联用时,图片会被包裹在 <p> 标签内(图片实际是 <div>、<span>、<picture> 的组合,这种嵌套是无效 HTML);默认集成后行为改变,如果你的 CSS 依赖旧的层级结构,这属于破坏性变更。若此前你在 mdxOptions.remarkPlugins 数组中显式配置了 remark-unwrap-images,现在可以将其卸载。

注意:如果你还没完成 gatsby-plugin-mdx 从 v3 到 v4 的迁移,那么要在 Gatsby 5 中使用最新版 gatsby-plugin-mdx,必须先走完那个迁移流程。

四、未来(v6)的破坏性变更预告

以下行为在 v5 中仍可使用,但已标记弃用,将在 v6 中移除。建议尽早迁移。

4.1 <StaticQuery /> 已弃用

<StaticQuery /> 组件被弃用,请改用 useStaticQuery hook,<StaticQuery /> 将在 Gatsby 6 中移除。

迁移前:

import React from "react"
import { StaticQuery, graphql } from "gatsby"

export default function Title() {
  return (
    <StaticQuery
      query={graphql`
        query {
          site {
            siteMetadata {
              title
            }
          }
        }
      `}
      render={data => <h1>{data.site.siteMetadata.title}</h1>}
    />
  )
}

迁移后:

import React from "react"
import { useStaticQuery, graphql } from "gatsby"

export default function Title() {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)

  return <h1>{data.site.siteMetadata.title}</h1>
}

更复杂的自定义组合 hook 场景可参考 useStaticQuery 指南。

4.2 浏览器与服务端 page props 将统一

React 18 引入了更严格的 hydration 错误检测(服务端渲染 JSX 与客户端渲染 JSX 不一致时会抛错)。为便于排查这类问题,Gatsby 计划在 v6 中尽可能统一页面组件在 Node 端(服务端渲染)与浏览器端(客户端渲染)收到的 props。

v6 中页面 props 将由以下字段组成:

const { location, params, data, pageContext, serverData } = props

具体变更包括:

  • 移除仅在浏览器端存在的 pageResources prop(它是内部数据结构);
  • 移除仅在服务端存在的 * prop(改为使用 location prop);
  • 移除在服务端/浏览器端含义不一致的 path prop(改为使用 location prop);
  • 移除 uri prop(改为使用 location prop)。

location prop 在两端仍会略有差异(浏览器端基于 window.location 提供更多属性)。

4.3 ___NODE 命名约定继续弃用

v3→v4 迁移指南中已提及的 ___NODE 约定在 v5 中仍处于弃用状态(官方尚未完成所有重要插件的迁移),因此该语法在 v5 中仍可用,但官方强烈敦促迁移到 @link 指令,详见 v3 到 v4 迁移指南。

五、插件维护者:更新 peerDependencies

大多数插件无需修改代码即可兼容 v5,但为了确保插件不抛出警告或错误,最关键的一步是设置正确的 peer dependencies:gatsby 应位于插件的 peerDependencies 中并声明正确的支持版本。

仅支持 v5:

{
  "peerDependencies": {
-   "gatsby": "^4.0.0",
+   "gatsby": "^5.0.0",
  }
}

同时支持 v4 与 v5:

{
  "peerDependencies": {
-   "gatsby": "^4.0.0",
+   "gatsby": "^4.0.0 || ^5.0.0",
  }
}

如果定义了 engines 字段,还需同步更新最低 Node 版本:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

另外,本文「三、处理破坏性变更」中的部分条目也可能适用于你的插件(例如 shouldOnCreateNode 重命名、nodeModel 方法替换、GraphQL 新语法等)。

六、已知问题:项目里存在多个版本的 graphql

由于内部 graphql 依赖升级到了 v16,你可能会遇到如下报错:

Cannot create as TypeComposer the following value:
  GraphQLScalarType({ name: "Date", description: "A date string, such as 2007-12-03, compliant with the
 ISO 8601 standard for representation of dates and times using the Gregorian calendar.",
specifiedByURL: undefined, serialize: [function String], parseValue: [function String], parseLiteral:
[function parseLiteral], extensions: {  }, astNode: undefined, extensionASTNodes: [] }).

该错误(或类似错误)通常意味着项目中安装了多个版本的 graphql。手动检查:

npm ls graphql

或使用 yarn:

yarn why graphql

一个粗暴但有效的解法是:删除 lock 文件与 node_modules,然后用 npm install --legacy-peer-deps(或 yarn install)重新安装。这只适用于项目依赖比较单纯(仅 gatsby)的场景;如果依赖关系更复杂,可能需要借助 resolutions 之类的机制来强制统一 graphql 版本。

结语

Gatsby 4 → 5 的升级路径整体平滑:绝大多数站点的核心动作只有三个——Node 升到 18、React 升到 18、运行 sort-and-aggr-graphql codemod 改写 GraphQL 查询。其余破坏性变更(trailingSlash 默认值、useNavigate 移除、flags 清理、shouldOnCreateNode 更名、nodeModel 方法替换等)多为一次性的小改动。升级过程中若遇到本文未覆盖的问题,可在仓库的 Discussions 中反馈;关于版本支持周期与后续新功能(Slice API、Partial Hydration Beta、GraphiQL v2),可进一步阅读仓库中的 v5.0 发布说明与 Gatsby 版本支持文档。

登录后查看全文
gatsby