解决 CKEditor 5 React 集成自定义构建版本时出现的渲染失败问题

当在 React 应用中集成通过 CKEditor 5 Online Builder 创建的自定义编辑器时，可能会遇到 `TypeError: Cannot read properties of undefined (reading 'create')` 错误，导致编辑器无法正常渲染。本文旨在深入分析此问题，指出其根源在于 CKEditor 5 的 Watchdog 功能与 React 集成组件之间的冲突，并提供通过配置 `watchdogConfig` 属性来有效解决此问题的专业教程。

问题描述

在使用 CKEditor 5 Online Builder 生成自定义编辑器构建版本，并尝试将其集成到 React 18 应用程序中时，开发者可能会发现编辑器未能成功渲染，并在控制台中看到类似 TypeError: Cannot read properties of undefined (reading 'create') 的错误信息。尽管预构建的经典版或气球版 CKEditor 5 能够正常工作，但自定义版本却遇到了初始化障碍。

典型的集成代码示例如下：

import { CKEditor } from '@ckeditor/ckeditor5-react';
import { Editor } from 'ckeditor5-custom-build/build/ckeditor';

const DashboardPage = () => {
  return (
    <p className='card'>
      <p className='card-body'>
        <p className='mx-auto'>
          <CKEditor
            editor={Editor}
            data="<p>Hello from CKEditor 5!</p>"
            onReady={editor => {
              console.log('Editor is ready to use!', editor);
            }}
            onChange={(event, editor) => {
              // const data = editor.getData();
              // console.log({ event, editor, data });
            }}
            onBlur={(event, editor) => {
              console.log('Blur.', editor);
            }}
            onFocus={(event, editor) => {
              console.log('Focus.', editor);
            }}
          />
        </p>
      </p>
    </p>
  );
}

export default DashboardPage;

登录后复制

同时，项目中使用的 CKEditor 5 相关依赖版本可能如下：

"@ckeditor/ckeditor5-build-balloon": "^38.0.1",
"@ckeditor/ckeditor5-react": "^6.0.0",
"ckeditor5-custom-build": "file:./ckeditor5"

登录后复制

问题根源分析

此 TypeError: Cannot read properties of undefined (reading 'create') 错误通常表明 CKEditor 实例在 React 组件内部未能正确初始化。经过深入研究，问题的核心在于 CKEditor 5 的 Watchdog (看门狗) 功能。

CKEditor 5 的 React 集成 (@ckeditor/ckeditor5-react) 已经内置了其自身的 Watchdog 功能，用于监控编辑器的状态并处理潜在的崩溃。然而，当通过 CKEditor 5 Online Builder 创建自定义构建版本时，如果其中也包含了 Watchdog 功能，就会导致两个 Watchdog 实例同时存在，产生冲突。这种冲突会干扰编辑器核心的初始化流程，使得 editor 对象在尝试调用 create 方法时为 undefined，从而抛出上述类型错误。

CKEditor 官方文档对此有明确说明：“如果您想使用 CKEditor 5 Online Builder，请确保未选择 Watchdog 功能。React 集成组件已将 Watchdog 功能集成到核心中。”这进一步证实了冲突是问题的关键。

解决方案

解决此问题的关键是确保 React 集成组件能够正确管理 Watchdog 功能，避免与自定义构建版本中的 Watchdog 产生冲突。最直接且推荐的方法是在使用 CKEditor 组件时，通过 watchdogConfig 属性明确配置 Watchdog 的行为。