Word文档样式迁移到编辑器的完整实践指南

我在互联网公司做了好几年的文档平台，天天和Office文档打交道。前段时间接到一个让我印象很深的活儿——业务部门要批量迁移几百份Word方案文档到公司自研的在线编辑系统里，内容不能丢是底线，连标题层级、表格边框、图注位置、双栏排版这些样式细节也得尽量还原。当时团队里不少人觉得这就是“复制粘贴”的事，结果真动手才发现，Word排版和网页编辑器之间隔着一道看不见的沟：同样的加粗，Word里有七八种写法；同样一个分页符，在网页里没有对应概念；甚至同一个段落间距，两个人的操作习惯不同，解析出来的结果就完全不一样。

这篇就围绕“Word文档到编辑器的样式迁移”这件事，把我踩过的坑、建立过的方案、沉淀下来的样式映射经验都整理出来。无论你是正在做富文本编辑器选型，还是被Word导入导出的格式问题折磨过，这篇应该能给你一个比较完整的参考路径。

1. 整体方案设计：样式迁移不是“格式搬运”，而是“语义翻译”

1.1 为什么直接复制粘贴走不通

很多人觉得Word文档粘贴到网页编辑器里很简单，Ctrl+C和Ctrl+V就完事。但真做过一次就知道，浏览器从剪贴板接收的HTML是非常混乱的，而且不同浏览器、不同编辑器、不同操作系统出来的结果都不一样。

我从几个维度拆一下这个问题。

第一，Word的“所见即所得”和网页的“CSS盒子模型”从根上就不一样。Word基于“页面流”排版，页面上有页边距、分页符、分节符，内容会跟着页面尺寸自动流动；而网页是流式布局，没有“第几页”的概念，也没有“页面底部最后一行”的概念。这就导致很多Word里的视觉样式，在网页里根本没有直接对应的表达方式。

第二，Word文档里的格式标记，大量是“隐性”的。比如某人为了对齐，敲了七八个空格；为了分页，连按了三个回车；为了让某个段落看起来居中，手动加了缩进。这些东西在Word里显示得“没问题”，但到了网页编辑器里就是一堆空段落和游离的空白文本。

第三，互联网公司的编辑器通常不只一种。有的是富文本编辑器（如Quill），有的是Markdown编辑器，有的是代码编辑器，还有大屏可视化编辑器、在线表单设计器这类垂直场景编辑器。不同编辑器的数据模型和渲染方式差异极大，不可能靠一套“万能转换器”通吃。

所以我在项目一开始就和团队定了一个基调：不能做“格式搬运”，而要做“语义翻译”。什么意思？不要追求每个像素都和Word一致，而是先把Word文档的结构和语义提取出来——标题几级、正文段落、列表层级、表格行列、图片引用——再把这些语义映射到目标编辑器支持的能力上。样式迁移的本质，是“把Word排版意图翻译成网页编辑器的语言”。

1.2 技术选型：解析层、转换层、注入层三层架构

定下“语义翻译”的思路之后，我们需要选技术方案。我当时的团队是Java加Python混合技术栈，前端是Vue全家桶，编辑器用的是基于Quill二次封装的富文本组件。基于这个背景，我设计了一套三层架构：

• 解析层：负责把docx文件读进来，提取文档结构和样式信息。
• 转换层：负责把解析结果转成HTML/CSS，同时做样式清洗和归一化。
• 注入层：负责把转换后的内容送入编辑器，并适配编辑器的数据格式。

解析层其实有两条路线可走。

路线一，用现成的转换库。比如前端的Mammoth.js、后端Java的Apache POI、Python的python-docx或pandoc。这些库能直接抽取文档正文和基础样式，Mammoth.js更是专门为“docx转HTML”设计的，开箱即用。路线二，自己解析docx。docx本身就是个zip包，里面是若干XML文件，核心的正文内容在word/document.xml里，样式定义在word/styles.xml里。这种路线灵活度高，能完全掌控解析逻辑，但开发量很大，要处理XML命名空间、各种异常标签、主题字体、编号定义这些底层细节。

