从 v1 迁移到 v2

寻找 v1 文档？ 在此处找到它们。

本文档仍在进行中。您是否遇到此处未涵盖的内容？ 在 GitHub 上添加您的更改！

简介

这是将您的网站从 Gatsby v1 迁移到 Gatsby v2 的参考。虽然这里涵盖了很多内容，但您的网站不一定需要全部完成。我们将尽力使其易于理解，并尽可能按顺序进行，以便您可以顺利过渡到 v2！

如果您想从头开始，请查看 “对于探索者”部分。

为什么要迁移

本篇文档涵盖了从 v1 迁移到 v2 的 方法。各种博客文章涵盖了 原因。

• v2 概述 by Kyle Mathews
• 提高可访问性 by Amberley Romo
• 保持 Gatsby 网站闪电般的速度 by Dustin Schau

我们将涵盖的内容

• 更新您的依赖项

  • 更新 Gatsby 版本
  • 安装 React
  • 安装插件的对等依赖项

• 处理重大变更

  • 移除或重构布局组件
  • 将 navigateTo 改为 navigate
  • 转换为纯 CommonJS 或纯 ES6
  • 移动 Babel 配置
  • 恢复 v1 PostCSS 插件设置
  • 从 React Router 迁移到 @reach/router
  • onPreRouteUpdate 和 onRouteUpdate 的 API 不再通过路由更新操作进行调用
  • Browser API replaceRouterComponent 已移除
  • Browser API replaceHistory 已移除
  • Browser API wrapRootComponent 已被 wrapRootElement 替换
  • 不要按 ID 查询节点
  • 在 RootQueryType 中使用 Query
  • Typography.js 插件配置
  • 更新使用连字符的 CSS Modules 类名
  • 更新 Jest 配置
  • gatsby-image 的 outerWrapperClassName 已移除

• 解决已弃用的问题

  • 从 Gatsby 导入 Link
  • 从 Gatsby 导入 GraphQL
  • 将 boundActionCreators 重命名为 actions
  • 将 pathContext 重命名为 pageContext
  • 重命名响应式图片查询
  • deleteNodes API 已弃用

• 其他值得注意的更改

  • 不再需要显式查询名称
  • 移除 html.js 中的内联 CSS
  • 移除显式 polyfills

• 对于插件维护者

  • 设置正确的对等依赖项
  • 将 modifyBabelrc 改为 onCreateBabelConfig
  • 将 modifyWebpackConfig 改为 onCreateWebpackConfig
  • createRemoteFileNode API 已更改
  • 只允许节点 internal 对象上已定义的键
  • 从 gatsby/graphql 导入 graphql 类型

• 对于探索者

  • 从头开始 v2

更新您的依赖项

首先，您需要更新您的依赖项并安装任何需要的对等依赖项。

更新 Gatsby 版本

您需要将 package.json 更新为使用最新版本的 Gatsby。

或者运行

更新 Gatsby 相关包

将您的 package.json 更新为使用最新版本的 Gatsby 相关包。您应该升级任何以 gatsby- 开头的包名。注意，这仅适用于 gatsbyjs/gatsby 仓库中管理的插件。如果您使用的是社区插件，它们可能尚未升级。检查它们的仓库以了解状态。许多插件不需要升级，因此它们很有可能仍然有效。您可以运行

并比较“Wanted”和“Latest”版本，然后手动更新 package.json 文件或运行

注意：以上命令仅为示例 - 请根据您使用的包进行调整。

安装 React

在 v1 中，react 和 react-dom 包是 gatsby 包的一部分。在 v2 中，它们现在是 peerDependencies，因此您需要将它们安装到您的项目中。

安装插件的对等依赖项

一些插件的依赖项也成为了 peerDependencies。例如，如果您使用 gatsby-plugin-typography，现在您需要安装

您应该在 插件库 中搜索您使用的插件。然后，查看它们的安装说明，了解可能需要安装的额外软件包。

处理重大变更

移除或重构布局组件

Gatsby 的布局组件（src/layouts/index.js）已移除。“顶层组件”现在是页面本身。如果您的网站布局看起来损坏，这很可能是原因。

此更改带来了一些影响

• 为不同页面渲染不同的布局方式已更改。使用标准的 React 继承模型。Gatsby 不再维护，也不需要维护，用于处理布局的单独行为。

• 由于“顶层组件”在每个页面之间都会更改，React 将重新渲染所有子项。这意味着之前在 Gatsby v1 布局中的共享组件（如导航）将卸载并重新挂载。这将破坏这些共享组件中的 CSS 过渡或 React 状态。如果您的用例需要布局组件不被卸载，请使用 gatsby-plugin-layout。

• 要了解有关移除此功能的决策，请阅读 RFC - 移除特殊布局组件。

