CKEditor保留Word格式全攻略：从配置到标题层级修复

你维护过教育平台的话，一定对这样的工单不陌生：老师把Word写好的讲义直接Copy到网页编辑器里，三级标题变成了二级标题，行距缩成一团，表格边框全没了。第一反应往往是“老师不会用编辑器”，但排查到最后，问题几乎都集中在CKEditor对Word格式的处理上。

这个问题的痛点非常具体：教育平台的内容生产端以Word为主，老师写课件、出试卷、整理教案都是在Word里完成的，编辑器只是最后展示的出口。如果粘贴过去格式全丢，老师就得在网页上重新排版，这等于把已经做完的工作再干一遍。所以“CKEditor尽量保留Word格式”不是锦上添花，而是能不能正常交付教学资源的底线能力。

接下来，我不会只讲插件安装，也不会只给一句“装上Paste from Word就完事”，而是把整个链路拆开：为什么丢格式、哪些配置能留格式、出现标题级别错乱时怎么修、图片和表格这类高危对象怎么处理。所有内容都是我实际维护教育平台时踩过坑的总结，适合正在给学校、培训机构、知识付费产品做编辑器的朋友参考。

1. 先弄清楚：Word粘贴到网页，格式是怎么一步步丢掉的

1.1 Word格式和HTML格式，根本不是一个物种

Word文档的本质是用Office Open XML封装的压缩包，里面记录段落、样式、字体、表格、修订和批注。HTML虽然也能描述这些，但描述方式完全不一样。处理Word粘贴的难点，就在于两个不同世界的“翻译”。

在Word里按Ctrl+C时，操作系统会拿到多种格式的数据，其中就有HTML格式。但是这份HTML是Word按照自己的XML规则临时生成的，里面充斥着<w:>命名空间、mso-开头的样式，甚至还有一大段<!--[if gte mso 9]>条件注释。这个HTML直接贴进网页会污染整页样式，CKEditor的工作就是把它清洗成干净、安全、标准的HTML。

问题在于：清洗和保留天然矛盾。清洗得越彻底，页面越安全，Word细节丢得越多；保留得越完整，网页越“脏”，样式冲突风险越高。大部分编辑器的默认策略是优先保安全，结果就是老师排了半天的缩进、行距、标题层级，粘贴过来全无踪影。

1.2 CKEditor 的内容过滤机制是怎么把关的

CKEditor 4的过滤机制叫ACF（Allowed Content Filter），它维护一个白名单。粘贴进来的HTML，凡是白名单里没有的标签、属性和样式，都会被删掉。默认白名单包含常见的p、span、table、img等标签，但Word自定义的那些mso-样式、outline-level样式根本不在名单里，所以直接删除。

CKEditor 5的做法更体系化。它先剖析HTML，把内容映射成内部模型，再按Schema决定哪些元素能保留。Schema不允许的元素不会进入最终模型。理解这一点非常重要：不管你是装插件还是写事件，本质上都是在“扩充允许保留的规则”。

如果你没装专门的Word粘贴处理插件，CKEditor的默认行为就是“宁可错杀一千，不可放过一个”。这也是为什么很多人换了编辑器版本后，粘贴体验反而变差——新版本对安全要求更高了。

1.3 最常见的三类“格式丢失”事故

按我收到的工单统计，格式问题逃不出三类。

第一类是段落类：缩进、行距、对齐方式全部失效。Word里靠mso-indent、line-height等样式控制，这些样式无法通过ACF白名单，自然被丢掉。

第二类是字符类：字体、字号、颜色、加粗/斜体消失。Word的字符样式在输出时大量使用mso-bidi-font-size这类专属属性，浏览器无法解析。

第三类是标题层级错乱，也就是热搜词里说的“三级标题变二级标题”。这类问题最让人抓狂，因为标签结构被改变了，而不是单纯丢样式。后面我会单开一节讲。

2. 教育平台场景下，为什么非要保留Word格式

2.1 老师的使用习惯决定了产品策略

在教育平台，内容生产者是老师，他们不是网页开发者，没有精力和意愿去学HTML。他们一辈子的排版习惯就是Word。如果平台要求他们把讲义复制进网页后重新调整格式，这就是教育平台在跟老师的使用习惯对着干。

