Next.js14构建遇document未定义及预渲染错误，如何定位页面？

错误成因 #

document是浏览器特有的全局对象，Next.js执行build时会对页面进行预渲染（SSR/SSG），这个过程运行在Node.js服务器环境中，不存在document对象。如果代码在服务端执行阶段直接调用document（比如组件顶层代码、未做环境判断的初始化逻辑），就会触发该错误。

精确定位错误位置 #

1. 利用Source Map映射源码 #

• 在next.config.js中开启生产环境Source Map：

  module.exports = {
    productionBrowserSourceMaps: true,
  }
  

• 重新执行npm run build，拿到错误栈中的文件路径与行号（比如3871.js:1:68626）
• 打开Chrome DevTools的Sources面板，将项目.next目录添加到工作区，DevTools会自动通过Source Map将编译后的chunk文件映射回原始源码，直接定位到出错的代码行。

2. 聚焦预渲染报错页面 #

错误提示Error occurred prerendering page "/"，优先排查首页（/）的所有组件：

• 检查组件顶层代码是否有直接调用document的逻辑（比如document.getElementById）
• 排查页面依赖的第三方库，确认是否有库在初始化阶段调用浏览器API且不支持SSR。

3. 逐步缩小排查范围 #

• 临时注释首页的部分组件，重新执行build，若错误消失，说明问题出在被注释的组件中，逐步恢复组件定位具体出错项。

修复方案 #

• 仅在客户端执行浏览器API逻辑：使用React的useEffect钩子，该钩子仅在客户端渲染时执行：

  import { useEffect } from 'react';
  
  function MyComponent() {
    useEffect(() => {
      const targetElement = document.getElementById('target');
      if (targetElement) {
        // 此处安全操作DOM
      }
    }, []);
  
    return <div id="target">...</div>;
  }
  

• 动态导入不支持SSR的组件/库：使用Next.js的dynamic方法禁用SSR：

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

• 环境判断包裹代码：通过typeof document判断当前环境，仅在浏览器环境执行相关逻辑：

  if (typeof document !== 'undefined') {
    // 此处调用document相关代码
  }
  

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