Gatsby Build构建失败：React Context与window对象访问问题求助

一、解决浏览器window/document访问问题（替代typeof window判断） #

• 用useEffect/useLayoutEffect包裹客户端逻辑
  这两个钩子仅在客户端执行，SSR阶段不会运行，直接把依赖浏览器API的代码放在里面即可：

  useEffect(() => {
    // 这里安全访问window/document，比如获取视口尺寸
    const viewportWidth = window.innerWidth;
    document.title = `当前宽度: ${viewportWidth}`;
  }, []);
  

• 封装复用的自定义Hook
  写一个useBrowser Hook统一处理浏览器对象，避免重复代码：

  import { useState, useEffect } from 'react';
  
  export const useBrowser = () => {
    const [browser, setBrowser] = useState({
      window: null,
      document: null
    });
  
    useEffect(() => {
      setBrowser({
        window: window,
        document: document
      });
    }, []);
  
    return browser;
  };
  

  组件中使用时直接调用，无需每次写判断：

  const { window, document } = useBrowser();
  if (window) {
    // 执行客户端操作
  }
  

二、解决React Context SSR报错问题（避免全量可选链） #

1. 给Context设置默认初始值 #

创建Context时传入兜底默认值，确保SSR阶段即使没有Provider覆盖，也不会出现null/undefined：

import { createContext } from 'react';

// 定义与实际Context结构一致的默认值
const GeneralStateContext = createContext({
  accessLevel: 0,
  // 其他需要的属性都设默认值
});

这样SSR时读取accessLevel会拿到默认的0，不会触发Cannot read properties of null错误。

2. 把依赖Context的客户端逻辑移到useEffect #

比如你需要根据accessLevel重定向，这是纯客户端行为，SSR不需要处理，放在useEffect里：

import { useContext, useEffect } from 'react';
import { useNavigate } from 'gatsby';
import { GeneralStateContext } from '../contexts/GeneralStateContext';

const YourPage = () => {
  const { accessLevel } = useContext(GeneralStateContext);
  const navigate = useNavigate();

  useEffect(() => {
    // 客户端渲染完成后再判断重定向
    if (accessLevel > 1) {
      navigate('/');
    }
  }, [accessLevel, navigate]);

  return (
    {/* 页面内容 */}
  );
};

3. 统一在根层包裹Context Provider #

在gatsby-browser.js和gatsby-ssr.js中用wrapRootElement API，确保所有页面（包括SSR时）都被Context Provider包裹：

// gatsby-browser.js 和 gatsby-ssr.js 内容一致
import React from 'react';
import { GeneralStateContextProvider } from './src/contexts/GeneralStateContext';

export const wrapRootElement = ({ element }) => {
  return <GeneralStateContextProvider>{element}</GeneralStateContextProvider>;
};

同时在Provider组件中设置SSR兼容的初始值，客户端加载后再更新为真实数据：

// GeneralStateContext.js
import { createContext, useState, useEffect } from 'react';

const GeneralStateContext = createContext({ accessLevel: 0 });

export const GeneralStateContextProvider = ({ children }) => {
  const [state, setState] = useState({
    accessLevel: 0, // SSR兜底值
  });

  useEffect(() => {
    // 客户端获取真实用户状态，更新Context
    const fetchUserState = async () => {
      const res = await fetch('/api/user-access');
      const data = await res.json();
      setState({ accessLevel: data.accessLevel });
    };
    fetchUserState();
  }, []);

  return (
    <GeneralStateContext.Provider value={state}>
      {children}
    </GeneralStateContext.Provider>
  );
};

4. 使用useStaticQuery或getStaticProps预取Context依赖数据 #

如果Context的值可以在构建时预获取，用Gatsby的数据查询API提前拿到数据，直接传入Context Provider，避免客户端异步更新的间隙：

// 在根组件或Provider中用useStaticQuery获取静态数据
import { useStaticQuery, graphql } from 'gatsby';

const GeneralStateContextProvider = ({ children }) => {
  const data = useStaticQuery(graphql`
    query GetDefaultAccessLevel {
      site {
        siteMetadata {
          defaultAccessLevel
        }
      }
    }
  `);

  const [state, setState] = useState({
    accessLevel: data.site.siteMetadata.defaultAccessLevel,
  });

  // 客户端再更新为用户真实数据
  useEffect(() => {
    // ...fetch逻辑
  }, []);

  return <GeneralStateContext.Provider value={state}>{children}</GeneralStateContext.Provider>;
};

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