如何强制Gatsby在报错时完成构建？解决SSR中window未定义问题

1. 延迟第三方依赖的加载 #

如果错误来自第三方包，不要在组件顶部直接import，改用动态导入+浏览器环境判断，确保只在客户端加载依赖：

import React, { useEffect, useState } from 'react';

const MyComponent = () => {
  const [TargetModule, setTargetModule] = useState(null);

  useEffect(() => {
    import('存在问题的第三方包').then(mod => {
      setTargetModule(mod.default || mod);
    });
  }, []);

  if (!TargetModule) return <div>加载中...</div>;

  return <TargetModule />;
};

export default MyComponent;

2. 全局Mock window对象 #

在项目根目录创建gatsby-ssr.js，给SSR过程添加window的模拟对象，避免报错：

exports.onRenderBody = ({ setPreBodyComponents }) => {
  setPreBodyComponents([
    <script
      dangerouslySetInnerHTML={{
        __html: `
          if (typeof window === 'undefined') {
            global.window = {};
            // 按需补充需要mock的属性，比如document、navigator等
            window.document = { createElement: () => ({}) };
            window.navigator = { userAgent: 'ssr' };
          }
        `,
      }}
    />,
  ]);
};

3. 修正Webpack Null Loader配置 #

之前的配置可能没匹配到正确的依赖包名，将/filler-module/替换为实际出问题的依赖包名称，并且仅在build-html阶段生效：

exports.onCreateWebpackConfig = ({ actions, loaders, stage }) => {
  if (stage === 'build-html') {
    actions.setWebpackConfig({
      module: {
        rules: [
          {
            test: /实际有问题的依赖包名/,
            use: loaders.null(),
          },
        ],
      },
    });
  }
};

4. 使用官方推荐的代码分割工具 #

安装@loadable/component插件，自动处理SSR与客户端的加载差异：

npm install @loadable/component

在组件中引入使用：

import loadable from '@loadable/component';

const LoadableTarget = loadable(() => import('存在问题的第三方包'), {
  fallback: <div>加载中...</div>,
});

const MyComponent = () => <LoadableTarget />;

export default MyComponent;

关于强制跳过检查 #

Gatsby没有官方的强制跳过SSR检查的选项，强行跳过会导致页面渲染异常（如空白、功能失效），不建议这么做。优先通过上述方案解决根本问题，保证SSR与客户端渲染的一致性。

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