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

1162 字

6 分钟

Gatsby迁移指南:v2 To v3

2023-07-26

前端

/

gatsby

NOTE
官方迁移指南

TIP
对于拥有一定影响力的开源项目而言，可在 npm 官网查找它在某个大版本下的最新版本（带 lts/latest 标记）。

例如，查询 Node v16 和 Gatsby v3 下的最新版：

version-node

version-gatsby

提升 Node 版本上限#

:::danger 镜像由于 CI 配置中调用了 rsync 包的相关命令，因此需要自行构建一个包含 rsync 模块的新镜像。 :::

1
image: node:10.18.1-rsync
2
image: node:16.19.1-rsync

1
{
2
  "name": "root",
3
  "version": "0.1.0",
4
  "engines": {
5
   "node": "10.18.1"
6
   "node": ">= 16"
7
  }
8
  // ...
9
}

升级 Gatsby 及其相关插件#

由于这些依赖为整个 monorepo 项目共用，因此安装时加上-W参数将其提升至项目根部的 package.json 中。

1
yarn add -W \
2
gatsby@^3.15.0 \
3
gatsby-plugin-image@^1.15.0 \
4
gatsby-plugin-sharp@^3.15.0 \
5
gatsby-plugin-sitemap@^4.11.0 \
6
gatsby-plugin-react-helmet@^4.15.0 \
7
gatsby-plugin-styled-components@^4.15.0 \
8
gatsby-source-filesystem@^3.15.0 \
9
gatsby-source-contentful@^5.15.0 \
10
gatsby-transformer-sharp@^3.15.0

:::info 依赖安装策略实际上在使用 npm/Yarn 等包管理器为 monorepo 项目安装依赖时，默认会将除可执行文件（.bin）之外的所有依赖包都安装到项目<根>目录下的 node_modules 中，此处仅提升公共依赖的「声明位置」以减少多个 package.json 文件维护同一份依赖版本数据的心智负担。 :::

问题处置#

路由导航错误#

1
import { navigate } from "gatsby";
2

3
navigate(path);

在旧版中，Gatsby 默认会对传给navigate方法的path参数中多余的/进行去重处理：

1
//path//xxx -> /path/xxx

而在新版中，移除了这一默认行为，若path存在多余的/则会导致路由导航错误，因此需自行对path做规范化处理：

1
import { navigate } from "gatsby";
2

3
/**
4
 * @param {string} path navigate path
5
 */
6
function normalizePath(path) {
7
  return path.replace(/\/+/g, `/`);
8
}
9

10
navigate(normalizePath(path));

依赖相关问题#

❗️❗️❗️ 添补http-proxy-middleware依赖与配置，解决本地代理错误问题：

proxy-error

1
yarn add -W -D http-proxy-middleware

1
 const { createProxyMiddleware } = require('http-proxy-middleware')
2

3
 const middleware = createProxyMiddleware({ secure: false, target: 'https://xxx.xxx.xxx' })
4

5
/** @type {import("gatsby").GatsbyConfig} */
6
module.exports = {
7
 proxy: [
8
   { url: 'https://xxx.xxx.xxx', prefix: '/api-xxx-1' },
9
   { url: 'https://xxx.xxx.xxx', prefix: '/api-xxx-2' },
10
 ],
11
 developMiddleware: (app) => app.use('/api-xxx-1', middleware).use('/app-xxx-2', middleware),
12
}

❗️❗️❗️ 移除@hot-loader/react-dom依赖与配置，目前已无用：

1
exports.onCreateWebpackConfig = ({ getConfig, stage }) => {
2
  const config = getConfig()
3

4
  if (stage.startsWith('develop') && config.resolve) {
5
    config.resolve.alias = {
6
      ...config.resolve.alias,
7
      'react-dom': '@hot-loader/react-dom',
8
    }
9
  }
10
}

❗️❗️❗️ 添补gatsby-plugin-compile-es6-packages依赖与配置，以解决在 Gatsby v3 版本下，插件gatsby-plugin-image在 monorepo 项目里不能正常运作的问题：

1
yarn add -W gatsby-plugin-compile-es6-packages

1
module.exports = {
2
  plugins: [
3
    {
4
      resolve: "gatsby-plugin-compile-es6-packages",
5
      options: {
6
        modules: ["gatsby-plugin-image"],
7
      },
8
    },
9
  ],
10
};

❗️❗️❗️ 由于 Webpack v5 版本不再提供自动引入 Node 模块对应的 polyfills 功能，因此需自行添加依赖与配置：

webpack-polyfills

1
yarn add -W -D process path-browserify

1
/**
2
 * @typedef {import("webpack").Configuration} WebpackConfiguration
3
 */
4

5
/** @type {(config: WebpackConfiguration) => WebpackConfiguration} */
6
const defineWebpackConfig = (config) => config;
7

