Gatsby构建报WebpackError: document.createElement非函数如何解决

Gatsby的gatsby build构建过程会先在Node.js环境执行服务端渲染（SSR）打包，Node环境不存在浏览器专属的document/window等BOM全局对象。报错代码在模块顶层直接调用document.createElement，SSR阶段执行到这行代码时就会抛出类型错误。

• 先查看构建报错的完整调用栈，定位出错代码所属的文件：区分是自身业务代码，还是引入的第三方npm依赖包触发的错误。
• 如果堆栈路径包含node_modules，直接在依赖目录下搜索对应代码片段，确认具体是哪个第三方包没有做SSR兼容。

场景1：错误来自自身业务代码 #

• 不要在模块顶层直接执行DOM/BOM相关逻辑，优先把这类代码放到仅客户端执行的时机：
  • 类组件放到componentDidMount生命周期中
  • 函数组件放到useEffect钩子中（useEffect内的逻辑不会在SSR阶段执行）
• 如果需要在模块作用域缓存DOM相关变量，增加环境判断，SSR阶段跳过执行：

let _elementStyle = null;
// 仅浏览器环境下执行DOM操作
if (typeof document !== 'undefined') {
  _elementStyle = document.createElement('div').style;
}

场景2：错误来自第三方依赖 #

• 方案1：在Gatsby的Webpack配置中，将不兼容SSR的依赖排除出HTML构建阶段，修改项目根目录的gatsby-node.js：

exports.onCreateWebpackConfig = ({ stage, loaders, actions }) => {
  // HTML构建阶段（SSR阶段）跳过问题依赖的编译
  if (stage === 'build-html' || stage === 'develop-html') {
    actions.setWebpackConfig({
      module: {
        rules: [
          {
            test: /问题依赖的包名/,
            use: loaders.null(),
          },
        ],
      }
    })
  }
}

• 方案2：如果是引入的第三方组件触发的错误，使用动态导入关闭该组件的SSR渲染，仅在客户端加载：

import React from 'react'
// 动态导入问题组件
const ClientOnlyComp = React.lazy(() => import('问题组件的引入路径'))

export default function TargetPage() {
  return (
    <React.Suspense fallback={<div>加载中</div>}>
      <ClientOnlyComp />
    </React.Suspense>
  )
}

注意：不要尝试在Node构建阶段polyfill完整的document对象，这类方案不仅会拖慢构建速度，还容易引发更多不可预期的SSR hydration不匹配问题。

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