我实验下来的结论是：如果项目周期紧、需求清晰，优先用Mammoth.js做第一版，它把文档结构、引用、样式、图片都处理得比较干净；如果后续要支持复杂的自定义排版，比如公文模板、学术论文格式，就再自研或二次封装解析逻辑。我当时是先上Mammoth.js完成了首轮验证，然后针对业务特有的双栏和目录需求，在转换层做了大量定制。

转换层的核心任务是样式清洗和语义映射，我会在下一节详细拆。注入层相对简单，因为我们的编辑器是Quill二次封装的，Quill自带clipboard模块，可以直接把HTML转成内部的Delta格式。但这里有个隐藏问题，Quill默认的clipboard行为在匹配样式时会做“合并去重”，比如连续两个相同格式的段落，它会自动合并成一段。这对纯文本粘贴是友好的，对样式迁移反而有害，因为它会破坏Word里含义不同的空段和分页结构。所以我在注入层做了额外处理，详细后面讲。

1.3 一套可复用的转换流程

整体流程可以画成一条流水线：docx -> 解析XML -> 中间JSON（语义化） -> 生成HTML -> 样式清洗 -> 归一化CSS -> 注入编辑器。

减少不必要的“把docx直接变成HTML再反向解析”的弯路。我建议始终保留中间JSON层，也就是文档的结构化描述。举例来说，Word里的标题来源可能有三种：真正的Heading样式、手写加粗的大字、编号加粗文本。如果直接转HTML，这三种都变成了<p><strong>xxx</strong></p>，后面的样式映射就没法区分了。但如果你在中间层记录“这个段落应用了名为Heading1的样式”，后面就能精准地还原标题层级。

这个设计看似多了一步，实际上为后续所有样式映射和问题排查提供了锚点。后面的章节我会按这个流水线逐个环节展开。

2. 核心细节拆解：Word样式体系与编辑器能力模型

2.1 docx文档格式：先说清楚Word到底存了啥

要理解样式迁移，先得知道docx里面有什么。docx是Office Open XML格式，本质是一个zip压缩包。你随便找个docx文件，把后缀改成.zip再解压，会看到这些目录和文件：

• word/document.xml：正文内容，所有段落、表格、图片引用都在这里。
• word/styles.xml：样式定义，比如“标题1”“正文”“引用”等命名样式。
• word/numbering.xml：编号定义，项目符号和自动编号的规则在这里。
• word/media/：图片、图表等资源文件。
• word/rels/：文档关系，告诉解析器哪些资源属于哪个位置。

document.xml里一段最简单的标题可能是这样：

<w:p> <w:pPr> <w:pStyle w:val="Heading1"/> <w:spacing w:before="240" w:after="120"/> </w:pPr> <w:r> <w:t>项目背景</w:t> </w:r> </w:p>

注意这里的关键信息是w:pStyle w:val="Heading1"，它指向styles.xml里的命名样式。这就是我在前面说的“语义锚点”。一个文档里，同样是视觉上看起来像标题的文字，如果用了Heading1样式，它就是真正的文档结构；如果只是手动加粗加大，那在样式迁移里就只是“加粗的段落文本”。

除了基础段落，Word里还有Section（分节符）的概念。分页、分栏、页眉页脚都是基于Section的。双栏布局就是通过Section属性里的<w:cols w:num="2" w:space="360"/>来设置的。这也是很多“双栏显示局部有空白无法删除”问题的根源——你删不掉的是分节符带来的区块边界，需要调整Section属性，不是删一两个回车能解决的。

2.2 Word里常见的样式类型和它们的“网页等价物”

我梳理了一份Word样式到网页样式的映射关系，整个迁移逻辑基本围绕这张表展开。

