Gatsby构建报错：HTML编译时'document'未定义求助

问题概述 #

运行gatsby develop正常，但执行gatsby build时触发HTML编译错误，提示服务端渲染阶段document对象不可用。已尝试重装依赖、清理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 - 13.248s

 ERROR #95312  HTML.COMPILATION

"document" is not available during server-side rendering. Enable "DEV_SSR" to
  debug this during "gatsby develop".

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

  WebpackError: ReferenceError: document is not defined

项目配置 #

package.json #

{
  "name": "Test Project",
  "author": "Akila Gunasekara",
  "version": "1.1.0",
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build",
    "start": "gatsby develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
  },
  "dependencies": {
    "@emotion/react": "^11.11.1",
    "@emotion/styled": "^11.11.0",
    "@gatsbyjs/reach-router": "^2.0.1",
    "@mui/icons-material": "^5.14.19",
    "@mui/material": "^5.14.20",
    "animate.css": "^4.1.1",
    "gatsby": "^5.12.12",
    "gatsby-link": "^5.12.1",
    "gatsby-plugin-emotion": "^7.25.0",
    "gatsby-plugin-image": "^3.12.3",
    "gatsby-plugin-manifest": "^5.13.1",
    "gatsby-plugin-postcss": "^6.12.0",
    "gatsby-plugin-react-helmet": "^6.12.0",
    "gatsby-plugin-sharp": "^5.12.3",
    "gatsby-react-router-scroll": "^6.12.0",
    "gatsby-script": "^2.12.0",
    "gatsby-source-filesystem": "^5.12.1",
    "gatsby-theme-codebushi": "^1.0.0",
    "gatsby-transformer-sharp": "^5.12.3",
    "postcss": "^8.3.8",
    "react": "^18.2.0",
    "react-anchor-link-smooth-scroll": "^1.0.12",
    "react-animation-on-scroll": "^5.1.0",
    "react-dom": "^18.2.0",
    "react-helmet": "^6.1.0",
    "react-hook-form": "^7.48.2",
    "react-router-dom": "^6.20.1"
  },
  "devDependencies": {
    "eslint": "^7.21.0",
    "eslint-config-airbnb": "^18.0.1",
    "eslint-config-prettier": "^8.1.0",
    "eslint-plugin-import": "^2.19.1",
    "eslint-plugin-jsx-a11y": "^6.2.3",
    "eslint-plugin-prettier": "^3.1.2",
    "eslint-plugin-react": "^7.17.0",
    "eslint-plugin-react-hooks": "^4.2.0",
    "prettier": "^2.2.1"
  }
}

gatsby-config.js #

module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-codebushi`,
      options: {
        tailwindConfig: `tailwind.config.js`
      }
    },
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/assets/icons/icon.png'
      }
    },
    'gatsby-plugin-image',
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
  ],
};

解决方案 #

1. 启用DEV_SSR定位问题代码 #

修改gatsby-config.js，添加DEV_SSR标记，在开发阶段模拟服务端渲染，快速找到触发错误的位置：

module.exports = {
  flags: {
    DEV_SSR: true
  },
  plugins: [
    // 原插件配置不变
    {
      resolve: `gatsby-theme-codebushi`,
      options: {
        tailwindConfig: `tailwind.config.js`
      }
    },
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/assets/icons/icon.png'
      }
    },
    'gatsby-plugin-image',
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
  ],
};

运行gatsby develop，此时会在开发环境抛出同样的错误，根据堆栈信息定位到具体组件或代码行。

2. 修复客户端API调用 #

方法一：用useEffect包裹document操作

所有直接访问document的代码，必须放到React的useEffect钩子中，因为useEffect仅在客户端渲染阶段执行：

import { useEffect } from 'react';

const MyComponent = () => {
  useEffect(() => {
    // 这里写访问document的代码，比如：
    const element = document.querySelector('#target');
    if (element) {
      // 执行操作
    }
  }, []);

  return <div id="target">...</div>;
};

export default MyComponent;

方法二：动态导入依赖客户端环境的第三方库

从package.json看，项目使用了react-animation-on-scroll、react-anchor-link-smooth-scroll这类可能在服务端访问document的库，需要用动态导入并禁用SSR：

import loadable from '@loadable/component';

// 动态导入组件，禁用服务端渲染
const AnimationOnScroll = loadable(() => import('react-animation-on-scroll'), {
  ssr: false
});

const MyAnimatedSection = () => {
  return (
    <AnimationOnScroll animateIn="animate__fadeIn">
      <div>滚动时会动画的内容</div>
    </AnimationOnScroll>
  );
};

export default MyAnimatedSection;

如果没有安装@loadable/component，先执行npm install @loadable/component，并在gatsby-config.js中添加gatsby-plugin-loadable-components-ssr插件。

方法三：排查主题内置代码

项目使用了gatsby-theme-codebushi主题，可能主题内部存在访问document的代码。可以尝试：

• 查看主题文档，确认是否有针对SSR的配置选项
• 覆盖主题中涉及客户端API的组件，用useEffect或动态导入改造

3. 其他排查点 #

• 检查gatsby-ssr.js、gatsby-node.js等文件，确保没有在服务端执行阶段访问document
• 确认MUI组件的使用方式，部分MUI组件需要客户端环境，必要时用动态导入处理

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