Gatsby 4升级至5后构建失败：aa.TextEncoder is not a constructor

问题详情 #

将Gatsby从v4升级到v5后，项目无法完成构建。构建流程在执行到success Building HTML renderer - 16.746s步骤后抛出以下错误：

ERROR UNKNOWN
aa.TextEncoder is not a constructor
TypeError: aa.TextEncoder is not a constructor

错误调用栈 #

• react-server-dom-webpack-writer.node.production.min.server.js:12 Object.6652
  [gatsby-test]/[react-server-dom-webpack]/cjs/react-server-dom-webpack-writer.node.production.min.server.js:12:171
• bootstrap:19 webpack_require
  /Users/smackey/Sites/gatsby/gatsby-test/.cache/page-ssr/routes/webpack:/gatsby-test/webpack/bootstrap:19:1
• writer.node.server.js:4 Object.2442
  [gatsby-test]/[react-server-dom-webpack]/writer.node.server.js:4:3
• bootstrap:19 webpack_require
  /Users/smackey/Sites/gatsby/gatsby-test/.cache/page-ssr/routes/webpack:/gatsby-test/webpack/bootstrap:19:1
• render-page.js:34134
  /Users/smackey/Sites/gatsby/gatsby-test/.cache/page-ssr/routes/render-page.js:34134:101
• render-page.js:34169
  /Users/smackey/Sites/gatsby/gatsby-test/.cache/page-ssr/routes/render-page.js:34169:3
• render-page.js:34174 Object.
  /Users/smackey/Sites/gatsby/gatsby-test/.cache/page-ssr/routes/render-page.js:34174:12
• loader:1275 Module._compile
  node:internal/modules/cjs/loader:1275:14
• loader:1329 Object.Module._extensions..js
  node:internal/modules/cjs/loader:1329:10
• loader:1133 Module.load
  node:internal/modules/cjs/loader:1133:32
• loader:972 Function.Module._load
  node:internal/modules/cjs/loader:972:12
• loader:1157 Module.require
  node:internal/modules/cjs/loader:1157:19
• helpers:119 require
  node:internal/modules/helpers:119:18
• page-mode.ts:124 preparePageTemplateConfigs
  [gatsby-test]/[gatsby]/src/utils/page-mode.ts:124:24
• build.ts:290 build
  [gatsby-test]/[gatsby]/src/commands/build.ts:290:37

未完成任务 #

• not finished Running gatsby-plugin-sharp.IMAGE_PROCESSING jobs - 39.419s
• not finished Execute page configs - 0.206s

项目依赖 #

"@mdx-js/mdx": "^3.0.0",
"@mdx-js/react": "^3.0.0",
"@parcel/namer-default": "^2.10.3",
"@u-wave/react-vimeo": "^0.9.10",
"bootstrap": "^5.1.1",
"gatsby": "^5.12.4",
"gatsby-graphql-sharp": "^1.1.4",
"gatsby-plugin-google-fonts": "^1.0.1",
"gatsby-plugin-google-gtag": "^5.12.3",
"gatsby-plugin-image": "^3.12.3",
"gatsby-plugin-manifest": "^5.12.3",
"gatsby-plugin-mdx": "^5.12.3",
"gatsby-plugin-react-helmet": "^6.12.0",
"gatsby-plugin-react-svg": "^3.3.0",
"gatsby-plugin-sass": "^6.12.3",
"gatsby-plugin-sharp": "^5.12.3",
"gatsby-plugin-sitemap": "^6.12.3",
"gatsby-plugin-transition-link": "^1.20.5",
"gatsby-plugin-use-query-params": "^1.0.1",
"gatsby-source-filesystem": "^5.12.1",
"gatsby-source-graphql": "^5.12.1",
"gatsby-transformer-remark": "^6.12.3",
"gatsby-transformer-sharp": "^5.12.3",
"gsap": "npm:@gsap/shockingly@^3.12.2",
"https-browserify": "^1.0.0",
"marked": "^10.0.0",
"node-sass": "^9.0.0",
"path-browserify": "^1.0.1",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-helmet": "^6.1.0",
"react-hook-form": "^7.48.2",
"react-three-fiber": "^6.0.13",
"react-visibility-sensor": "^5.1.1",
"rfs": "^10.0.0",
"sanitize-html": "^2.11.0",
"sass": "^1.69.5",
"stream-browserify": "^3.0.0",
"stream-http": "^3.2.0",
"swiper": "^7.4.1",
"three": "^0.124.0",
"tty-browserify": "^0.0.1",
"use-query-params": "^1.2.3",
"util": "^0.12.5",
"vanta": "^0.5.22"

排查尝试 #

• 初始化全新Gatsby项目并安装上述所有依赖，可正常完成构建
• 将原有项目代码复制到全新项目后，构建再次触发相同错误

解决方案 #

问题根源在于gatsby-node.js中遗留的自定义Webpack配置，该配置在Gatsby v4中可用，但在v5中已不再兼容：

exports.onCreateWebpackConfig = ({
  actions,
}) => {
  const { setWebpackConfig } = actions;
  setWebpackConfig({
    externals: {
      jquery: 'jQuery',
    },
    node: {
      fs: "empty",
    },
    resolve: {
      fallback: {
        "path": require.resolve("path-browserify"),
        "stream": require.resolve("stream-browserify"),
        "util": require.resolve("util/"),
        "fs": false,
        "http": require.resolve("stream-http"),
        "https": require.resolve("https-browserify"),
        "tty": require.resolve("tty-browserify"),
        "zlib": false,
        "crypto": false,
        "url": false
      }
    }
  })
}

移除这段自定义Webpack配置，使用Gatsby v5的默认Webpack配置后，构建错误消失，项目可正常完成构建。

内容的提问来源于stack exchange，提问作者Steve Mackey