这里要特别提一下分页符。Word里有硬分页和软分页之分。硬分页是用户主动插入的分页符，在XML里能看到明确的w:br w:type="page"；软分页是Word根据页面大小自动生成的，不会在XML里出现。所以如果你在网页端想保留“每章另起一页”的效果，只能识别硬分页符，软分页是解析不到的。

2.3 编辑器端的“样式能力模型”决定迁移上限

样式的迁移上限，不完全由转换方案决定，也由目标编辑器的能力决定。我把互联网公司常见的编辑器按能力模型分成了几类。

第一类，富文本编辑器，代表是Quill、wangEditor、tinymce、以及Vue生态常用的vue-quill-editor。这类编辑器支持丰富的样式和结构，最适合承接Word文档迁移。但要注意，不同富文本编辑器的“语义化”程度不一样。Quill用的是Delta格式，它在插入带样式的文本时会比较“聪明”，会自动提取样式并生成attribute；tinymce更接近传统的contenteditable，粘贴时对HTML的保真度更高但更容易脏。

第二类，Markdown编辑器，代表是Typora、以及各类在线MD编辑器。Markdown的样式表达能力非常有限，标题、列表、引用、表格、代码块能支持，但Word里的双栏、任意字体颜色、任意段落缩进、复杂的嵌套表格都做不到。如果目标是Markdown编辑器，就必须对样式做“降级”——把承载语义的内容保留下来，把纯排版信息丢弃。

第三类，低代码/可视化编辑器，比如大屏可视化编辑器、表单设计器。这类编辑器一般有固定的组件模型，Word文档要转换为“组件配置项”，比如把标题映射为标题组件、把图片映射为图片组件。这种迁移更像“结构化抽取”，而不是样式还原，需要额外开发一套针对业务组件库的适配层。

第四类，代码类编辑器，比如VS Code、Zed、Vim。一般不会把Word直接迁到这类编辑器里，但如果业务有“把Word里的代码示例转成Markdown/代码块”的需求，也要考虑转义问题。Word里的代码片段往往保留了大量自动纠正过的引号和破折号，转换时要统一清洗。

我当时的目标编辑器是Quill二开版，能力模型偏第一类，但我们对表格和双栏做了不少增强。所以迁移策略很明确：先还原语义结构（标题、列表、表格、图片），再尽力还原排版（间距、字体、双栏、分页）。

2.4 样式映射表：一份要不断维护的“字典”

样式迁移能不能稳定运行，核心取决于样式映射表的质量。这个东西就像一个词典，左边是Word样式的特征，右边是目标编辑器的输出方式。

我这里给一个映射表示例，实际使用中需要按业务不断加条目。

有两点要注意。第一，Word里的单位和HTML里的单位不是一比一的。字号sz的单位是半磅，1磅等于0.35mm，所以sz=48其实是24磅；行距line的单位是1/240行；段前段后距的单位是1/20磅。换算错了，出来的页面会显得非常松散或非常拥挤。第二，样式映射表不是你定了就完事，随着业务方文档风格的增加，得持续维护。比如后来我们发现有人用“标题+副标题”的样式来模拟两级标题，就专门加了一条映射规则，把这些手工标题也转换成h2/h3。

3. 实操过程：一步步把Word文档迁移进编辑器

3.1 第一步：解包docx并读取document.xml

先说解析层的实操。如果用Mammoth.js，整个过程大概是这样的：

import mammoth from "mammoth/mammoth.browser.js"; const arrayBuffer = await file.arrayBuffer(); const result = await mammoth.convertToHtml({ arrayBuffer: arrayBuffer }, { styleMap: [ "p[style-name='Heading 1'] => h1:fresh", "p[style-name='Heading 2'] => h2:fresh", "p[style-name='正文'] => p:fresh" ] });