所以产品策略应该顺应习惯：让老师用Word写完，一键粘贴到编辑器，格式尽可能保持原样。哪怕做不到100%，至少标题结构、段落缩进、表格这些骨架要保住。能用技术解决的问题，就不要用培训去解决。

2.2 标题层级是课程内容的“目录骨架”

课程讲义天然有层级，比如“第3章-第2节-3.2.1小节”。前端页面通常用h1到h6生成目录导航，老师也能靠标题快速定位。

如果三级标题被变成二级标题，课程目录会多出一层错误的节点；如果再往下错乱，整个导航就乱了。这对线上课程的影响是灾难性的——学生跟着目录找不到知识点，老师也搞不清自己上传的课件到底哪里出了问题。

2.3 公式、图片、表格，教育内容的高危对象

教育内容跟普通博客不一样，里面充满公式、图片、表格和特殊字符。数学公式的下标、上标要是丢了，题目的意思就变了；化学方程式缺一个状态符号，学生就做错题。这类内容对格式保留的要求极高，不是“差不多排版”就行。

Word里插入的公式如果是以OLE对象（比如MathType）方式存在的，粘贴到网页基本等于报废，因为网页没有OLE宿主。表格的复杂合并单元格粘贴过来也经常散架。所以“保留格式”这四个字，在教育场景里背后是实打实的内容正确性问题。

3. CKEditor 4 保留Word格式的落地配置

3.1 必备插件：pastefromword 和它的依赖

如果你还在用CKEditor 4（国内很多教育平台的老系统都是），首先要确认你的构建里是否包含pastefromword插件，以及它依赖的pastetools。这两个插件的作用，是把Word生成的脏HTML先做一层“翻译”，把常见Word样式转成标准HTML，再交给ACF过滤。

安装方式很简单：从官方或社区下载插件包，放到项目的ckeditor/plugins/目录，然后在初始化时用extraPlugins引入。

CKEDITOR.replace('editor', { extraPlugins: 'pastetools,pastefromword', pasteFromWordPromptCleanup: true, pasteFromWordRemoveFontStyles: false, pasteFromWordRemoveStyles: false });

这几个参数的意思有必要解释一下。pasteFromWordPromptCleanup设为true，会在老师粘贴内容时弹出一个“是否清理格式”的确认框。弹窗看起来很贴心，但在课堂直播场景很容易被误点，我的建议是教育平台不要开弹窗，改成在工具栏放一个“清除格式”按钮，让老师自己掌握。

pasteFromWordRemoveFontStyles和pasteFromWordRemoveStyles这两个开关，很多教程会让你们全设成true，理由是可以避免样式冲突。但在教育场景，这会连表格边框、单元格背景一起删掉，所以我的经验是两个都设false。

3.2 ACF白名单：哪些样式必须放行

插件翻译完之后，ACF还要过一道。如果不放行，插件翻译的成果也会被删。所以要在allowedContent里显式声明允许哪些标签和样式。

CKEDITOR.config.allowedContent = { 'h1,h2,h3,h4,h5,h6': { styles: { 'text-align': true } }, p: { styles: { 'text-align': true, 'text-indent': true, 'line-height': true, 'margin': true, 'padding': true } }, table: { attrs: { border: true, cellpadding: true, cellspacing: true, width: true } }, 'td,th': { styles: { 'text-align': true, 'vertical-align': true, 'width': true, 'background-color': true } }, img: { attrs: { src: true, alt: true, width: true, height: true } } };

这个配置不是最全的，但对于“保基础、保安全”来说够用了。要点是：表格的width、background-color一定要放行，否则Word制作的试卷底纹、列宽在网页上全部丢光。line-height要放行，不然Word里调好的行距也会没。

注意：不要因为怕丢格式就把allowedContent设成true，那等于关闭ACF，会陷入另一个坑——老师从别的网页复制内容时，脚本、iframe、非法样式全都进来，页面直接崩掉。我们曾经这么干过，后来不得不花一个晚上清理数据库里的脏数据。

3.3 专项修复：三级标题变二级标题怎么办

现在认真聊“word文档窗口三级标题变二级标题格式不对”这个问题。我遇到的案例里，这个问题的成因至少有三类。

第一类，也是最多的一类：Word文档里的“三级标题”其实并不是真正的“标题3”样式，而是老师手动缩进、手动放大字号伪造出来的视觉效果。Word的导航窗格显示它属于三级，是因为老师使用的操作痕迹，不代表样式级别。复制到网页后，编辑器读取的是样式级别，自然就和老师看到的对不上。