我们推荐以下迁移路径

1. 将布局的子项从渲染 prop 转换为普通 prop（必需）

在 v1 中，传递给布局的 children prop 是一个函数（渲染 prop）并且需要被执行。在 v2 中，情况不再如此。

2. 将 layouts/index.js 移动到 src/components/layout.js（可选，但推荐）

3. 导入布局组件并用其包装页面

遵循标准的 React 组合模型，导入您的布局组件，并用它来包装页面的内容。

对需要此布局的每个页面和模板重复此操作。

4. 将 history、location 和 match props 传递给 layout

在 v1 中，布局组件可以访问 history、location 和 match props。在 v2 中，只有页面可以访问这些 props。如果您需要在布局组件中使用这些 props，请通过页面传递它们。

5. 更改查询以使用 StaticQuery

如果您在 Gatsby v1 布局中使用了 data prop，现在需要使用 Gatsby v2 的 StaticQuery 功能。这是因为布局现在是一个普通组件。

用 StaticQuery 替换布局的查询

将 navigateTo 改为 navigate

gatsby-link 中的 navigateTo 方法已被重命名为 navigate，以反映 @reach/router 使用的 API。

除了名称更改之外，gatsby-link 现在从 gatsby 包导出，无法直接安装。

转换为纯 CommonJS 或纯 ES6

Gatsby v2 使用 webpack 4，它对混合模块系统的模块更严格。

所有 ES6 是 好的

所有 CommonJS 是 好的

混合使用 requires 和 export 是 不好的

混合使用 import 和 module.exports 是 不好的

移动 Babel 配置

最新版本的 Gatsby 使用 Babel 7。Babel 7 引入了 配置查找/解析的新行为。在项目根目录可能使用 .babelrc 文件（例如用于配置 Jest）的情况下，将该 Babel 配置移至 jest.config.json 将避免任何冲突。

此 GitHub 评论记录了执行此操作所需的步骤。

有关 Gatsby 和 Babel 配置的更多信息，请在此 处 查阅。

恢复 v1 PostCSS 插件设置

Gatsby v2 移除了默认 PostCSS 设置中的 postcss-cssnext 和 postcss-import。

使用 gatsby-plugin-postcss 来获得与 v1 相同的配置。

1. 安装依赖项

npm install gatsby-plugin-postcss postcss-import postcss-cssnext postcss-browser-reporter postcss-reporter

注意：postcss-cssnext 已弃用，最好使用 postcss-preset-env。

2. 在你的 gatsby-config.js 文件中包含 gatsby-plugin-postcss

3. 在你的 postcss.config.js 文件中包含 PostCSS 插件

从 React Router 迁移到 @reach/router

我们将路由库从 React Router v4 切换到了 @reach/router，因为 @reach/router 更小，并且具有一流的可访问性支持。

React Router 的创始人 Ryan Florence 也是 @reach/router 的创始人。

他表示 @reach/router 恢复了他怀念的 React Router v3 的一些特性。@reach/router 也保留了 React Router v4 的最佳部分，并且增加了完整的可访问性支持。

对于 大多数 网站来说，此更改不会导致任何破坏性更改，因为这两个路由库非常相似。

此更改 可能 破坏您网站的两种常见方式是：

• 您在 <Link> 组件中使用了 to prop 的对象形式
• 您有客户端路由

在 https://reach.tech/router 阅读有关我们新路由功能的更多信息。

注意： @reach/router 的一个突出功能，相对路由，目前在 Gatsby 中无法正常工作。我们正在与 Ryan Florence 合作，希望能尽快支持它。

继续阅读有关将您的网站迁移到 @reach/router 的说明。

只允许字符串 to

React Router 允许您将对象传递给 to prop，例如：

React Router 会将对象值连接成完整的路径名，例如 /about/?fun=true&pizza=false#people。

现在您需要自己连接完整的路径名。

将 state 传递给 state prop

以前使用 React Router，您会将其作为 to 对象 prop 的一部分传递 state：

现在，要向链接添加 state，请通过 state prop 传递。

不再将 history prop 传递给页面组件

React Router 会将 history prop 传递给您可以用来导航的组件。

如果您需要进行编程导航，请改用 @reach/router 的 navigate 函数。

<Link> 上不再提供以下 props

• exact
• strict
• location

exact 和 strict 不再是必需的，因为 @reach/router 默认会进行此方式的匹配。

您以前可以传递 location 来手动计算链接是否处于活动状态。对于更高级的链接样式，现在请使用 getProps。

使用 getProps 进行高级链接样式设置

Gatsby 的 <Link> 组件开箱即用地支持 activeClassName 和 activeStyle。

如果您有更高级的样式需求，请使用 getProps prop。

更改客户端路径以使用 splat

