能否禁用SSR，构建纯静态SSG模式的Gatsby站点？

Gatsby默认的SSG模式会在构建时预渲染页面，这导致依赖浏览器API（比如window）的纯客户端库报错。要实现类似Vite或Create React App的纯客户端静态站点，彻底跳过SSR/预渲染流程，按以下步骤操作：

1. 禁用Gatsby的SSR与预渲染能力 #

修改项目根目录的gatsby-config.js，添加flags配置关闭相关功能，同时移除不需要的数据层插件：

module.exports = {
  flags: {
    DEV_SSR: false, // 关闭开发环境的SSR
    PARALLEL_SOURCING: false, // 禁用并行数据拉取（无需数据层时可关）
  },
  plugins: [], // 清空或只保留纯客户端插件
}

如果项目中有gatsby-node.js，直接清空该文件即可，避免触发页面预渲染逻辑。

2. 确保组件仅在客户端渲染 #

对于依赖浏览器API的组件，用两种方式避免SSR期间报错：

• 通用客户端组件封装：写一个可复用的ClientOnly组件，只在浏览器环境渲染子内容：

  import { useEffect, useState } from 'react';
  
  export default function ClientOnly({ children }) {
    const [isMounted, setIsMounted] = useState(false);
  
    useEffect(() => {
      setIsMounted(true);
    }, []);
  
    return isMounted ? children : null; // 也可以替换成加载占位符
  }
  
  // 使用示例
  <ClientOnly>
    <YourClientSideComponent />
  </ClientOnly>
  

• 直接在组件内判断环境：在组件里用typeof window !== 'undefined'确保只在客户端执行相关逻辑：

  import { useEffect, useState } from 'react';
  
  function WindowDependentComponent() {
    const [windowWidth, setWindowWidth] = useState(0);
  
    useEffect(() => {
      setWindowWidth(window.innerWidth);
    }, []);
  
    if (typeof window === 'undefined') return null;
  
    return <div>当前窗口宽度：{windowWidth}</div>;
  }
  

3. 动态导入客户端专属库 #

如果某些库在导入阶段就会访问window（比如一些DOM操作库），用动态导入延迟加载：

useEffect(() => {
  import('your-client-only-library').then(module => {
    const ClientLib = module.default;
    // 在这里初始化并使用库
  });
}, []);

4. 验证构建产物 #

运行gatsby build后，public目录下的产物就是纯静态的HTML/CSS/JS资源，和Vite、CRA的输出结构一致，此时打开页面不会再出现SSR相关的报错。

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