Next.js中使用ReactQuill执行yarn build时出现document未定义错误

安全阿岳

2026-7-20

解决Next.js中ReactQuill构建时"document is not defined"的错误

问题原因

Next.js 默认对 pages 目录下的组件执行服务端渲染（SSR），而 ReactQuill 依赖浏览器环境的 document 对象——服务端渲染阶段不存在这个对象，因此构建时会抛出 ReferenceError，导致 /Articles 页面的数据收集失败。

修复方案

方案1：动态导入并禁用SSR（推荐）

使用 Next.js 提供的 dynamic 函数，在导入 ReactQuill 时明确禁用服务端渲染，确保组件只在客户端加载：

import React, { useState } from 'react';
import dynamic from 'next/dynamic';

// 动态导入ReactQuill，禁用SSR
const ReactQuill = dynamic(() => import('react-quill'), { ssr: false });
// 导入Quill样式（必须，否则编辑器无样式）
import 'react-quill/dist/quill.snow.css';

export default function Articles() {
  const [content, setContent] = useState<ReactQuill.Value>('');
  
  const handleChange = (value: ReactQuill.Value) => {
    setContent(value);
  };

  return (
    <ReactQuill theme="snow" value={content} onChange={handleChange} />
  );
}

方案2：利用useEffect在客户端加载组件

通过 useEffect 钩子，确保只有在客户端渲染完成后才加载 ReactQuill：

import React, { useState, useEffect, useRef } from 'react';
import 'react-quill/dist/quill.snow.css';

export default function Articles() {
  const [content, setContent] = useState<string>('');
  const quillContainer = useRef<JSX.Element | null>(null);

  useEffect(() => {
    // 仅在客户端动态导入ReactQuill
    import('react-quill').then(({ default: ReactQuill }) => {
      quillContainer.current = (
        <ReactQuill 
          theme="snow" 
          value={content} 
          onChange={(value) => setContent(value)} 
        />
      );
    });
  }, [content]);

  return <div>{quillContainer.current}</div>;
}