判断方法很简单：在Word里打开“开始-样式”右侧的样式窗格，看这个标题使用的是不是“标题3”。如果样式窗格里根本没高亮，那它就是伪造的伪标题。

第二类，是复制时浏览器或者剪贴板对Word HTML做了转换。不同浏览器看到的剪贴板HTML并不一样，Outlook处理过头，Chrome处理得粗糙，老版Edge又不一样。有些转换会把outline-level:3的段落写成<p>而不是<h3>，最后编辑器根本不知道这是标题。

第三类，是编辑器自身清洗逻辑导致的。CKEditor 4在ACF清理中，有可能把当前层级不连续的元素做降级处理，三级变二级这种“向上”迁移也会发生。

修复思路分两步。

第一步，从源头规范。给老师提供一个检测清单：打开样式窗格，确认标题用的是真实标题样式，不要靠缩进假装标题。这一步能解决70%的工单。

第二步，如果确实需要对粘贴内容做映射修复，可以在paste事件里检查数据的HTML。下面这段代码是思路演示，照着跑之前建议充分测试。

editor.on('paste', function (evt) { var data = evt.data.dataValue; if (!data) return; // 如果粘贴的内容里有 outline-level:n 的段落，把它映射成对应级别的 h 标签 data = data.replace( /<p([^>]*outline-level\s*:\s*(\d+)[^>]*)>/gi, function (match, attrs, level) { var tag = 'h' + Math.min(parseInt(level, 10) + 1, 6); return '<' + tag + attrs + '>'; } ); evt.data.dataValue = data; });

这段代码的原理是：Word在导出HTML时，会把真实应用的标题级别写在outline-level样式里（注意不同版本导出规则不一样），我们把带该样式的<p>重新提升为<h1>到<h6>标签。为什么是level + 1？因为Word的outline级别1对应h1，数字越小越靠顶层，但不同工具实现有差异，所以具体偏移量要按现场HTML实测调整。

如果你拿不准，最快的排查办法是在页面加一段监听，把粘贴的原始HTML打出来：

document.addEventListener('paste', function (e) { console.log(e.clipboardData.getData('text/html')); });

在Word里复制一段标题，回到浏览器按下Ctrl+V，控制台输出的HTML就是编辑器和ACF看到的内容。对照里面的标签和样式，你就能确定问题出在剪贴板转换、Word样式本身还是编辑器清洗哪一层。

4. CKEditor 5 环境下的方案取舍

4.1 架构变化：从改HTML字符串，到改模型

CKEditor 5是个重写版本，底层是模型-视图双层结构。编辑器解析粘贴的Word HTML后，先转成内部模型数据，再渲染到视图。这意味着，你在CKEditor 4里惯用的“正则替换HTML”不再直接有效，因为内容已经变成模型对象了。

不过也不必头大。CKEditor 5提供了一套Schema机制，你可以声明哪些元素可以被保留，哪些标签可以放进文档树。这和ACF的思路类似，但更符合现代编辑器的设计。

4.2 开源版能做到什么程度

如果平台已经升级到CKEditor 5，想保留Word格式，首先要装上General HTML Support插件。它让你在htmlSupport配置里指定允许的标签和样式，和CKEditor 4的allowedContent是同一个用途。

ClassicEditor .create(document.querySelector('#editor'), { htmlSupport: { allow: [ { name: 'h3', classes: true, styles: true }, { name: 'p', classes: true, styles: true }, { name: 'table', styles: true, classes: true }, { name: 'td', styles: true, classes: true }, { name: 'img', attributes: true, styles: true } ], disallow: [ { name: 'script' }, { name: 'style' } ] } }) .catch(function (err) { console.error(err); });

这段配置的意思是：放行h3、p、table、td、img这些元素的样式和类名，同时禁止script和style标签。教育平台用这一段基本够用。注意，classes: true表示保留class属性，这很重要，因为有些Word格式解析后会挂class。

4.3 升级编辑器时，别让老数据一起“升级坏”

编辑器从4升到5，不只是前端组件替换，老页面里用HTML字符串保存的内容也会被新编辑器重新加载。有些老数据带着大量内联样式，CKEditor 5第一次加载时如果Schema不允许，这些样式会显示不出来。所以在升级前，要拿一批真实的老课件做回归测试，重点看标题、表格和图片。

我们平台当时做了一个共存期：编辑页默认用新编辑器，但提供“切换到旧编辑器”的入口，遇到格式兼容性问题时老师还能用老的编辑。共存期过了两个月，等熟悉了再把旧编辑器下线。这个方案虽然不是最优，但胜在平稳，不会出现老师正在备课结果编辑器突然不能用的情况。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

这张表我反复用过，基本能覆盖90%的工单。

5.2 排查顺序：先看源头，再改代码

接到格式问题的反馈，我习惯按照固定顺序排查，避免上来就改配置改了又没用。

第一步，让老师把原始Word文件发过来，确认文档里的实际样式。很多时候老师口中说的“三级标题”，在Word样式窗格里压根不是标题3。源头没问题，才谈得上后面的粘贴处理。

第二步，自己在浏览器里复制粘贴做个对照实验。用我们刚才那段paste监听代码，把原始HTML打出来，看Word产出的HTML里有没有outline-level、有没有mso样式、有没有<style>标签。

第三步，把原始HTML手动丢进编辑器的源码模式，逐个删节点看哪个标签被过滤。这样能快速定位是ACF的问题，还是插件翻译的问题。

5.3 图片和公式的特殊处理

Word粘贴的图片在HTML里经常有两种形态：一种是<img src="data:image/png;base64,...">，一种是<img src="file:///C:/...">。前者保存到数据库后内容体积会很大，后者根本没法显示。建议写一个上传中间件，检测到粘贴内容里的图片地址是base64或者file协议时，自动把图片转存到对象存储，再把src替换为线上地址。

教育平台尤其要处理公式。如果粘贴的是MathType的OLE对象，CKEditor拿到的基本是个不可用的形状；如果平台支持LaTeX，最好提醒老师用平台的公式编辑器重新录入。这一点靠插件没法自动解决，产品设计上要给老师提供清晰入口。

5.4 安全过滤不能放松

既然要保留格式，就必然要放开一些样式白名单。但是要时刻记住，放开不是放开到裸奔。script、iframe、style、object这些标签一定要在禁用列表中。Word粘贴的HTML虽然不带恶意脚本，但老师的电脑如果中了网页病毒，剪贴板里的HTML可能有附加内容，编辑器一旦执行就出问题。ACF本身就是安全闸门，不要为了方便把它关掉。

6. 一些非技术层面的心得

6.1 格式保留的核心是“取舍”

在网页上100%还原Word的布局是不现实的。Word是纸张思维的产物，有分页、有页边距、有网格，网页则是流式的。所以“保留格式”的目标不是让页面看起来和Word一模一样，而是把结构信息（标题层级、段落、表格、图片）完整保住，呈现交给CSS去统一。

理解这个取舍，你就不会陷入“这个mso样式为什么删了”的纠结——有些样式删了就删了，反而让网页更干净。

6.2 给老师设计“二次整理”工具

即使配置做到位，从Word复制过来的内容也不可能永远完美。教育平台的编辑器，最好提供一个“清除格式”按钮和一套风格统一的预设模板（比如“课程讲义”模板、“试卷”模板）。老师粘贴后，一键套模板，标题、正文字体、间距立刻统一。这比让老师手动逐行改高效得多，也符合实际工作流。

6.3 沉淀一份平台的“粘贴规范”

技术解决了大部分问题后，剩下的少数问题要靠规范。我后来给平台写了一页很短的粘贴说明：不用格式刷伪造标题、表格尽量从Excel粘贴、图片先另存到本地再插入。配合编辑器的自动处理，工单量直线下降。别小看这种非技术手段，它其实是让系统跑得最稳的润滑剂。

最后说点个人感受。我刚接手那个教育平台的时候，几乎每周都有老师反馈粘贴格式问题，一度想通过关掉ACF来解决，结果越改越乱。真正花时间把Word的HTML结构、CKEditor的过滤规则、不同客户端的转换差异摸清之后，问题才一个个从根上解决。后来平台上线了这套方案，格式类的工单大概少了六成，最让我高兴的是有老师主动说“现在粘过来基本不用调了”。

如果你现在也被类似问题折磨，建议从第3节的配置开始试，别一上来就改代码。先把插件的关键参数和ACF白名单配好，再拿一份真实Word文档反复粘贴测试，你很快就能找到那个让老师满意的平衡点。