涉密内网办公系统CKEditor格式保留插件选型与落地配置

接手过这类涉密内网办公系统改造的人大概率都经历过相似的至暗时刻文印室老师傅把Word红头文件直接CtrlC进浏览器排版全散科研人员从内部资料站复制一段带公式的内容粘进去全是乱码最麻烦的是年底总结时从Excel拷出来的表格在编辑器里变成一坨没有框线的纯文本。问题出在哪大多数人第一反应是前端组件不行甚至有人直接提需求说把富文本编辑器换成Word Online。但实际上CKEditor的底子是够用的真正缺的是格式保留这一层的插件选型和配置。这篇文章就把我在军工系统这类高安全要求环境里给CKEditor搭配格式保留插件的完整思路和落地配置讲清楚。先说清楚这篇文章适合谁看如果你正在做内网办公系统、涉密OA、军工科研单位知识库或者只是想把Web端富文本编辑器做得更接近Word的排版体验那么下面这些插件选型和坑点都可以直接抄作业。我不会只给一份插件清单还会把每个插件的取舍逻辑、离线部署方式、安全过滤策略一起讲明白。毕竟在军工系统里能装什么、不能装什么比功能本身更先决定方案走向。1. 先拆需求格式保留到底在保什么1.1 三个层面的格式保留很多人一上来就问要装哪些格式保留插件但这个问题其实藏着一个前置问题你要保留的是哪一层格式我在实际项目里会把格式拆成三层看每一层的插件选型完全不同。第一层是粘贴来源格式也就是从Word、WPS、Excel、网页里复制内容后还能不能保留原文的字体、字号、颜色、表格框线、列表编号和图片。这一层靠的是CKEditor的粘贴预处理插件典型代表是Paste from Office。很多粘贴后全乱的抱怨其实都是这一层没有配好。第二层是编辑状态格式也就是用户在编辑器里手动设置的加粗、倾斜、下划线、对齐、缩进、列表样式、标题级别、代码块、公式、表格列宽等。这一层靠的是编辑器内置和扩展的样式插件比如Font、Alignment、ListProperties、TableProperties等。这一层漏配的结果是从外部拷贝进来看起来正常但用户一改就丢样式或者菜单栏上根本没那个按钮。第三层是输出与回显格式也就是内容存进数据库再加载回来时HTML结构和内联样式是否被保留。这一层人们最容易忽略但它往往不是缺插件而是缺配置比如内容过滤规则太严格span style...一进去就被过滤掉导致编辑时看着没问题保存再打开就变了样。1.2 为什么CKEditor默认配置会丢格式理解这个问题要回到CKEditor的数据模型。CKEditor不是简单地把HTML字符串塞进contenteditable就完事它会先做一套HTML解析和内容过滤把不合规的标签、样式、事件属性全部剔除再转成自己的模型结构并重新渲染。这个机制叫ACFAdvanced Content Filter高级内容过滤CKEditor 4的叫法或者htmlSupport配置CKEditor 5里的叫法。这套机制的本意是好的能阻止用户粘贴进来的危险脚本和脏样式但副作用也很明显默认白名单往往只包含基础标签比如p、strong、em、h1-h6、ul、ol、li、table等对于span stylefont-family:...、自定义CSS类、section这类结构标签默认是不保留的。所以在军工项目里我看到最多的现象是Word文档粘贴进来正文文字保住了但字体全变成默认体表格框线没了图片不显示公式变成纯文本。这不是CKEditor不行而是没有按需放开过滤规则、没有挂对应的处理插件。2. 插件选型按保留对象逐类拆解2.1 粘贴来源抢救Word、WPS、Excel的格式导入第一个要配的插件就是PasteFromOffice在CKEditor 5里官方包名是ckeditor/ckeditor5-paste-from-officeCKEditor 4里对应的是pastefromword插件。这个插件做的是粘贴净化工作用户从Word、Excel里复制内容时剪贴板里不只是纯文本还带一份HTML片段Office自己生成的OOXML转HTML结构PasteFromOffice会解析它把Word特有的命名空间标签、无效样式、vml图形封装、域代码域代码就是Word里那种自动编号、交叉引用的隐藏指令清洗掉同时把能映射到CKEditor模型的内容尽量保留比如字体、字号、加粗、对齐、表格框线。我实测下来CKEditor 5的PasteFromOffice对Word的兼容性已经相当好但对WPS的支持不如原生Word。毕竟WPS生成的HTML片段在命名空间和样式写法上有自己的变种。碰到这种情况我的做法是再加一个兜底配置clipboard的粘贴钩子在数据进入编辑器之前先做一次预处理把WPS特有的标签替换掉。下面这段伪代码思路可以放在项目里editor.plugins.get( ClipboardPipeline ).on( inputTransformation, ( evt, data ) { const content data.content; // 对WPS生成的标签做一次清洗去除类似o:p这类无效的XML占位 content.change( writer { // 这里可以用writer遍历content根节点做标签重映射 // 实际项目中我们会在这一层剥离无意义的font-family内联 // 并统一Times New Roman到系统默认中文字体。 } ); } );另一个被忽视的点是PasteFromPlainText。军工系统里有很多用户习惯从PDF、CAJ阅读器、甚至老旧的TXT格式文档里复制内容这些来源的剪贴板数据往往是伪纯文本或者带大量不可见字符。我建议在工具栏上保留一个粘贴为纯文本的入口让用户自己选择而不是让编辑器把所有来源都按富文本处理。用户一定会在某个时候感谢你这个按钮。提示不要把PasteFromOffice当成万能。它只能保证从Word/Excel粘贴的常见格式被保留像Word里用文本框、形状工具做的复杂版式粘贴进HTML后依然会崩。这是浏览器剪贴板机制决定的任何Web富文本编辑器都没法完全还原那种版式。2.2 基础文本和版式字体字号颜色对齐缩进这一层是用户在编辑器内主动排版的核心。CKEditor 5的官方包ckeditor/ckeditor5-font提供了字体、字号、字体颜色、背景色四个子功能对应插件分别叫FontFamily、FontSize、FontColor、FontBackgroundColor。它们生成的是span stylefont-family:...和span stylefont-size:...这类内联样式所以必须配合htmlSupport白名单才能保证保存后回显不丢。这里有个军工项目里很常见的需求单位公文要求字体必须是方正小标宋仿宋_GB2312黑体这类中文字体而员工的浏览器可能没装这些字体。如果你只把字体列表配成固定的中文字体名也不做任何降级那么另一个没装字体的电脑打开内容时就会自动替换成默认字体版式就看着好像没变、实际全变了。我的建议是把字体列配置为字体名 安全兜底字体的组合类似CSS里的font-family: 仿宋_GB2312, FangSong, SimSun, serif;这样的逻辑。在FontFamily配置里可以指定选项时附带fallback虽然CKEditor在输出HTML时还是会写成单个字体名但至少你可以规定统一使用仿宋_GB2312这一名字并让前端展示样式时做一次字体映射。对齐和缩进也是格式保留的重灾区。CKEditor 5里对应的包是ckeditor/ckeditor5-alignment提供左对齐、居中、右对齐、两端对齐生成text-align样式。缩进则需要ckeditor/ckeditor5-indent配合IndentBlock一起用否则只能缩进列表项不能缩进段落。在军工公文场景里段落首行缩进2字符是硬需求但我必须提醒一句CKEditor的IndentBlock默认输出的是margin-left或padding-left的像素值输出到打印端时除非打印CSS做了特殊适配否则缩进会跟Word的首行缩进2字符产生视觉误差。我建议在前端展示层用一个约定正文段落统一不加内联缩进样式而是用一种特殊类名比如classfirst-line-indent再由CSS统一控制缩进量。这样既能保证编辑时所见接近Word又能保证打印导出时的统一性。2.3 表格与复杂结构表格是格式保留里的重头戏。CKEditor 5的表格功能拆得比较细Table是最基础的表格支持TableToolbar提供插入行、列、删除表格这些操作入口TableProperties和TableCellProperties则负责表格宽度、高度、边框颜色、背景色、单元格宽高这些属性级格式。从Excel粘贴表格后框线、合并单元格能否保留主要看PasteFromOffice和Table插件配合得怎么样。实际项目里Excel粘贴进CKEditor往往有两个问题。一是框线丢失因为Excel的单元格边框在粘贴后的HTML里经常表现为border样式而不是table border1属性如果内容过滤白名单把border-style、border-color过滤掉了表格就变成无框线。二是列宽失真Excel的列宽转成HTML之后往往是像素或百分比但CKEditor默认可能使用固定像素模式粘贴后列宽比例看起来会跟Excel不完全一致。解决列宽的思路是在粘贴预处理里把Excel生成的colgroup和col width转换成CKEditor能识别的table stylewidth:100%加每列td stylewidth:??%的百分比结构。这样至少能保住大致的比例关系。对于合并单元格CKEditor 5的Table插件原生支持rowspan和colspan的可视化操作工具栏里能用鼠标合并拆分单元格。这一点在军工科研单位的多级表头场景里特别有用因为涉密装备的测试记录表、指标对照表几乎都有复杂的多级表头结构。如果你手里的老系统还在用CKEditor 4那建议把TableTools和tableresize一起装上否则合并单元格和拖拽调整列宽会很痛苦。2.4 代码块与数学公式军工系统里搞计算机和通信技术的人多科技文档经常要贴代码片段和数学公式。代码块用ckeditor/ckeditor5-code-block它会把代码包在precode classlanguage-xxx里支持高亮。选它的时候要注意两点第一语言类别列表要按单位实际情况裁剪不要默认给几十种语言内网用户翻起来麻烦第二它输出的代码块用的是pre标签而Word粘贴进来的代码往往是一堆乱七八糟的等宽字体文本加换行粘贴后并不会自动识别成代码块需要用户手动套用代码块样式。数学公式是另一个大坑。CKEditor 5官方文档推荐的是商业插件MathType它提供可视化的公式编辑面板用户体验非常好但问题是它需要网络通信做公式渲染和授权校验在物理隔离的内网环境里落地很麻烦。我的替代方案是用开源思路集成KaTeX把公式编辑组件做成一个弹窗性质的插件用户从LaTeX文本粘贴或手写公式语法预览渲染用KaTeX实时完成最终在编辑器里插入一段用span classmath-tex\(...\)/span包裹的HTML。这套方案不需要额外的云端服务离线部署完全可控。对于老项目用CKEditor 4的场景官方有个mathjax插件可以把MathJax库放到内网静态资源目录下通过config.mathJaxLib指定本地地址一样能跑。注意公式和代码不要混用一套过滤规则。代码块里的、字符很多数学公式里又有大量#、{、}如果保存到后端后还经过一次HTML实体解码或转义很容易出现显示异常。我在项目里会把这类内容按原文块存储前端展示时再动态渲染避免在传输链路上被二次转义。2.5 图片、附件与多媒体图片是格式保留里最容易被忽略的一环。CKEditor 5的图片功能由Image、ImageToolbar、ImageStyle、ImageResize、ImageUpload等插件组成。这里我特别想提醒的是图片粘贴上传问题用户在Word里复制一张截图后粘贴到编辑器剪贴板里其实是一张二进制图片如果编辑器没有配置上传适配器CKEditor 5会默认把图片转成base64字符串塞进HTML源码里。一张几MB的图片立刻让文档体积膨胀一半保存到数据库还会撑爆字段长度。军工内网环境里我推荐的做法是自建一个简单的图片上传接口用ckeditor/ckeditor5-upload提供的SimpleUploadAdapter或者自定义UploadAdapter把图片传到内网文件服务器然后在编辑器里保存的是图片URL。这样有几个好处文档库体积可控、图片可以走内网CDN缓存、后续归档导出时图片是独立文件方便做密级标记和脱敏处理。需要注意图片URL在内网环境里要写绝对路径还是相对路径要跟系统部署架构对齐否则就会出现编辑时能看到图别人打开却看不到的问题。多媒体方面还有ckeditor/ckeditor5-html-embed可以做原始的HTML嵌入比如科研人员需要插入一段WebGL演示或者嵌入式可视化图表时直接用HtmlEmbed把HTML片段塞进文档。但这个插件要小心它等于允许用户往编辑器里塞任意HTML安全风险极高在涉密系统里最好只对管理员开放或者干脆禁用。2.6 HTML原始标签的兜底不管前面怎么做总有一些奇怪场景需要保留原始HTML结构。CKEditor 5为此提供了GeneralHtmlSupport它允许你配置一个白名单声明哪些标签、哪些属性、哪些样式可以在编辑器里保留。比如某个系统需要保留section块和>import { ClassicEditor } from ckeditor/ckeditor5-editor-classic; import { Essentials } from ckeditor/ckeditor5-essentials; import { Undo } from ckeditor/ckeditor5-undo; import { Bold, Italic, Underline, Strikethrough, Subscript, Superscript } from ckeditor/ckeditor5-basic-styles; import { Font } from ckeditor/ckeditor5-font; import { Alignment } from ckeditor/ckeditor5-alignment; import { List, ListProperties } from ckeditor/ckeditor5-list; import { Indent, IndentBlock } from ckeditor/ckeditor5-indent; import { BlockQuote } from ckeditor/ckeditor5-block-quote; import { Table, TableToolbar, TableProperties, TableCellProperties } from ckeditor/ckeditor5-table; import { Image, ImageToolbar, ImageStyle, ImageResize, ImageUpload } from ckeditor/ckeditor5-image; import { CodeBlock } from ckeditor/ckeditor5-code-block; import { Link } from ckeditor/ckeditor5-link; import { RemoveFormat } from ckeditor/ckeditor5-remove-format; import { SourceEditing } from ckeditor/ckeditor5-source-editing; import { GeneralHtmlSupport } from ckeditor/ckeditor5-html-support; import { HtmlEmbed } from ckeditor/ckeditor5-html-embed; import { PasteFromOffice } from ckeditor/ckeditor5-paste-from-office; import { HorizontalLine } from ckeditor/ckeditor5-horizontal-line; import { SpecialCharacters } from ckeditor/ckeditor5-special-characters; ClassicEditor.create( document.querySelector( #editor ), { plugins: [ Essentials, Undo, Bold, Italic, Underline, Strikethrough, Subscript, Superscript, Font, Alignment, List, ListProperties, Indent, IndentBlock, BlockQuote, Table, TableToolbar, TableProperties, TableCellProperties, Image, ImageToolbar, ImageStyle, ImageResize, ImageUpload, CodeBlock, Link, RemoveFormat, SourceEditing, GeneralHtmlSupport, HtmlEmbed, PasteFromOffice, HorizontalLine, SpecialCharacters ], toolbar: { items: [ undo, redo, heading, |, fontfamily, fontsize, fontColor, fontBackgroundColor, |, bold, italic, underline, strikethrough, subscript, superscript, removeFormat, |, alignment, outdent, indent, |, bulletedList, numberedList, blockQuote, horizontalLine, |, link, uploadImage, insertTable, codeBlock, // 如果集成了公式插件在这里加 mathType 或 katexFormula |, htmlEmbed, sourceEditing ] }, table: { contentToolbar: [ tableRow, tableColumn, mergeTableCells, tableProperties, tableCellProperties ] }, fontSize: { options: [ 12px, 14px, 16px, 18px, 20px, 24px, 28px, 36px, { title: 小五, value: 9pt }, { title: 五号, value: 10.5pt }, { title: 小四, value: 12pt }, { title: 四号, value: 14pt }, { title: 小三, value: 15pt }, { title: 三号, value: 16pt }, { title: 小二, value: 18pt }, { title: 二号, value: 22pt } ] }, list: { properties: { styles: true, startIndex: true, reversed: true } }, image: { toolbar: [ imageStyle:block, imageStyle:side, imageUpload, toggleImageCaption ], upload: { types: [ jpg, png, gif, bmp, webp ] } }, htmlSupport: { allow: [ { name: span, attributes: true, styles: { font-weight: true, font-style: true, text-decoration: true, color: true, background-color: true, font-size: true, font-family: true, text-align: true, margin-left: true, margin-right: true, padding-left: true, padding-right: true } }, { name: section, attributes: true, classes: true }, { name: div, attributes: true, classes: true, styles: true } ] } } ).catch( error { console.error( error ); } );几个关键配置的解释fontSize里我同时保留了像素值和以号为单位的公文字号因为军工单位的文档规范里经常要求三号仿宋这类说法给出预设字号能大大减少踩踏式调整。htmlSupport只放开span的部分样式其他标签默认仍由ACF阻断。这里要特别提醒我写的allow规则是允许attributes: true和classes: true在真实项目里要根据安全策略收紧最好精确到属性名。4.3 CKEditor4 老项目兼容方案很多军工单位的老系统还在用CKEditor 4升级到CKEditor 5是大工程因为CKEditor 5的框架结构完全重写了插件不兼容。如果你的老项目暂时不能升级那至少在格式保留上把CKEditor 4配到最优状态。在CKEditor 4里我推荐配置如下插件pastefromword从Word粘贴、font字体字号、colorbutton和colordialog字体颜色、justify对齐、liststyle列表样式、indentblock段落缩进、table和tableresize和tabletools表格、image图片、codesnippet代码块、mathjax公式、sourcearea源码。在config.js里可以这样写config.extraPlugins pastefromword,font,colorbutton,colordialog,justify,liststyle,indentblock,tableresize,tabletools,codesnippet,mathjax,image,sourcearea; // 保留尽可能多的标签和样式但注意这条配置需要用白名单收紧 config.allowedContent true; config.pasteFromWordPromptCleanup true; config.mathJaxLib /internal-resources/mathjax/MathJax.js?configTeX-AMS_HTML; // 字体配置示例按单位规范配置 config.font_names 仿宋_FangSong;楷体_KaiTi;黑体_SimHei;宋体_SimSun;方正小标宋_FZXiaoBiaoSong;; config.fontSize_defaultLabel 14px;这里我要泼一盆冷水config.allowedContent true;虽然能保证最完整的格式保留但同时也是安全审计里最刺眼的红灯。因为这个开关等于关闭了CKEditor 4的自动内容过滤粘贴进来的script虽然还是会被浏览器的粘贴事件剥掉大部分但一些通过DOM事件属性构造的恶意代码就可能留住了。我建议实在要保留复杂格式可以用config.extraAllowedContent指定放行项而不是无脑开allowedContent true。这算是我踩过内网安全扫描之后总结的一条硬经验。5. 常见问题与排查技巧5.1 粘贴Word内容后样式丢失或错乱我排查这类问题的顺序是先看是全丢还是部分丢。全丢一般是PasteFromOffice插件没挂上或者挂上了但被内容过滤规则压制了。此时打开浏览器控制台把粘贴内容截取一段看有没有Office特有的o:p、?xml残留标签。如果残留说明PasteFromOffice根本没有处理你的剪贴板数据可能原因是剪贴板数据不是Word的标准格式也可能是插件版本与核心不匹配。部分丢则通常是过滤规则把某种样式或标签干掉了这时用开发者工具查看编辑器的模型数据对照htmlSupport白名单逐项排查。还有一个很隐蔽的坑从Word粘贴过来后字体颜色显示正常但背景色全没了。这是Word里很多文字的高亮颜色其实存在主题颜色里不是普通的background-colorPasteFromOffice并不会把主题颜色全部映射为CSS色值。这种情况我一般是反其道而行之在粘贴预处理阶段将主题色值做一次映射表转换把Word的标准主题色转成固定十六进制色值。5.2 WPS粘贴后的兼容问题WPS作为国内办公软件的常见选择它的剪贴板HTML生成规则跟Word有差异。典型症状是粘贴后出现大量空的span标签、字体变成wps:name这种自定义命名空间、行距异常。我遇到最崩溃的一次是用户从WPS粘了一个带着仿宋_GB2312字体的文档进来编辑器显示完全正常但导出PDF时那些空span导致了莫名其妙的换行。处理思路是在inputTransformation里对WPS特有标签做主动清理。我写过一个简单的正则和节点遍历逻辑把所有span里没有任何有效样式且没有文本内容的空节点直接删除对wps前缀的属性统一剥掉对WPS生成的p stylemso-pagination:...这类无效样式也可以剥除。这个清理不会影响Word粘贴的内容因为Word生成的HTML结构里这些噪声相对较少。5.3 图片粘贴不显示或变成base64如果粘贴截图后编辑器里有个图标占位但图片不显示多半是上传适配器没有正确返回图片URL。CKEditor 5的图片上传流程是粘贴图片后生成一个临时占位调用自定义UploadAdapter的upload()方法拿到Promise返回的{ url: xxx }后才替换成真实图片。如果上传接口返回的不是标准JSON结构编辑器就会一直停留在占位状态。如果图片显示正常但保存到数据库后文档体积变得很大那就是走了base64内嵌路线。在军工系统的数据库里这种体积膨胀是不可接受的。我的建议是配置ImageUpload的同时把现有的GeneralHtmlSupport白名单里对srcdata:image/...的限制一起加上优先禁止在新文档里生成base64图片只允许上传后的URL地址。不过这也意味着离线环境必须要有一个稳定可靠的内网图片上传服务。5.4 公式渲染异常公式类问题分两种编辑时渲染不了和保存后展示异常。编辑时渲染不了多半是MathJax或KaTeX的脚本资源没有加载内网环境尤其容易漏配路径。检查网络请求看MathJax.js或katex.min.js是否返回200没有就是路径问题。保存后展示异常的情况我排查重点在LaTeX源码的存储格式。有的方案会把\(...\)标记存进数据库但展示页没有做同样的解析脚本于是用户看到一串反斜杠和花括号还有的方案直接把公式转成了base64图片保存后能显示但清晰度极差打印出来全是马赛克。我更推荐用LaTeX文本渲染引擎方案因为文本不会因为设备分辨率变化而模糊而且能保持可检索性。5.5 粘贴外部HTML带入危险脚本这是安全审计必查的一项。我遇到过内网某个知识库被人贴了一段包含img srcx onerroralert(1)的内容前端过滤规则漏了大小写变体结果所有打开该文档的用户浏览器都弹了警告。虽然只是一次内部演练但这个问题的危害级别很高。对付它不能只靠前端我通常用后端清洗的时候会做几件事一是解析HTML时把标签名统一转成小写再进行白名单匹配防止SCRIPT这类大小写绕过二是把所有事件属性onclick、onerror、onload等在正则层面直接剥除三是对href、src、action这类URL属性做协议白名单只允许http:、https:、mailto:和相对路径其他如javascript:、data:全部拦截。做完这三步配合前端的htmlSupport白名单双端基本能堵住大多数XSS变体。6. 经验与总结6.1 插件不是越多越好我在前面推荐了二十来个插件但真实项目里你完全可以根据业务裁剪。插件越多包体积越大内网加载时间越长更重要的是很多插件会引入额外的DOM结构和样式反而干扰格式保真的最终效果。比如SpecialCharacters如果单位不是经常要写特殊符号完全可以去掉HtmlEmbed这种高风险插件默认就不该出现在普通用户的工具栏里。我的原则是先把业务真正需要的场景列出来再按场景反向配插件。比如军工系统里的公文编辑场景和技术文档场景其实需要完全不同的插件组合。公文场景重在字体、字号、首行缩进、表格框线技术文档场景重在代码块、公式、多级列表。日后再有变更再按需求小批量增加插件并回归一次内容过滤配置。6.2 版本升级前一定要做粘贴回归我在项目里踩过的最痛的坑是从CKEditor 4升CKEditor 5之后存储的旧文档里大量内联样式失效。原因很简单CKEditor 5对HTML结构的清洗策略更激进旧的font face...标签、废弃的align属性在读取时会被当成无效内容丢掉。当时文档库里几千篇历史文档一夜之间版式有点乱解决起来非常麻烦。所以如果你在一个有存量数据的内网系统里做升级务必将旧文档回显效果列成验收标准。测试时不能只看新建一篇文档的效果还要拿不同年代的存量文档逐篇看版式。如果存量数据里的格式大多依赖font标签和废弃属性建议先在旧数据入库一刻做一次HTML规范化转换把旧标签统一映射成CKEditor 5支持的CSS内联样式或类名再进行升级。这个迁移过程虽然烦但总比上线后天天被人骂要强。最后再分享一个我常年保留的小技巧无论用CKEditor 4还是CKEditor 5都建议在编辑器下方预留一个HTML源码折叠区。内网用户里总有一些熟悉代码的老专家他们贴复杂排版时HTML源码视图比任何按钮都好用。SourceEditing插件在CKEditor 5里提供了这个入口CKEditor 4里就是sourcearea。做好这个入口之后至少格式保留的求助工单能少掉三分之一。别小看这个看似不起眼的开关很多编辑器丢了格式的最终解法就是让用户能亲手打开源码把那个该死的空标签删掉。