使用gatsby-background-image插件在生产环境触发React错误#418

刚接触Gatsby，开发环境运行正常，但执行gatsby build和gatsby serve后，浏览器抛出以下错误：

react-dom.production.min.js:131 Uncaught Error: Minified React error #418; 查看未压缩的开发环境可获取完整错误及警告。
at sa (react-dom.production.min.js:131:159)
at Ei (react-dom.production.min.js:293:379)
at ks (react-dom.production.min.js:280:389)
at ys (react-dom.production.min.js:280:320)
at vs (react-dom.production.min.js:280:180)
at as (react-dom.production.min.js:268:209)
at S (scheduler.production.min.js:13:203)
at MessagePort.T (scheduler.production.min.js:14:128)

排查后发现，移除gatsby-background-image插件错误就消失。为验证问题，通过npm init gatsby新建空项目并编写测试代码，执行gatsby build后仍出现相同错误。

环境信息：

• Node版本：v18.12.1

测试用index.js代码：

import * as React from "react";
import { graphql } from "gatsby";
import BackgroundImage from "gatsby-background-image";

const pageStyles = {
  color: "#232129",
  padding: 96,
  fontFamily: "-apple-system, Roboto, sans-serif, serif",
};

const bgImage = {
  minHeight: "100vh",
  backgroundPosition: "center",
  backgroundAttachment: "fixed",
  backgroundSize: "cover",
  backgroundRepeat: "no-repeat",
  display: "flex",
  justifyContent: "center",
  alignItems: "center",
};


const IndexPage = ({ data }) => {
  const imageData = data.imageBcg.childImageSharp.fluid;
  return (
    <main style={pageStyles}>
      <BackgroundImage Tag="section" fluid={imageData} style={bgImage}>
        <h2>gatsby-background-image</h2>
      </BackgroundImage>
    </main>
  );
};

export default IndexPage;

export const Head = () => <title>Home Page</title>;

export const query = graphql`
  query {
    imageBcg: file(relativePath: { eq: "bouq.jpg" }) {
      childImageSharp {
        fluid(quality: 90, maxWidth: 1920) {
          ...GatsbyImageSharpFluid_withWebp
        }
      }
    }
  }
`;

package.json配置：

{
  "name": "my-gatsby-site",
  "version": "1.0.0",
  "private": true,
  "description": "my-gatsby-site",
  "keywords": [
    "gatsby"
  ],
  "scripts": {
    "develop": "gatsby develop",
    "start": "gatsby develop",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "clean": "gatsby clean"
  },
  "dependencies": {
    "babel-plugin-styled-components": "^2.0.7",
    "gatsby": "^5.7.0",
    "gatsby-background-image": "^1.6.0",
    "gatsby-plugin-image": "^3.7.0",
    "gatsby-plugin-sharp": "^5.7.0",
    "gatsby-plugin-styled-components": "^6.7.0",
    "gatsby-source-filesystem": "^5.7.0",
    "gatsby-transformer-sharp": "^5.7.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "styled-components": "^5.3.8"
  }
} 

解决方法：

问题根源是使用的gatsby-background-image@1.6.0版本仅兼容Gatsby 3及更早版本，而当前项目使用Gatsby 5 + React 18，版本不匹配导致生产环境渲染错误。提供两种可行方案：

1. 升级到兼容Gatsby5的gatsby-background-image版本
   卸载旧版本，安装最新兼容版：

   npm uninstall gatsby-background-image
   npm install gatsby-background-image@^3.1.1
   

2. 改用Gatsby官方的BackgroundImage组件
   Gatsby 5推荐使用官方gatsby-plugin-image提供的BackgroundImage组件，兼容性更好。修改代码如下：

   import * as React from "react";
   import { graphql } from "gatsby";
   import { BackgroundImage } from "gatsby-plugin-image";
   
   const pageStyles = {
     color: "#232129",
     padding: 96,
     fontFamily: "-apple-system, Roboto, sans-serif, serif",
   };
   
   const bgImage = {
     minHeight: "100vh",
     backgroundPosition: "center",
     backgroundAttachment: "fixed",
     backgroundSize: "cover",
     backgroundRepeat: "no-repeat",
     display: "flex",
     justifyContent: "center",
     alignItems: "center",
   };
   
   
   const IndexPage = ({ data }) => {
     const imageData = data.imageBcg.childImageSharp.gatsbyImageData;
     return (
       <main style={pageStyles}>
         <BackgroundImage
           image={imageData}
           style={bgImage}
           tag="section"
         >
           <h2>gatsby-plugin-image BackgroundImage</h2>
         </BackgroundImage>
       </main>
     );
   };
   
   export default IndexPage;
   
   export const Head = () => <title>Home Page</title>;
   
   export const query = graphql`
     query {
       imageBcg: file(relativePath: { eq: "bouq.jpg" }) {
         childImageSharp {
           gatsbyImageData(quality: 90, width: 1920)
         }
       }
     }
   `;
   

   注意：官方组件使用gatsbyImageData查询而非fluid，传入props为image而非fluid。

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