Vercel部署React/Next.js项目失败：无法读取undefined的'document'属性

一、处理package-lock.json警告 #

直接删除项目根目录下的package-lock.json文件，提交代码到Git仓库后重新触发Vercel部署即可。
原因：项目同时存在Yarn的yarn.lock和npm的package-lock.json，混用包管理器会导致依赖解析不一致，Vercel检测到后触发该警告，移除其中一个锁文件就能解决。

二、解决"无法读取undefined的'document'属性"错误 #

这个错误源于Next.js的服务端渲染（SSR）/静态生成（SSG）特性：服务器端执行代码时，浏览器专属的document对象不存在，而你的代码在服务器环境中尝试访问了它。本地build成功是因为本地构建预览环境和Vercel部署环境存在差异，或是本地未触发服务器端执行该逻辑的场景。

解决步骤：

• 排查所有直接访问document的代码位置，将这些操作移至useEffect钩子内部。useEffect仅在客户端渲染完成后执行，此时document已存在。
  错误示例：

  const domElement = document.querySelector('.some-class');
  export default function Home() {
    return <div className="some-class"></div>;
  }
  

  修正后：

  import { useEffect } from 'react';
  export default function Home() {
    useEffect(() => {
      const domElement = document.querySelector('.some-class');
      // 执行相关操作
    }, []);
    return <div className="some-class"></div>;
  }
  

• 如果是第三方依赖导致的问题，使用Next.js的dynamic导入组件并禁用SSR，让组件仅在客户端渲染：

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

• 本地模拟生产环境：执行yarn run build && yarn run start，启动生产服务后测试，复现错误以便定位问题。
• 检查next.config.js配置，确保没有强制在服务器端执行客户端逻辑的选项。

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