React项目按F5刷新页面后CKEditor消失不显示问题咨询

核心诱因 #

• 初始化时序不匹配：首次通过路由跳转进入页面时，React组件挂载、CKEditor资源加载顺序稳定，编辑器可正常初始化；F5触发全页刷新时，很容易出现编辑器初始化逻辑先于DOM容器挂载、核心依赖脚本未加载完成就执行的情况，实例创建失败直接导致组件不显示。
• SSR环境兼容问题：如果项目基于Next.js、Remix等带服务端渲染能力的React框架搭建，刷新时服务端会先执行组件代码，CKEditor强依赖浏览器端的window、document对象，服务端环境下运行初始化逻辑会直接抛错，后续水合阶段节点匹配失败，编辑器组件就会被卸载不渲染。
• 实例残留冲突：如果组件卸载时没有正确销毁已创建的CKEditor实例，刷新时全局作用域下残留的实例标记会被新的初始化逻辑检测到，判定同容器已绑定编辑器实例，直接终止新实例的创建流程。
• 静态资源路径错误：部分项目配置了动态publicPath，在深层路由下触发刷新时，CKEditor依赖的语言包、插件等静态资源会拼接错误的相对路径，返回404导致资源加载失败，编辑器渲染中断。

对应解决方法 #

• 对齐初始化时序
  不要在组件同步执行阶段直接渲染编辑器，先通过ref确认DOM容器已完成挂载，再触发编辑器渲染，同时在组件卸载时彻底销毁全局残留的编辑器实例，参考代码：

  import { useEffect, useRef, useState } from 'react';
  import { CKEditor } from '@ckeditor/ckeditor5-react';
  import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  
  export default function MyEditor() {
    const containerRef = useRef(null);
    const [editorReady, setEditorReady] = useState(false);
  
    useEffect(() => {
      if (containerRef.current) setEditorReady(true);
      // 卸载时清理残留实例
      return () => {
        if (window.CKEDITOR?.instances) {
          Object.values(window.CKEDITOR.instances).forEach(instance => instance.destroy());
        }
      }
    }, []);
  
    return (
      <div ref={containerRef}>
        {editorReady && (
          <CKEditor
            editor={ClassicEditor}
            config={{
              language: 'zh-cn',
              // 固定资源根路径，避免深层路由下相对路径404
              simpleUpload: { uploadUrl: '/api/editor/upload' }
            }}
          />
        )}
      </div>
    )
  }
  

• 适配SSR场景
  用动态导入的方式加载编辑器组件，关闭该组件的服务端渲染逻辑，仅在客户端环境下初始化，Next.js项目示例：

  import dynamic from 'next/dynamic';
  const EditorComp = dynamic(() => import('./MyEditor'), { ssr: false });
  
  // 页面中直接使用<EditorComp />即可
  

• 排查资源加载错误
  打开浏览器开发者工具的Network面板，刷新页面时筛选CKEditor相关的请求，如果存在404报错，直接在编辑器配置中指定静态资源的基础路径为站点根路径，不要用相对路径引用编辑器依赖。
• 避免重复初始化
  在编辑器初始化的回调中，先判断当前容器是否已经绑定过编辑器实例，如果存在旧实例先调用destroy()方法销毁，再创建新实例。

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