这个API的核心在于styleMap，它把Word里的命名样式映射到输出HTML的标签上。这里有个小技巧：加:fresh后缀，意思是不再继承样式名里的其他格式，直接从标题标签本身开始计算样式，这样能避免Word样式里残留的字体、颜色污染到输出。如果你想让mammoth保留部分内联样式，就不要加:fresh，或者用p[style-name='正文'] => p这种写法。

不过Mammoth在解析比较复杂的Word时也有不够用的地方。比如它处理并排表格、脚注、目录时比较乏力。所以我的做法是：Mammoth做第一道解析，拿到干净的HTML后，再配合正则和后处理补强。如果遇到Mammoth都搞不定的文件，我才降级到自研解析器处理。

我用python-docx自研解析时，代码大概是下面这个雏形。这里用Python是因为团队后端的文件处理服务就是Python的，两边好配合。

from docx import Document from docx.enum.text import WD_ALIGN_PARAGRAPH def extract_style(paragraph): p_style = paragraph.style.name if paragraph.style else "" pf = paragraph.paragraph_format info = { "style_name": p_style, "alignment": pf.alignment, "space_before": pf.space_before.pt if pf.space_before else None, "space_after": pf.space_after.pt if pf.space_after else None, "line_spacing": pf.line_spacing, "first_line_indent": pf.first_line_indent.pt if pf.first_line_indent else None, } return info

这是中间层JSON的雏形，记录每个段落的样式信息。实际生产里，我还会记录这一段落里每个run的字体、字号、加粗、颜色，以及它是否处于某个表格内部、某个分节内。因为后面做样式归一化时，这些信息越细越好。

3.2 第二步：把document.xml转成“干净”的HTML

转换层是整条流水线里最考验经验的地方。很多人直接从docx拿到XML就动手转HTML，结果出来的页面一屏都是冗余标签，样式乱成一锅粥。我的做法是分两步：先生成HTML骨架，再做全局清洗。

先说骨架生成。基于中间的JSON，逐段遍历生成HTML。每段根据style_name和run样式生成对应的标签和CSS。比如一个Heading1段落，生成<h1>；一个正文段落，生成带行距和首行缩进的<p>。这一步要尽量遵守“一个语义只保留一个标记”的原则。比如段落既设置了段前距，又设置了段后距，那就在p标签上设置margin，而不要同时塞一堆包裹用的div。

然后是全局清洗。Word生成的HTML里，最常见的垃圾包括：条件注释（<!--[if gte mso 9]>...<![endif]-->）、Mso样式（class="MsoNormal"、mso-开头的CSS属性）、命名空间残留（xmlns:w="urn:schemas-microsoft-com:office:word"）、空的span（<span style="mso-spacerun: yes;">）、微软专有的标签（<o:p>等）。

清洗用的正则不能盲目写，我提供一个基本可用的思路：

// 移除条件注释 html = html.replace(/<!--\[if[^]*?<!\[endif\]-->/g, ""); // 移除Mso样式类 html = html.replace(/\s*class=["'][^"']*Mso[^"']*["']/gi, ""); // 移除空span html = html.replace(/<span[^>]*>\s*<\/span>/gi, ""); // 清理mso-开头的CSS属性 html = html.replace(/(?:^|;)\s*mso-[^;]+/gi, "");

但是注意，清洗不能太激进。有些公司的CSS框架可能也带Mso之类的前缀，容易误删。所以生产环境里最好基于AST解析来做，而不是纯正则。比如用cheerio把HTML加载为DOM树，再遍历节点做清理和合并，这样更可控。

3.3 第三步：样式归一化——把“不同写法”统一成“一种输出”

这一步是“样式迁移”的题眼。Word文档里，同一个视觉样式可能有N种实现方式。比如粗体，可能用的是真正的<w:b/>，可能用的是样式表里的Strong，可能是用户手动把字号调大并加粗来模拟标题，也可能是复制网页内容时带过来的<span style="font-weight: 700">。

