最近在做公司的Vue3后台管理系统表单里需要放一个富文本编辑器用来发布公告、写产品说明。UI层我用的Element Plus表格、表单、弹窗都有现成组件唯独富文本这块一直没选到特别顺手的。市面上的编辑器挨个试了一圈最后在Vue3项目里老老实实接入了CKEditor5并且花了不少时间研究怎么把不需要的工具栏按钮和无关功能藏干净。今天这篇文章就把这部分实操记录下来从安装、封装组件到隐藏多余功能的几种做法一次讲透。如果你也在Vue3项目里遇到编辑器功能太多、界面太乱的问题这篇可以直接抄作业。1. 为什么选CKEditor5几款主流编辑器的真实对比1.1 主流富文本编辑器横向对比在确定用CKEditor5之前我把当前主流的几个编辑器都过了一遍这里直接给结论。先说对比维度Vue3适配度、常用功能完善度、文档质量、自定义开发成本、以及社区活跃度。编辑器Vue3适配度优点劝退点CKEditor5官方组件功能全面模块化设计文档清晰界面现代包体积偏大配置有一定学习成本TinyMCE第三方封装老牌稳定插件丰富高级功能需要付费自托管配置较繁琐UI偏老气Quill第三方封装轻量API清晰JSON增量好用图片上传和粘贴处理需要自己折腾2.x API变动大wangEditor原生JS为主中文文档友好上手快定制能力受限更新节奏不稳定复杂场景容易碰壁TipTap官方基于ProseMirror扩展性强头铁的人喜欢概念偏重学习曲线陡峭中小团队上手成本高对于后台管理系统来说编辑器本质是一个生产力组件不能光图轻量。运营和编辑日常要用它写文章、做排版粘贴过来的Word、网页内容能不能干净地转换图片能不能方便上传这些直接影响工作效率。CKEditor5在粘贴清洗、多媒体处理、协同编辑这些方向都有成熟方案而且在Vue3生态里有官方维护的组件包不需要依赖个人维护的第三方封装这点很重要——至少不会出现作者弃坑、Vue3升级后组件不兼容的尴尬。1.2 CKEditor5的构建形态和版本选型CKEditor5和很多老一代编辑器的最大区别在于它的功能全部基于插件机制实现。官方预打包了几种常用的构建形态Build比如Classic经典布局工具栏在顶部表单场景最常用Document类似Google Docs的流式文档布局Inline点击文本就地编辑没有工具栏框Balloon点击后弹出气泡工具栏BalloonBlock气泡加固定工具栏块做后台管理系统尤其是有明确表单结构的页面Classic是最贴合需求的编辑器就是一个可输入的区块顶部工具栏直观保存时直接拿HTML内容提交。所以下面所有配置都以Classic Build为基础展开。这里有一个容易被忽略的选型点如果你只需要编辑器不需要给它做源码级深度定制直接用ckeditor/ckeditor5-build-classic官方包即可如果后续大概率要裁剪插件、新增自定义按钮那么直接走官方在线构建器生成自定义包更有利后面第3章会专门讲。2. 从零安装并在Vue3项目里跑起来2.1 创建项目和安装npm依赖如果项目已经存在这一步直接跳过。如果从零开始我习惯用Vite创建Vue3项目npm create vuelatest # 或者 npm create vitelatest过程中会让你选择是否启用TypeScript、Vue Router、Pinia等。TypeScript看团队规范如果只是写配置类代码先不选也行后续想加也能加。项目创建好之后进入项目目录安装编辑器相关依赖npm install ckeditor/ckeditor5-vue ckeditor/ckeditor5-build-classic这两个包的分工要搞清楚ckeditor/ckeditor5-vue是Vue官方适配组件它负责把编辑器实例和Vue的响应式系统绑到一起ckeditor/ckeditor5-build-classic是编辑器本体里面已经打包好了默认插件集合和样式。二者缺一不可。安装完成后强烈建议把版本号锁死。具体做法是打开package.json把这两个包的版本从类似^41.0.0改成41.0.0这样不带脱字符^的形式。CKEditor5社区迭代很快有时候一个minor版本就会调整配置字段或者改变默认行为如果让npm install自动拉新版本很容易出现昨天还好好的今天同事pull代码装完包就报错了的情况。我在项目里吃过这个亏之后所有前端小组成员都被我要求锁版本。2.2 封装一个可复用的Vue3编辑器组件直接在每个页面里写CKEditor原始用法不是不行但维护成本太高。我倾向于在src/components下封装一个Ckeditor5Editor.vue组件把配置、事件、样式都收拢到一处。完整代码如下template div classckeditor-wrapper ckeditor :editoreditor :model-valuemodelValue :configeditorConfig inputhandleInput readyhandleReady focushandleFocus blurhandleBlur / /div /template script setup import { ref, computed } from vue; import ClassicEditor from ckeditor/ckeditor5-build-classic; import { CKEditor } from ckeditor/ckeditor5-vue; const props defineProps({ modelValue: { type: String, default: }, config: { type: Object, default: () ({}) } }); const emit defineEmits([update:modelValue, ready, focus, blur]); const editor ClassicEditor; const editorConfig computed(() ({ placeholder: 请输入内容..., ...props.config })); function handleInput(event, editorInstance) { emit(update:modelValue, editorInstance.getData()); } function handleReady(editorInstance) { emit(ready, editorInstance); } function handleFocus(event, editorInstance) { emit(focus, editorInstance); } function handleBlur(event, editorInstance) { emit(blur, editorInstance); } /script style scoped .ckeditor-wrapper { width: 100%; } /style这段代码里有几个点需要重点说明。第一我用了:model-value而不是直接v-model因为ckeditor/ckeditor5-vue组件的v-model用法沿袭了Vue2时代的习惯在Vue3里用起来有些别扭拆开写更可控。第二input回调的第一个参数并不是DOM事件对象而是编辑器实例很多第一次接入的人在这里卡住拿不到数据。第三editorConfig用computed包裹是为了让父组件传入的配置变化时能响应式更新。第三点展开说一下如果没有用computed父组件改了config子组件里的editorConfig不会重新计算编辑器仍然保持旧配置。这在需要动态切换工具栏场景、比如不同角色看到不同按钮时非常关键。2.3 页面里引入并做首次运行封装好组件后在业务页面里使用template Ckeditor5Editor v-modelform.content / /template script setup import { reactive } from vue; const form reactive({ content: }); /script打开页面编辑器应该能正常渲染了。但这时候你会看到顶部密密麻麻排了一整排工具栏按钮加粗、斜体、下划线、删除线、上标、下标、代码块、表格、图片上传、表情、块引用、WordCount统计……视觉上非常劝退。我项目里第一次跑起来运营同事看了一眼就吐槽怎么这么多按钮我们日常只用加粗、列表和超链接。这句话基本就是做隐藏功能的最佳理由。另外首次运行如果控制台出现warning比如Some of the toolbar buttons are not available不要慌。这通常是因为默认toolbar配置里包含了某些需要额外插件加载的按钮而当前构建包里没有对应插件。这类warning会随配置调整逐渐消失。3. 隐藏不需要的功能三种做法逐步进阶3.1 搞清楚架构功能的载体是插件按钮只是入口在动手隐藏之前必须先理解CKEditor5的插件机制。它的每个功能加粗、列表、图片、表格、字数统计等都是一个独立插件而工具栏上的每个按钮只是对应插件的触发入口。这就带来一个关键认知如果只是把按钮从toolbar数组里删掉插件本身仍然在编辑器后台运行代码也依然会被浏览器加载。只是用户看不到按钮了而已。所以如果只是想让界面清爽、操作路径简单裁剪toolbar配置就够了如果还希望减小打包体积、减少不必要的代码逻辑必须把插件本身移出构建。做后台管理系统正确的组合策略是日常编辑功能全部保留用不到的重型插件彻底移除最终让界面和代码体积一起瘦身。3.2 方式一直接裁剪toolbar配置在封装组件的defaultConfig里加上一套精简toolbarconst defaultConfig { toolbar: { items: [ heading, |, bold, italic, underline, strikethrough, |, bulletedList, numberedList, |, link, blockQuote, |, undo, redo ] } };这里解释几个语法细节|表示垂直分隔线-表示换行。想让工具栏两排展示就在中间插入-。按钮顺序完全可控最常用的放最前面用户进页面一眼就能看到。我故意去掉了fontColor、fontBackgroundColor和fontSize。后台系统里运营和编辑如果随意改字号和颜色最终产出的页面会乱成一锅粥。限定他们只能用固定层级标题和加粗/斜体内容排版反而更统一。另外heading按钮默认会带出H1、H2、H3、H4等多个标题级别。如果后台文章只需要二级和三级标题可以进一步限制选项const config { heading: { options: [ { model: paragraph, title: 正文, class: ck-heading_paragraph }, { model: heading2, view: h2, title: 二级标题, class: ck-heading_heading2 }, { model: heading3, view: h3, title: 三级标题, class: ck-heading_heading3 } ] } };这一步看起来只是少几个选项实际对内容规范的约束力比很多人想象的大。编辑不会出现在后台看到什么按钮都点一遍的行为你给什么入口他就用什么能力。3.3 方式二用removePlugins移除整个功能模块假设项目里明确不允许直接插入表格或上传图片可以再加一段配置const config { removePlugins: [ Table, TableToolbar, Image, ImageToolbar, ImageUpload, MediaEmbed, PageBreak, CodeBlock ], toolbar: { items: [ heading, |, bold, italic, underline, strikethrough, |, bulletedList, numberedList, |, link, blockQuote, |, undo, redo ] } };removePlugins数组里的插件名必须和构建包导出的类名完全一致。不确定名字时去node_modules/ckeditor/ckeditor5-build-classic/node_modules里翻源码类型定义文件或者直接看官方文档的Plugin List。这里有两个坑要提前提醒。第一个坑部分插件之间有依赖关系比如ImageUpload依赖Image如果你只删ImageUpload不删Image控制台会报冲突。解决办法是移除插件时把关联的一起移除或者干脆保留基础依赖。第二个坑removePlugins和toolbar是两码事。如果你只removePlugins不裁剪toolbar某些已移除插件对应的按钮还在toolbar里编辑器初始化时会直接报Unsupported toolbar item。3.4 方式三用官方在线构建器生成自定义版本toolbar裁剪只是入口不显示removePlugins是运行时不加载但ckeditor/ckeditor5-build-classic这个包本身仍然是一个全量构建里面包含了官方默认捆绑的所有插件的代码。如果你不需要这些功能让它们一直躺在包里打包体积依然很大。想要最干净的方案官方提供了一条正路在线构建器Online Builder。流程是这样的打开CKEditor5官方在线构建器页面在左侧选择需要的插件、定义工具栏按钮、设置语言页面右侧实时预览编辑器效果下载生成的zip压缩包里面有完整的自定义构建包源码、示例页面、README文档。下载解压后把整个ckeditor5-custom-build目录放进自己的项目里或者发布到公司内部npm仓库我为了省事直接作为本地依赖引入。包结构类似ckeditor5-custom-build/ ├── build/ │ ├── ckeditor.js │ └── ckeditor.d.ts ├── src/ │ └── ckeditor.ts ├── package.json └── README.md在封装组件里只需要把导入路径换掉import CustomEditor from /vendor/ckeditor5-custom-build/build/ckeditor; const editor CustomEditor;我当时把默认的Classic Editor换成自定义构建后包体积从400多KB降到130KB左右首屏加载体验明显改善。缺点是构建流程需要人工到网页上操作配置需要手动记录存档但收益也明显代码里没有一句话是没用但被迫加载的。3.5 隐藏底部信息栏和多余弹窗除了顶部工具栏Classic构建在编辑器可编辑区域下方还会显示一个底部状态栏区域常见的字数统计就是在这里出现的。如果不需要最好从源头把对应插件移除比如WordCount插件。但如果只是视觉上想隐藏、又不想动插件加载逻辑也可以用CSS兜底.ck.ck-editor__bottom { display: none; }不过我不建议用CSS硬藏。插件逻辑还在跑只是看不到界面白白消耗运行性能。理想状态是从配置层把插件移除界面才不会出现相关的DOM节点。隐藏功能不是为了看起来干净而是让编辑器真正不存在这些代码路径。4. 进阶配置高度、中文、事件与外链资源4.1 编辑器高度和滚动优化默认状态下Classic编辑器的高度很矮只有顶部工具栏加输入区的一小段在后台系统里写稍长一点的内容就显局促了。我习惯在组件里给可编辑区域设置最小高度.ck-editor__editable { min-height: 320px; }这里要特别注意不要直接写height: 320px。如果写死高度用户内容一多编辑器内部会出现滚动条操作体验很别扭。设min-height更符合内容编辑器的习惯——内容少时保持一个舒适的输入区域内容长时自然往下撑开。如果业务上确实要固定高度比如放在弹窗里控制总高度可以同时设置max-height和overflow-y.ck-editor__editable { max-height: 500px; overflow-y: auto; }实测下来这是固定高度场景下最接近文档编辑器的配置。4.2 界面语言切换为中文默认Classic构建是英文界面后台系统面向国内运营人员中文界面更友好。切换方法是在配置里加上language并引入中文语言包import zh from ckeditor/ckeditor5-build-classic/build/translations/zh-cn; const config { language: { ui: zh-cn, content: zh-cn }, localization: { extraTranslations: [zh-cn] } };不同大版本40.x、41.x、42.x语言包路径有差异最稳的做法是去node_modules/ckeditor/ckeditor5-build-classic/build/translations/目录下面看实际有哪些文件再选择对应路径。配置完刷新页面插入链接、选择标题等弹窗界面就会变成中文。4.3 把编辑器事件安全传递出来前面封装的组件已经对外暴露了ready、focus、blur事件。实际业务中比较常用的是blur场景后台表单在用户离开编辑器时做内容校验或者把临时存储的数据同步到接口。在父组件里这么用template Ckeditor5Editor v-modelform.content blurhandleEditorBlur / /template script setup function handleEditorBlur(editorInstance) { // 在这里校验内容、同步数据 const content editorInstance.getData(); } /script这里有一个使用习惯要特别提醒如果用input做实时存储输入中文时回显会偶尔出现延迟。因为每次输入都触发数据同步在复杂表单和低性能页面上会有可感知的卡顿。我的建议是编辑时只做本地展示数据最终以blur时或表单提交时取到的内容为准。5. 常见问题与排查技巧5.1 高频问题排查速查表下面这些是CKEditor5在Vue3项目里出现频率最高的问题也是我自己和团队里同事踩过的坑整理成了一张速查表现象可能原因解决方案编辑器没有任何样式输入区域显示为空白全局CSS或CSS重置把ck样式覆盖了检查全局样式里是否有针对.ck-*类名的规则必要时给编辑器容器加独立类名隔离控制台报Unsupported toolbar itemtoolbar里配置了未安装插件对应的按钮删掉该按钮或先确认对应插件已加载页面出现Duplicate CKEditor 5警告项目里同时存在多个构建包版本统一所有ckeditor/*相关包版本或改用在线构建版在Element Plus弹窗里打开编辑器不显示弹窗懒加载导致编辑器初始化时容器不可见在弹窗完全打开后再初始化编辑器或用nextTick延迟创建input事件拿到的内容不对第一个参数理解错误它不是DOM事件确认回调签名是(event, editorInstance)用第二个参数取数据打包体积太大默认引入了全量Classic构建用removePlugins裁剪插件或改用在线构建生成精简包编辑器内粘贴Word内容格式混乱默认粘贴规则对复杂文档结构保留程度有限开启对应粘贴清理插件或自定义htmlSupport规则排查这些问题的通用思路是先看版本再看配置最后检查样式覆盖。不要一上来就怀疑构建工具或者组件封装90%的问题出在配置和版本一致性上。5.2 Vite和Webpack下遇到的兼容性问题如果项目使用ViteCKEditor5的ESM代码和动态import机制偶尔会触发编译警告尤其是老版本。常见的有两类构建时提示Could not resolve ckeditor5通常是关联包找不到依赖别名控制台出现The files property相关warning一般是不同包引用了不同路径。我的处理经验是优先把CKEditor5相关包升级到40以上的稳定版本新版本对Vite的友好度大幅提升如果仍然报错在vite.config.js里给相关包加optimizeDeps.include让依赖预构建时显式包含如果你使用Webpack老版本还遇到过Module not found的问题通常是把ckeditor/ckeditor5-*相关包加入babel-loader的include范围就能解决。5.3 每次都值得检查的一步关闭联网类和自动保存类功能在后台管理系统的内网环境中最容易踩的暗坑是编辑器配置里隐含了外链资源请求。比如某些扩展插件会加载远程图标、字体、或者调用云端处理接口。一旦网络环境不允许轻则图标加载失败重则编辑器直接初始化失败。我个人的做法是在封装组件的config里对不明确来源的扩展一律不引入。如果确实要用图片上传对应的ckfinder或uploadAdapter连接器必须指向自己后端接口不能留在默认的云服务配置上。写到这里从安装到隐藏不需要功能的完整路径基本已经落地。最后分享一个我自己的习惯不管用哪种方式裁剪功能都建议把最终配置整理成一份注释清晰的文档放在组件旁边。这类配置后期更换负责人时最容易出现不知道当初为什么去掉这个按钮一堆删不掉的配置没人敢动的情况。我自己经历过的坑是项目后期运营提出要加一个插入视频按钮结果翻代码发现MediaEmbed插件早就被我removePlugins移除了排查了半天才想起来是自己当初干的。如果当时在注释里写清楚就能少浪费半小时。这种项目里的为什么文档没什么技术含量但时间久了它比任何代码注释都值钱。
