Next.js预渲染报错：Cannot read properties of null 求助

核心原因分析 #

该错误本质是Next.js预渲染（SSR/SSG）阶段，React内部全局对象未被正确初始化，导致useEffect、useState等hooks无法正常调用。常见触发场景：

• React、React DOM版本与当前Next.js版本不兼容
• @tanstack/react-query等依赖包的SSR适配存在问题
• _app.tsx中存在违反React Hooks规则的代码，或在服务端执行了仅客户端可用的逻辑

具体调试步骤 #

1. 校验依赖版本兼容性 #

• 执行npm list react react-dom next查看版本，确保Next.js与React版本匹配：Next.js 13+需搭配React 18.x，Next.js 12对应React 17.x，不匹配则升级/降级到兼容版本。
• 确认@tanstack/react-query版本支持当前Next.js的SSR模式，比如v4+需配合Next.js的App Router或正确配置服务端逻辑。

2. 排查_app.tsx代码问题 #

• 若使用Pages Router，将QueryClientProvider的初始化逻辑限制在客户端：

  import dynamic from 'next/dynamic'
  const ClientProvider = dynamic(() => import('./ClientProvider'), { ssr: false })
  
  function MyApp({ Component, pageProps }) {
    return (
      <ClientProvider>
        <Component {...pageProps} />
      </ClientProvider>
    )
  }
  

• 确保所有React Hooks都在组件顶层调用，无组件外部的Hook调用行为。

3. 隔离服务端执行的客户端代码 #

• 检查页面组件中是否在服务端调用了window、document等浏览器专属API，可通过typeof window !== 'undefined'判断环境，或用useEffect延迟执行客户端逻辑。
• 排查第三方库是否在服务端渲染时未正确导出React依赖，导致React对象为null。

4. 启用详细构建日志 #

• 修改package.json的build脚本，添加调试参数：

  "scripts": {
    "build": "next build --debug"
  }
  

  执行yarn build后查看完整错误栈，定位具体报错的代码文件与行号。

5. 逐步隔离代码定位问题 #

• 先替换为极简版_app.tsx（仅返回<Component {...pageProps} />），重新执行next build，若错误消失，再逐步加回QueryClientProvider、全局样式等逻辑，定位触发错误的代码块。
• 逐个禁用页面组件，确认是否为某个页面的代码导致全局预渲染失败。

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