归一化的目标，是让最终HTML里表达相同视觉语义的标记尽量统一。我在项目里建立了一套规则，按优先级处理：

一是结构归一化。把h1-h6、p、ul/ol、table这些基础语义标签先归位。Word里如果标题样式被错误地应用在正文段落，我按content长度和是否含编号来做推断，但只作为低置信度信号。

二是内联样式归一化。把font-weight: bold合并成strong标签，把font-style: italic合并成em标签，把重复出现的color和background-color提取到统一class里。这里的目标是减少最终HTML的冗余，让编辑器渲染时更可控。

三是长度单位归一化。Word的pt在网页里一般换算成pt或px。我用一个基准值，把pt转成px，方便前端适配：

pt到px的换算：1pt = 96 / 72 px = 1.3333px

举例，Word里正文12pt，换算成网页就是16px。有人习惯直接用pt，现代浏览器也能渲染，但考虑到响应式和缩放适配，统一用px更稳妥。

四是空白字符归一化。Word里的全角空格、连续多个普通空格、不换行空格（\u00A0）都要处理。我的规则是全角空格转半角空格，连续超过两个空格的全部压缩成一个（除非它们是在<pre>代码块内）。

3.4 第四步：图片导出与路径替换

图片迁移是文档导入里最容易被忽略、但也最容易翻车的环节。Mammoth.js默认会把图片转成base64格式的data URI：

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAU...">

这在预览demo里没问题，但真正上线时，如果文档里有几十张大图，整个HTML体积会膨胀到几十MB，打开编辑器直接卡死。所以在生产环境里，我从来不用base64内联，而是把图片单独提取出来，上传到对象存储（或公司的图片服务），再把HTML里的src替换为线上地址。

具体做法是给Mammoth传一个convertImage回调：

const result = await mammoth.convertToHtml({ arrayBuffer: arrayBuffer, convertImage: mammoth.images.imgElement(async (image) => { const buffer = await image.read("base64"); const response = await uploadToOss(buffer, image.contentType); return { src: response.url }; }) });

这里有几个点容易踩坑。一是图片格式，Word里的图片可能是EMF/WMF这种矢量格式，浏览器根本显示不了，需要先转成PNG或SVG。二是图片方向，手机拍的照片插入Word后有旋转信息（EXIF），直接转出来会横着，需要读取exif处理。三是透明背景，Word里常见的PNG透明图，转成JPEG会把背景变黑，要格式判断处理。四是重复图片，同一个Logo在文档里出现了几十次，每次都要上传一次太浪费，要在convertImage里做缓存去重，用图片内容的哈希值做key。

3.5 第五步：双栏布局的网页端实现

双栏是Word迁移里最让我头疼的样式之一，没有标准解。我先说清楚现象：Word里的“双栏”是一个Section属性，意思是这个节的内容在页面宽度内平均分成两列，文字自动在左右栏之间流动，哪一栏先写满就自动流到下一栏。对应到网页，最接近的实现有两种。

第一种，用CSS多栏布局column-count: 2或columns: 2。这个方案的原生性最好，文字也是自动流动的，很适合纯文本文档。但缺陷很明显，编辑器的很多组件（表格、图片、自定义块）在多栏布局里容易发生奇怪的断行，而且Quill这类编辑器对column-count的支持并不稳定，一旦用户手动调整内容，布局会乱。

第二种，用表格布局或flex布局模拟双栏。这种方案更可控，适合“严格左半页内容、右半页内容”的文档，比如产品说明书里左右两栏分别是图文对照。实现上，我把Word的一个分节拆成两个并排的容器，手动把内容按位置分到左右两栏里。缺点是需要估算内容的高度来平衡两栏，逻辑比较复杂。

我当时最终采用了一种混合方案：优先用column-count，遇到包含表格或图片的复杂段落，则降级为表格布局。同时把分节符本身输出成一条可见的分隔线，方便用户在编辑器里感知到“这里原来有个分节”。

