Next.js静态导出报document is not defined错误排查求助

错误触发原因 #

• 隐性引用：即使首页代码没直接写document，也可能有组件在客户端挂载前（比如组件函数顶层、useEffect外部）访问了document。Next.js预渲染在Node环境执行，没有浏览器的document对象，因此报错。
• 样式文件问题：全局样式或组件样式中如果用到依赖document的特性（比如动态计算的CSS变量、依赖视口的样式逻辑），也可能触发该错误。
• 配置遗漏：检查next.config.js是否正确设置output: 'export'，若存在experimental等其他配置项，可能意外开启了SSR相关逻辑。

更详细的构建输出方式 #

• 执行构建时添加--debug参数：

  npm run build -- --debug
  

  该命令会输出完整的构建日志，能定位到触发错误的具体文件和代码行。
• 切换到开发环境构建查看细节：

  NODE_ENV=development npm run build
  

  开发环境的日志会包含更清晰的组件调用栈，帮助排查问题。

能否关闭检查？ #

不能直接关闭该检查——预渲染阶段确实处于Node环境，document本身不存在，强行跳过检查会导致静态页面存在运行时隐患。正确的处理方式是确保依赖浏览器环境的代码仅在客户端执行：

• 将访问document的代码放入useEffect钩子内部（useEffect仅在客户端组件挂载后执行）。
• 添加环境判断包裹代码：

  if (typeof document !== 'undefined') {
    // 依赖document的逻辑写在这里
  }
  

• 若涉及第三方组件，使用Next.js的dynamic导入并禁用SSR：

  import dynamic from 'next/dynamic'
  const ClientOnlyComponent = dynamic(() => import('../components/TargetComponent'), { ssr: false })
  

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