Gatsby迁移指南:v3 To v4 - Jim的独立博客

655 字

3 分钟

Gatsby迁移指南:v3 To v4

2023-08-01

前端

/

gatsby

NOTE
官方迁移指南

NOTE
书接上回 Gatsby 迁移指南: v2 To v3

升级 Gatsby 及其相关插件#

1
yarn add -W \
2
gatsby@^4.25.7 \
3
gatsby-plugin-image@^2.25.0 \
4
gatsby-plugin-sharp@^4.25.1 \
5
gatsby-plugin-sitemap@^5.25.0 \
6
gatsby-plugin-page-creator@^4.25.0 \
7
gatsby-plugin-styled-components@^5.25.0 \
8
gatsby-source-filesystem@^4.25.0 \
9
gatsby-source-contentful@^7.23.1 \
10
gatsby-transformer-sharp@^4.25.0

问题处置#

编译转换#

Gatsby v4 版本可以启用新的 JSX 转换功能，即引入 React 不再是必须的：

1
import React from "react";

但该转换配置默认为禁用模式，当一个组件未导入 React 时会报以下错误（看似毫不相干）：

jsx-transform

补充配置即可：

1
/** @type {import("gatsby").GatsbyConfig} */
2
module.exports = {
3
  jsxRuntime: "automatic",
4
};

Optional 1 - 若使用了ESLint做代码校验，需添加插件eslint-plugin-react的扩展规则react/jsx-runtime，禁用检查：

1
extends:
2
  # ...
3
  - plugin:react/jsx-runtime
4
  # ...

Optional 2 - 若使用了@svgr/cli转换 SVG 图标，需添加命令行参数--jsx-runtime=automatic启用新的转换规则（相应的@svgr/cli需要更新到 v6 版本以上），禁止生成 React 导入：

1
{
2
 "svg": "npx @svgr/cli svg-dir --out-dir=xxx --ext=jsx --filename-case=kebab"
3
 "svg": "npx @svgr/cli svg-dir --out-dir=xxx --ext=jsx --filename-case=kebab --jsx-runtime=automatic"
4
}

依赖弃用#

移除gatsby-plugin-compile-es6-packages依赖与配置，在上一个版本的升级中引入了该依赖处理图片插件不能正常工作的问题，现已不再需要。

迁移 gatsby-plugin-react-helmet#

由于 react-helmet 已有 3 年未维护更新，同时 Gatsby v4 版本中支持（内置）了类似的解决方案。

Step 1 - 依赖变更

1
{
2
  "name": "root",
3
  "version": "0.1.0",
4
  "dependencies": {
5
   "react-helmet": "^5.2.1",
6
   "gatsby-plugin-react-helmet": "^4.15.0"
7
  }
8
  // ...
9
}

Step 2 - 配置变更

1
/** @type {import("gatsby").GatsbyConfig} */
2
module.exports = {
3
  plugins: [
4
   'gatsby-plugin-react-helmet',
5
    // ...
6
  ],
7
}

Step 3 - 使用变更

:::danger 注意必须在会被创建为 Page 的组件中导出一个具名的 Head 组件（详见）。

以下行为会创建一个页面：

使用createPages钩子创建
通过gatsby-plugin-page-creator插件创建

:::

1
 import Helmet from 'react-helmet'
2
 import { Fragment } from 'react'
3

4
export const SEO = ({ url, title, keywords, canonical, description }) => (
5
 <Helmet title={title}>
6
 <Fragment>
7
   <title>{title}</title>
8
    <meta name="keywords" content={keywords} />
9
    <meta name="canonical" content={canonical} />
10
    <meta name="description" content={description} />
11
    <meta property="og:url" content={url} />
12
    <meta property="og:image:width" content="400" />
13
    <meta property="og:image:height" content="300" />
14
 </Fragment>
15
 </Helmet>
16
)

1
export default function PageComp({ data, pageContext }) {
2
  return (
3
    <Xxx>
4
     <SEO {...props} />
5
    </Xxx>
6
  )
7
}
8

9
 export function Head({ data, pageContext }) {
10
   return <SEO {...props} />
11
 }

迁移 gatsby-plugin-remove-trailing-slashes#

该插件所提供的功能已在 Gatsby v4 版本中内置支持。

Step 1 - 依赖变更

1
{
2
  "name": "root",
3
  "version": "0.1.0",
4
  "dependencies": {
5
   "gatsby-plugin-remove-trailing-slashes": "^2.2.1"
6
  }
7
  // ...
8
}

Step 2 - 配置变更

1
/** @type {import("gatsby").GatsbyConfig} */
2
module.exports = {
3
 trailingSlash: 'never',
4
  plugins: [
5
   'gatsby-plugin-remove-trailing-slashes',
6
    // ...
7
  ],
8
}