当在 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 ( <div className='card'> <div className='card-body'> <div 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); }} /> </div> </div> </div> ); } 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 的行为。
通过向
以下是更新后的代码示例：
import { CKEditor } from '@ckeditor/ckeditor5-react'; import { Editor } from 'ckeditor5-custom-build/build/ckeditor'; const DashboardPage = () => { return ( <div className='card'> <div className='card-body'> <div className='mx-auto'> <CKEditor editor={Editor} data="<p>Hello from CKEditor 5!</p>" // 关键配置：添加 watchdogConfig 属性 // 它可以是一个空对象 {}，或者根据需要配置 crashNumberLimit 等参数 watchdogConfig={ { crashNumberLimit: 10 } } 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); }} /> </div> </div> </div> ); } export default DashboardPage;在上述代码中，watchdogConfig={ { crashNumberLimit: 10 } } 明确告知 React 集成组件如何处理 Watchdog。即使自定义构建版本中包含了 Watchdog，此配置也能使其在 React 环境下得到妥善管理，从而解除冲突，使编辑器能够顺利初始化和渲染。如果不需要特定的 Watchdog 行为配置，也可以简单地设置为 watchdogConfig={ {} }。
最佳实践与注意事项
-
Online Builder 配置优化： 最理想的解决方案是在使用 CKEditor 5 Online Builder 生成自定义构建版本时，就不要选择包含 Watchdog 功能。由于 @ckeditor/ckeditor5-react 已经内置了 Watchdog，自定义构建中再包含它是不必要的，并且容易引发冲突。在构建过程中取消勾选 Watchdog 选项，可以从根本上避免此问题。
-
watchdogConfig 的作用： watchdogConfig 属性不仅用于解决冲突，还允许开发者自定义 Watchdog 的行为，例如设置 crashNumberLimit 来限制编辑器在短时间内可以崩溃的次数。这是一个强大的工具，用于提高编辑器的稳定性。
-
参考官方示例： 在遇到集成问题时，查阅 CKEditor 5 React 官方仓库中的示例代码（例如 demo-react-18/src/EditorDemo.tsx）是非常有帮助的。官方示例通常展示了最新的、经过验证的集成方式，可以作为调试和学习的宝贵资源。
总结
当使用 CKEditor 5 Online Builder 创建的自定义构建版本在 React 应用中渲染失败，并出现 TypeError: Cannot read properties of undefined (reading ‘create’) 错误时，根本原因通常是 CKEditor 5 的 Watchdog 功能与 React 集成组件的内置 Watchdog 机制发生冲突。通过在