关于热搜里“word文档设置成双栏显示局部有空白无法删除”的典型问题，我在迁移中也遇到过。那个空白往往不是空段落，而是分栏设置里“分隔线”和“分节起始位置”叠加产生的占位区域。在Word里处理方式是把光标定位到分节符附近，打开页面设置，调整分栏间距，或把分节起始位置改成“接续本页”。迁移到网页时，如果直接忽略分节符，空白段落就会被原样保留，导致看起来“内容中间空了一大块”。所以清洗时要把孤立的分节符转成明确的分隔线，而不是留一堆空p标签。

3.6 第六步：目录与大纲的迁移

目录是Word文档里比较有特色的结构。Word目录本质上是一个域（Field），由标题样式自动生成，包含跳转链接。到了编辑器里，我一般做两件事：

第一件事，把目录提取出来，转成编辑器里的大纲导航。Quill本身没有层级目录概念，但可以通过标题标签的id生成一个右侧TOC列表。我这里需要在转换时给每个标题加上id，比如id="heading-1"、id="heading-2"，然后从HTML里收集所有标题标签，生成导航锚点。

第二件事，把Word自带的目录区内容清洗掉。因为目录区域在迁移后会变成一堆孤立的标题链接，和正文里的真实标题重复，如果不过滤，用户打开编辑器会看到两遍目录列表。我识别目录区域的方式是查找w:fldSimple w:instr=" TOC ..."或者w:fldChar对应的w:instrText。

热搜里“为啥word文档目录索引只有一级目录”这件事，我在迁移过程中也遇到过。原因一般是某个标题样式没有正确应用Heading2/Heading3，而是手写了加粗字体。Word目录生成的时候只认样式，不认视觉，所以层级缺失了。迁移时，我通过样式名和字体大小组合推断，把那些疑似标题但用了正文样式的段落提升为对应层级的标题，“强行”补回了层级。这个操作有风险，我在实现里加了人工确认的开关，只有在配置开启时才做推断。

3.7 第七步：注入编辑器与Quill适配

最后一步是把清洗后的HTML送进编辑器。Quill的注入方式很直接：

const quill = new Quill("#editor", { theme: "snow" }); quill.clipboard.dangerouslyPasteHTML(cleanHtml);

注意这里用的是dangerouslyPasteHTML，Quill会把它解析成Delta并插入到编辑器中。但这里有一个逆天的细节：Quill默认的clipboard模块带一个matchVisual配置，它会尝试把粘贴内容里的换行符“智能化”合并或拆分。这对样式迁移是个灾难，因为Word文档里的换行往往承载了排版意义，比如段前空行、分栏间隔。

处理方式是关掉matchVisual：

const quill = new Quill("#editor", { theme: "snow", clipboard: { matchVisual: false } });

如果用的是vue-quill-editor，配置也是类似的：

<quill-editor v-model="content" :options="editorOption" /> // editorOption里的clipboard: { matchVisual: false }

另外，Quill对表格、图片等非文本内容的处理需要额外的modules。我用的Quill二开版里，表格是自定义block，图片也封装了上传接口。注入之后，我还会跑一遍“归一化检查”：遍历Delta里的ops，检查是否有多余的换行、是否出现孤立的图片（src为空）、是否有颜色值为空字符串的样式。这些问题在Quill里都不会报错，但会让用户看到异常，所以用脚本做一轮自动检查是值得的。

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

做了一整轮Word样式迁移，我把实际遇到的高频问题整理成了一份速查表，基本对应了开头列的那些热搜词场景。这里直接分享出来，大家可以按图索骥。

除了这个表，我再分享几个“文档上看不到、实操中才遇到”的经验。