在 gatsby-node.js 中创建客户端路由时，使用 * 来选择所有子路由，而不是 :path。

迁移 React Router 客户端路由到 @reach/router

• 使用 <Location> 代替 withRouter
• 使用 import { navigate } from @reach/router 进行编程导航，而不是使用 history 对象
• 不再有 Route 组件。您可以添加一个 <Router> 组件（一个站点可以拥有任意数量的路由）。然后确保 <Router> 的直接子项有一个名为 path 的 prop。

基本的 <Router> 组件示例

这是一个更复杂的例子，演示了如何将 store.gatsbyjs.org 中使用的 <PrivateRoute> 组件从 React Router 迁移到 @reach/router。

以下是三个具有已升级到 @reach/router 的客户端路由的网站 diff 的链接

• store.gatsbyjs.org
• client-only-routes
• simple-auth

APIs onPreRouteUpdate 和 onRouteUpdate 不再通过路由更新操作调用

React Router v4 会告诉我们触发路由转换的“操作”（push/replace）。我们会将此作为参数之一，与 location 一起传递给插件。@reach/router 不支持此功能，因此我们已将其从 API 调用中移除。

浏览器 API replaceRouterComponent 已被移除

@reach/router 不允许你像 React Router 那样替换其 history 对象。在 Gatsby 中，曾使用一个名为 replaceRouterComponent 的 API 来实现此行为。现在它已不再需要，因此我们已移除此 API。

我们曾错误地建议使用此 API 来添加对 Redux 等的支持，这些场景需要用你的组件包装根 Gatsby 组件。

如果你曾使用 replaceRouterComponent 来实现此目的，则需要迁移到 wrapRootElement。

浏览器 API replaceHistory 已被移除

与 replaceRouterComponent 类似，我们不再支持自定义 history。这就是为什么我们还移除了 replaceHistory API。 replaceHistory() 方法曾用于通过 history.listen() 注册路由变更监听器来跟踪页面视图。

现在，要跟踪页面视图，可以使用 onRouteUpdate API 来跟踪页面更改。

浏览器 API wrapRootComponent 已被 wrapRootElement 替换

使用新的 wrapRootElement API：我们现在传递 component 元素而不是 Root 组件，并期望 wrapRootElement 返回元素而不是组件。此更改是为了使所有包装 API 保持一致。

不要按 ID 查询节点

Source 和 transformer 插件现在使用 UUID 作为 ID。如果你使用 glob 或 regex 按 ID 查询节点，则需要查询其他内容。

以下是一个查询图像的示例

查看实现此更改的 Pull Request

使用 Query 替换 RootQueryType

我们将 GraphQL 的根类型从 RootQueryType 更改为 Query。这可能只会影响到你在 GraphQL 查询中有顶级 fragment 的情况。

Typography.js 插件配置更改

如果你使用 gatsby-plugin-typography，现在需要显式地从你的 typography 配置文件模块中导出 scale 和 rhythm 作为命名导出。

更新使用连字符的 CSS Modules 类名

如果你使用 CSS Modules 并且类名中包含连字符，你需要更改从 JavaScript 中访问类名的方式。

这是因为 CSS Modules 的 camelCase 选项已从 false 更改为 dashesOnly。

以下是一个类名为 .my-class-name 的示例

可以通过调整 CSS Loader 选项来恢复 Gatsby v1 的行为。

对于没有预处理器的普通 CSS

如果你使用的是预处理器，可以在配置 gatsby-plugin-sass 或 gatsby-plugin-less 时传递 CSS Loader 选项。

更新 Jest 配置

如果你之前使用 Jest 和 Gatsby V1，在升级到 Gatsby V2 时需要更新你的配置。你可以在文档的 单元测试 页面上查看设置测试环境的完整细节。

gatsby-image 的 outerWrapperClassName 已被移除

由于移除了外部包装 div，你不再可以使用 outerWrapperClassName prop 来为你的图片设置样式。你应该将这些样式合并到你的 wrapper 的 class 中。

如果你创建了任何 CSS 样式规则引用 gatsby-image-outer-wrapper 类，你应该将这些样式合并到 gatsby-image-wrapper 类中。

解决弃用项

从 Gatsby 导入 Link

gatsby-link 中的所有组件和实用函数现在都从 gatsby 包中导出。因此，你应该直接从 gatsby 导入它。

此外，你可以从 package.json 中移除 gatsby-link 包。

从 Gatsby 导入 GraphQL

Gatsby v1 自动支持的 graphql 标签函数在 v2 中已弃用。Gatsby 会抛出弃用警告，除非你从 gatsby 包中显式导入它。

有一个 codemod 可以自动对你的项目进行此更改。查看 gatsby-codemods 包以获取使用说明。

