Next.js中React-Quill集成Quill Mention报TypeError问题求助

问题概述 #

• 在Next.js项目中集成react-quill和quill-mention模块时，触发错误：TypeError: moduleClass is not a constructor，调用栈指向Quill.js的SnowTheme.addModule方法
• 尝试通过以下useEffect代码注册模块时触发错误，目前已注释该代码：

useEffect(() => {
  if (Quill) {
    Quill.register("modules/imageResize", ImageResize);
    Quill.register("modules/mention", Mention);
  }
}, [Quill]);

• 已完成的排查：确认quill-mention导入路径正确、核对react-quill/quill/quill-mention版本兼容性、参考Quill官方模块注册文档

1. 错误产生原因 #

• 注册时机与环境问题：Next.js的SSR环境下，Quill尚未完成客户端初始化就执行注册操作，导致传入的模块类不是合法的构造函数
• 模块导入方式错误：quill-mention的默认导出并非直接构造函数，未正确解构或获取对应导出项会导致传入无效值
• react-quill内部冲突：react-quill已封装Quill实例管理，手动调用Quill.register会干扰内部逻辑，引发模块注册异常

2. 正确集成步骤 #

步骤1：确认版本兼容 #

推荐使用经过验证的版本组合：

• react-quill: ^2.0.0
• quill: ^1.3.7
• quill-mention: ^4.0.0

步骤2：客户端动态导入与模块注册 #

由于Quill是纯客户端库，必须禁用SSR，同时在客户端环境内完成模块注册：

'use client'; // Next.js 13+ App Router 需添加此指令
import dynamic from 'next/dynamic';
import { useMemo } from 'react';
// 导入必要样式
import 'react-quill/dist/quill.snow.css';
import 'quill-mention/dist/quill.mention.css';

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

const MentionEditor = () => {
  const modules = useMemo(() => {
    // 仅在客户端环境导入并注册模块
    const Quill = require('quill');
    const Mention = require('quill-mention').default;
    const ImageResize = require('quill-image-resize-module').default;

    // 注册模块，第三个参数true强制覆盖冲突模块
    Quill.register('modules/mention', Mention, true);
    Quill.register('modules/imageResize', ImageResize, true);

    return {
      mention: {
        allowedChars: /^[A-Za-z\sÅÄÖåäö]*$/,
        mentionDenotationChars: ['@'],
        // 自定义数据源逻辑
        source: (searchTerm, renderList) => {
          const userList = [
            { id: 1, value: '张三' },
            { id: 2, value: '李四' },
            { id: 3, value: '王五' }
          ];
          const filtered = userList.filter(item => 
            item.value.toLowerCase().includes(searchTerm.toLowerCase())
          );
          renderList(filtered, searchTerm);
        }
      },
      imageResize: {},
      toolbar: [
        ['bold', 'italic', 'underline'],
        ['link', 'image'],
        ['code-block']
      ]
    };
  }, []);

  return (
    <div style={{ width: '100%', height: '400px' }}>
      <ReactQuill theme="snow" modules={modules} placeholder="开始输入..." />
    </div>
  );
};

export default MentionEditor;

步骤3：避免错误的额外配置 #

• 强制禁用SSR：确保react-quill仅在客户端加载，避免服务端初始化Quill导致的异常
• 使用useMemo注册模块：确保模块注册逻辑仅执行一次，避免重复注册引发的冲突
• 导入完整样式：必须导入quill.snow.css和quill.mention.css，否则编辑器样式会错乱
• Next.js 13+ App Router适配：所有涉及Quill的组件需添加'use client'指令，标记为客户端组件

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