Gatsby 从 v4 迁移到 v5 完整指南:依赖升级、破坏性变更与源码级迁移要点
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_DEMANDLAZY_IMAGESPRESERVE_WEBPACK_CACHEDEV_WEBPACK_CACHELMDB_STOREPARALLEL_QUERY_RUNNINGGRAPHQL_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
具体变更包括:
- 移除仅在浏览器端存在的
pageResourcesprop(它是内部数据结构); - 移除仅在服务端存在的
*prop(改为使用locationprop); - 移除在服务端/浏览器端含义不一致的
pathprop(改为使用locationprop); - 移除
uriprop(改为使用locationprop)。
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 版本支持文档。