请注意，如果你依赖 WebStorm 或 VSCode 的自动导入功能，它可能会从 'graphql' 而不是 'gatsby' 导入 graphql。这会引发一系列关于错误导入的错误。请确保 graphql 始终从 gatsby 导入。

将 boundActionCreators 重命名为 actions

boundActionCreators 在 v2 中已弃用。你可以继续使用它，但建议将其重命名为 actions。

将 pathContext 重命名为 pageContext

与上面的 boundActionCreators 一样，pathContext 已弃用，建议使用 pageContext。

重命名响应式图片查询

sizes 和 resolutions 查询在 v2 中已弃用。这些查询已重命名为 fluid 和 fixed，以便更容易理解。你可以继续使用已弃用的查询名称，但建议更新它们。

更新图片查询和 fragment 名称

你可以在 Gatsby Image 文档中找到更多示例。

Delete Nodes API 弃用

deleteNodes 现在已弃用，取而代之的是你应该编写 nodes.forEach(n => deleteNode({ node: n }))。

其他值得注意的更改

不再需要显式查询名称

Gatsby v2 不需要显式查询名称。你现在可以省略它们。

如果你不使用查询变量，你也可以省略 query 关键字。

这不是一个破坏性更改。具有显式名称的查询将继续按 v1 中的方式工作。

移除 html.js 中内联的 CSS

Gatsby v2 会自动内联你的 CSS。你可以移除自定义 html.js 中任何自定义的 CSS 内联。除非你特意用于其他目的，否则你也可以移除 html.js 本身。

请参阅 此 PR 中的示例，该 PR 将 using-remark 网站升级到了 Gatsby v2。

移除显式 polyfills

如果你的 Gatsby v1 站点包含了任何 polyfills，你可以将它们移除。Gatsby v2 附带 Babel 7，并配置为自动包含你的代码的 polyfills。请参阅 Gatsby 的 Babel 文档以获取更多详细信息。

对于插件维护者

在大多数情况下，你无需做任何事情即可兼容 v2，但有一些事情可以确保你的插件能很好地与 v2 站点配合使用。

设置正确的对等依赖项

gatsby 应包含在您插件的 peerDependencies 中，并且应指定正确的支持版本。

将 modifyBabelrc 更改为 onCreateBabelConfig

我们将 modifyBabelrc 重命名为 onCreateBabelConfig，以使其与 Gatsby 的其他 API 名称保持一致。

使用 onCreateBabelConfig

注意使用新的 setBabelPlugin action。

有关配置 Babel 的更多详细信息，请参阅 Gatsby 的 Babel 文档。

将 modifyWebpackConfig 更改为 onCreateWebpackConfig

我们将 modifyWebpackConfig 重命名为 onCreateWebpackConfig，以使其与 Gatsby 的其他 API 名称保持一致。

使用 onCreateWebpackConfig

注意使用新的 setWebpackConfig action。

有关配置 webpack 的更多详细信息，请参阅 Gatsby 的 webpack 文档。

createRemoteFileNode

createRemoteFileNode 的使用签名在 v2 中发生了变化，它现在需要一个新参数 createNodeId。

有关 createRemoteFileNode 的文档

只允许在 node internal 对象上使用已定义的键

node 的 internal 对象不用于添加 node 数据。虽然 Gatsby v1 允许此行为，但我们在 v2 中对其进行了验证。node 数据应作为字段添加到顶层 node 对象上。

请参阅 Node interface 文档以了解允许的字段。

从 gatsby/graphql 导入 graphql 类型

从 gatsby/graphql 导入 GraphQL 类型，以防止出现 Schema must contain unique named types but contains multiple types named "<typename>" 错误。 gatsby/graphql 导出了所有内置 GraphQL 类型以及 graphQLJSON 类型。

如果你正在使用 Flowtype，请添加 gatsby-plugin-flow

我们从 Gatsby 的默认 Babel 配置中移除了 @babel/preset-flow，以便更轻松地允许用户选择自己的转译器。如果你的站点有自己的 .babelrc 文件并且已包含 Flow 预设，则无需更改。否则，你应该安装 gatsby-plugin-flow。

对于探索者

用 v2 开始新项目

这里有一个关于用 Gatsby v2 开始新项目而不是升级现有项目的简短部分。

从零开始：如果你是“从零开始”类型的人，你可以这样安装 Gatsby 和 React： npm install gatsby react react-dom

教程：如果你想要一个循序渐进的指南，请 按照教程 开始使用 Gatsby v2。

Starters：如果你更喜欢使用官方 starters 之一，可以使用 Gatsby CLI 安装你喜欢的 starter。

gatsby-starter-default (v2)

gatsby-starter-hello-world (v2)

gatsby-starter-blog (v2)