Gatsby项目构建失败：dev正常启动但build报fallback未定义错误

问题描述 #

执行gatsby develop时项目可正常启动，但运行gatsby build时触发HTML编译错误。已尝试以下操作但未解决：

• 重新安装依赖
• 切换yarn与npm
• 在Gatsby Cloud、Netlify及本地环境构建
• 删除node_modules和package-lock.json

报错信息 #

ERROR  UNKNOWN

Truncated page data information for the failed page "/": {
  "errors": {},
  "path": "/",
  "slicesMap": {},
  "pageContext": {}
}

failed Building static HTML for pages - 8.327s

 ERROR #95313  HTML.COMPILATION

Building static HTML failed for path "/"

See our docs page for more info on this error: https://gatsby.dev/debug-html


  WebpackError: TypeError: Cannot read properties of undefined (reading 'fallback')

 - gatsby-image.server.tsx:62 
    webpack:/gatsby-starter-default/src/components/gatsby-image.server.tsx:62:16

  - index.esm.js:40 
    [gatsby-starter-default]/[react-icons]/ai/index.esm.js:40:39

  - index.esm.js:42 
    [gatsby-starter-default]/[react-icons]/ai/index.esm.js:42:8

  - index.esm.js:48 
    [gatsby-starter-default]/[react-icons]/ai/index.esm.js:48:8

  - index.esm.js:51 
    [gatsby-starter-default]/[react-icons]/ai/index.esm.js:51:8

项目配置文件 #

gatsby-config.js #

/**
 * Configure your Gatsby site with this file.
 *
 * See: https://www.gatsbyjs.com/docs/reference/config-files/gatsby-config/
 */

/**
 * @type {import('gatsby').GatsbyConfig}
 */
module.exports = {
  siteMetadata: {
    title: `project`,
    description: ``,
    author: `@author`,
    siteUrl: `https://gatsbystarterdefaultsource.gatsbyjs.io/`,
  },
  flags: {
    DEV_SSR: true
  },
  plugins: [
    {
      resolve: "gatsby-source-wordpress",
      options: {
        url: ``,
        schema: {
          timeout: 1000000,
          perPage: 10,
          requestConcurrency: 5,
        },
      },
    },
    `gatsby-plugin-image`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-default`,
        short_name: `starter`,
        start_url: `/`,
        background_color: `#663399`,
        // This will impact how browsers show your PWA/website
        // https://css-tricks.com/meta-theme-color-and-trickery/
        // theme_color: `#663399`,
        display: `minimal-ui`,
        icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
      },
    },
    {
      resolve: '@chakra-ui/gatsby-plugin',
      options: {
        /**
         * @property {boolean} [resetCSS=true]
         * if false, this plugin will not use `<CSSReset />
         */
        resetCSS: true,
        /**
         * @property {boolean} [isUsingColorMode=true]
         * if false, this plugin will not use <ColorModeProvider />
         */
        isUsingColorMode: true,
      },
    },
    `gatsby-plugin-transition-link`
  ],
}

package.json #

{
  "name": "gatsby-starter-default",
  "private": true,
  "description": "A simple starter to get up and developing quickly with Gatsby",
  "version": "0.1.0",
  "author": "Kyle Mathews <mathews.kyle@gmail.com>",
  "dependencies": {
    "@chakra-ui/gatsby-plugin": "^3.1.1",
    "@chakra-ui/react": "^2.4.6",
    "@emotion/react": "^11.10.5",
    "@emotion/styled": "^11.10.5",
    "@fontsource/kaushan-script": "^4.5.10",
    "@fontsource/mulish": "^4.5.13",
    "@fontsource/spartan": "^4.5.8",
    "firebase": "^9.15.0",
    "formik": "^2.2.9",
    "framer-motion": "^8.1.3",
    "gatsby": "^5.3.3",
    "gatsby-image": "^3.11.0",
    "gatsby-plugin-image": "^3.3.2",
    "gatsby-plugin-manifest": "^5.3.1",
    "gatsby-plugin-sharp": "^5.3.2",
    "gatsby-source-filesystem": "^5.3.1",
    "gatsby-source-wordpress": "^7.3.2",
    "gatsby-transformer-sharp": "^5.3.1",
    "gsap": "^3.11.4",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-icons": "^4.7.1",
    "react-scroll-parallax": "^3.3.2",
    "webpack": "^5.75.0"
  },
  "devDependencies": {
    "prettier": "^2.8.0"
  },
  "keywords": [
    "gatsby"
  ],
  "license": "0BSD",
  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop",
    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,css}\"",
    "start": "gatsby develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/gatsbyjs/gatsby-starter-default"
  },
  "bugs": {
    "url": "https://github.com/gatsbyjs/gatsby/issues"
  }
}

问题分析与解决步骤 #

核心问题定位 #

报错指向Cannot read properties of undefined (reading 'fallback')，根源在于：

1. 依赖版本冲突：项目同时安装了gatsby-image（v3.11.0）和gatsby-plugin-image（v5.3.2），而Gatsby v5已废弃gatsby-image，两者共存会导致服务端渲染时的逻辑冲突。
2. react-icons服务端渲染兼容性：部分图标库在SSR过程中可能因为依赖浏览器环境（如window对象）出现未定义错误。

解决步骤 #

1. 移除废弃的gatsby-image依赖
   执行命令卸载旧包：

   npm uninstall gatsby-image
   # 或使用yarn
   yarn remove gatsby-image
   

2. 替换代码中的gatsby-image导入
   将所有组件中旧的导入语句：

   import { StaticImage, GatsbyImage } from 'gatsby-image'
   

   替换为：

   import { StaticImage, GatsbyImage } from 'gatsby-plugin-image'
   

3. 修复react-icons的SSR问题
   若图标组件在SSR时出错，可通过动态导入或条件渲染规避：

   import { useEffect, useState } from 'react'
   import { AiFillHome } from 'react-icons/ai'
   
   const HomeIcon = () => {
     const [Icon, setIcon] = useState(null)
   
     useEffect(() => {
       setIcon(AiFillHome)
     }, [])
   
     if (!Icon) return null
     return <Icon />
   }
   
   export default HomeIcon
   

4. 清理并重新安装依赖

   rm -rf node_modules package-lock.json
   npm install
   # 或yarn
   rm -rf node_modules yarn.lock
   yarn install
   

5. 重新构建项目

   gatsby clean && gatsby build
   

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