8
/** @type {(args: import("gatsby").CreateWebpackConfigArgs) => void} */
9
exports.onCreateWebpackConfig = ({ stage, actions, plugins }) => {
10
  const config = defineWebpackConfig({
11
    plugins: [],
12
    resolve: {
13
      fallback: {
14
        path: require.resolve("path-browserify"),
15
      },
16
    },
17
  });
18

19
  if (stage === "develop" || stage === "build-javascript") {
20
    config.plugins?.push(plugins.provide({ process: "process/browser" }));
21
  }
22

23
  actions.setWebpackConfig(config);
24
};

迁移 gatsby-plugin-image#

TIP
官方迁移指南：https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide/
官方插件文档：https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/

Step 1 - 配置添补

1
module.exports = {
2
  plugins: [
3
    // ...
4
    "gatsby-plugin-image",
5
  ],
6
};

Step 2 - 导入变更

1
import Img from 'gatsby-image'
2
import { GatsbyImage } from 'gatsby-plugin-image'

Step 3 - 查询变更

1
query {
2
  banner: file(relativePath: { eq: "xxx/xxx.png" }) {
3
   childImageSharp {
4
     fluid(maxWidth: 1920, quality: 100) {
5
       ...GatsbyImageSharpFluid
6
     }
7

8
     gatsbyImageData(quality: 100)
9
    }
10
  }
11
}

Step 4 - 使用变更

1
 import { getImageData } from 'gatsby-plugin-image'
2

3
function Comp() {
4
  return (
5
    <Fragment>
6
     <GatsbyImage fluid={banner.childImageSharp.fluid} />
7

8
      {/* 需要必传 alt 属性 */}
9
     <GatsbyImage alt="xxx-xxx" image={getImageData(banner)} />
10

11
      {/* or */}
12
     <GatsbyImage alt="xxx-xxx" image={banner.childImageSharp.gatsbyImageData} />
13
    </Fragment>
14
  )
15
}

1
<GatsbyImage
2
  fluid={[
3
    data.bannerMb.childImageSharp.fluid,
4
    {
5
      ...data.banner.childImageSharp.fluid,
6
      media: `(min-width: 813px)`,
7
    },
8
  ]}
9
/>
10

11
<GatsbyImage
12
  alt='xxx-banner'
13
  image={isSmall ? getImageData(data.bannerMb) : getImageData(data.banner)}
14
/>

迁移 gatsby-plugin-sitemap#

Step 1 - 配置变更

1
module.exports = {
2
  plugins: [
3
    {
4
      resolve: 'gatsby-plugin-sitemap',
5
      options: {
6
       exclude: ['*/404/', '*/404.html'],
7
       excludes: ['*/404/', '*/404.html'],
8
      },
9
    },
10
  ],
11
}

Step 2 - 规则变更

:::danger 站点地图抓取规则插件gatsby-plugin-sitemap在新版本中遵循了索引文件的定义规范，改变了创建 sitemap.xml 的规则：

旧规则：直接创建一个 xxx-sitemap.xml 文件。

新规则：先对 URL 条目进行拆分，每 45000 条拆分为一个 xxx-sitemap-0.xml 文件，以此类推 1-2-3-…，最后再创建一个 sitemap-index.xml 索引文件，重定向到拆分后的 xml 文件。 :::

baidu-sitemap-failure

由于百度不支持 sitemap-index.xml 这类索引文件的重定向（据说是为了打击非法产业与泛目录类网站），并且gatsby-plugin-sitemap也无选项可配置回退旧规则，因此需与营销同事协调改动。

Step 2.1 - 配置变更

由于规则从直接创建文件调整为了文件拆分，因此输出的是一个目录，对输出地址做语义化处理：

1
module.exports = {
2
  plugins: [
3
    {
4
      resolve: 'gatsby-plugin-sitemap',
5
      options: {
6
       output: `/xxx-sitemap.xml`,
7
       output: `/xxx-sitemap`,
8
      },
9
    },
10
  ],
11
}

Step 2.2 - 上传地址

打包后输出的目录结构如下所示：

1
public
2
└─ xxx-sitemap
3
     ├─ sitemap-0.xml
4
     └─ sitemap-index.xml

需要营销同事重新上传此地址，例如：https://domain/package-name/xxx-sitemap/sitemap-0.xml。

baidu-sitemap-success

Gatsby迁移指南:v2 To v3

https://www.hzhi.top/posts/gatsby-v2-to-v3/

作者

Jim的独立博客

发布于

2023-07-26

许可协议

CC BY-NC-SA 4.0

Gatsby迁移指南:v3 To v4

3DCAT 官网首页优化记录-网络优化

迁移 gatsby-plugin-image

迁移 gatsby-plugin-sitemap