部署Next.js到Vercel时出现ReferenceError: document is not defined错误

核心原因分析 #

虽然你已给页面和组件添加use client，但以下场景仍会导致服务端预渲染时访问document：

• 依赖库（如ReactQuill）内部代码在服务端解析阶段尝试调用浏览器API
• Navbar组件的document操作逻辑未被正确隔离在客户端执行环境
• use client指令的位置不符合Next.js规则要求

具体解决方案 #

1. 隔离Navbar中的浏览器API操作

将Navbar里操作document.body的代码放到useEffect中（仅客户端执行），或添加环境判断：

// Navbar.jsx
'use client';

import { useEffect } from 'react';

export default function Navbar() {
  useEffect(() => {
    // 仅在客户端执行的滚动控制逻辑
    document.body.style.overflow = 'hidden';
    return () => {
      document.body.style.overflow = 'auto';
    };
  }, []);

  // 其他组件代码
}

或用条件判断包裹：

if (typeof document !== 'undefined') {
  document.body.style.overflow = 'hidden';
}

2. 动态导入ReactQuill并禁用服务端渲染

ReactQuill依赖浏览器环境，即使加了use client，预渲染阶段仍可能触发错误。用next/dynamic动态导入，强制跳过服务端渲染：

// AdminForm.jsx
'use client';

import dynamic from 'next/dynamic';

// 动态导入ReactQuill，禁用SSR
const ReactQuill = dynamic(() => import('react-quill'), {
  ssr: false,
  loading: () => <p>加载编辑器中...</p>
});

export default function AdminForm() {
  // 使用ReactQuill的代码
  return <ReactQuill theme="snow" />;
}

3. 确保use client指令的正确位置

use client必须是文件的第一条有效语句，不能放在任何导入或代码之后：

// page.jsx 正确写法
'use client';

import AdminForm from '@/components/AdminForm';

export default function CreatePage() {
  return <AdminForm />;
}

4. 强制Vercel重新构建并清除缓存

在Vercel控制台的部署页面，点击"Redeploy"按钮，勾选"Skip cache"选项，确保构建过程完全重新执行，避免旧缓存导致的问题。

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