第一个是关于空段落处理的。Word文档天然有很多空段落，尤其是文档末尾和标题之间。直接迁移的话，编辑器里会出现大段空白，看起来很脏。我后来在清洗层加了一个“空段落压缩”逻辑：连续两个以上的空段落，只保留一个，并且把空段落统一转为带固定高度的CSS空行，而不是留多个<p><br></p>。这样既保留了“换行”的意图，又不会让页面出现过于夸张的空白。

第二个是字体家族的兜底。Word里很多中文字体（比如仿宋、楷体、黑体）在网页端不一定有对应的web字体。我的做法是在生成HTML阶段把字体族做一个映射，把Word字体名映射为编辑器预置的字体栈，比如仿宋映射为FangSong, STFangsong, sans-serif，黑体映射为SimHei, Heiti SC, sans-serif。这样至少保证用户看到的不是默认宋体。如果公司有买字库，可以把常见字体放在CDN里，然后直接引用。

第三个是编码和特殊字符。Word文档里的引号、破折号、<、>等字符，转到HTML后经常出现乱码或HTML实体问题。我的清洗规则是：在XML解析阶段就把所有文本统一转成UTF-8，然后在HTML生成阶段再用escapeHtml做一次转义，确保注入编辑器时不会把HTML标签画出来。这个步骤看着基础，但很多人忽略，最后导致页面内容显示错乱。

第四个是关于脚注的处理。Word脚注在Mammoth里默认是丢的，如果你不处理，迁移后脚注内容会消失。我在转换层专门加了一个扫描器，把所有脚注提取出来，拼接到文档末尾的“备注”区域，并在原文位置用括号数字标注引用位置。这个方案不算完美，但至少保留了信息。如果目标编辑器支持更强的块级组件，也可以做成提示框组件。

第五个是关于版本兼容。docx文件格式在不同Office版本间会有微小差异。同一段样式，WPS和MS Word生成的XML节点顺序可能就不同，不兼容会导致解析崩溃。我建议在服务端先做文件格式校验，比如用python-docx打开一次，如果打开失败就走第二套解析方案（比如Mammoth）。同时要给转换结果生成一个“置信度分数”，如果解析过程中遇到大量无法识别的标签，降级为“纯文本导入”模式，并在前端提醒用户手动调整。

5. 收尾：给后来者的一点心里话

样式迁移这事，表面上是个工具链问题，本质上是个产品问题。你迁移的不只是格式数据，更是用户对文档“看起来应该什么样”的心理预期。Word里一个标题的颜色、一个小数点的对齐、一张图的浮动位置，用户都记得，一旦迁移后稍有差异，就会觉得“系统不行”。但如果你在方案设计阶段就和业务方对齐好“语义迁移优先、像素级还原尽力而为”的原则，后面的一切争议都会小很多。

我的建议是，第一版上线时不要追求一次到位。流程上分三步走：先跑通docx到编辑器的基本解析，让所有文档能打开、能编辑；再完善样式映射表，把高频样式逐步还原；最后才做目录、分栏、脚注这些边缘功能的精细优化。每一步都做好日志和对比截图，用真实业务文档回归测试。别小看回归测试，Word文档千奇百怪，你永远不知道用户会用什么姿势排版，只有持续积累样例库，才能让迁移效果越来越稳定。

如果你也在做类似的事情，可以从我用过的方案直接起步：Mammoth做主干解析，Python脚本处理样式归一化，Quill关掉matchVisual后注入，图片一律走对象存储，分节符显式转为分隔线，目录自动提取为锚点导航。这套组合在我这边跑了半年，累计迁移了上千份文档，虽然不是百分百完美，但业务方已经能接受，日常使用里也没有出现系统性的大问题。

最后再分享一个我个人的小技巧：在转换层保留一份“原始文档结构JSON”和“迁移后HTML”的对照快照，一旦用户在编辑器里反馈排版异常，直接拿这两份数据做diff，能快速定位是清洗太狠还是映射表漏了规则。这一招帮我节省了大量排查时间，比你对着线上数据猜来猜去靠谱得多。