企业官网建设流程全解析

1. 先搞明白：Word 粘贴到网页为什么会“花”

1.1 剪贴板里装的不只是“文字”

很多同学遇到过这种情况：辛辛苦苦在 Word 里排版好的文档，复制到网页编辑器里，字体变成默认、表格挤成一团、图片全是裂的，更离谱的还会出现一堆奇怪的占位符和空行。大多数人第一反应是“这个编辑器太烂了”，但实际背锅的往往是 Word 生成的那份“HTML 副本”。

要解决“无格式丢失粘贴”，首先得知道剪贴板里到底装了什么东西。当你复制 Word 内容（Ctrl+C）时，系统剪贴板里其实同时放了多份数据：text/plain（纯文本）、text/html（带结构的 HTML）、text/rtf（富文本格式），有可能还有 image/png 这样的图片。浏览器在富文本编辑器里触发粘贴事件时，通常会优先读取 text/html 这层数据——注意这个“通常”，因为 Safari 和 Firefox 的取值优先级并不完全一样，后面我会单独说。

问题就出在 Word 生成的那份 text/html 上。它并不是干净整洁的 HTML，而是带着大量微软私有标记的“畸形文档”：标签层层嵌套、几乎每个 span 都挂着 mso-font-charset、“等线”“宋体”这样的命名空间，正文段落里塞着<o:p></o:p>空占位，表格每个单元格里写死了一堆 mso-border-alt 的边框声明，再往下翻还有<xml>定义、VML 矢量图形描述，甚至条件注释<!--[if gte mso 9]>这种只能在老 IE 里被识别的东西。

如果把这段 HTML 直接交给编辑器，绝大多数开源编辑器只做浅层清洗：过滤掉 script、iframe、事件属性这些明显危险的东西，然后把剩下的节点原样塞进去。结果就是：Word 的私有标记没有被解释成标准 CSS，反而以“残留样式”的形式污染了编辑器内容；本该由<ol>承载的自动编号变成一串纯文本数字；表格的固定布局和百分比宽度互相打架。这就是你看到“花成一片”的根源。

1.2 编辑器的默认粘贴流程为什么治不了

拿 WangEditor v5 来说，它默认的粘贴处理其实已经很克制了：会做 XSS 过滤、会合并一些重复节点、也会尝试收敛内联样式，但它不可能为 Word 定做一套语义恢复逻辑。原因很现实——编辑器不知道你粘贴来源是 Word、WPS 还是网页复制，它只能用一套通用规则去“猜”。

通用规则的下场往往是两个极端。要么过度清理：把所有内联样式全剥掉，只留文本内容和基本标签。这样安全是安全了，但用户的加粗、红色、字号、缩进全没了，文档结构直接腰斩。要么过度保留：把 mso-* 样式原样留在 style 属性里，编辑器界面上看不太出来，一导出 HTML 或 PDF，后端拿到的就是一堆无效声明，排版照样乱。

所以正确的做法不是指望编辑器“默认做好”，而是让它把粘贴流程交给我们自定义。这就是 WangEditor 一直保留customPaste事件的原因——你完全可以在粘贴事件进入编辑器默认处理逻辑之前把它拦截下来，自己处理 HTML，再通过dangerouslyInsertHtml插回去。

1.3 “无格式丢失”的验收标准到底定在哪

这里提醒一句：所谓“无格式丢失”不是像素级复刻 Word 显示效果。你是在网页里还原文档内容，不是在浏览器里再造一个 Word 排版引擎。硬要把每一磅字距、每一个段后间距、页边距、双下划线都搬过来，工作量巨大不说，意义也不大。

我一般按这个标准验收：

• 段落结构保留：标题层级、有序/无序列表、引用块、段落换行不丢。
• 行内样式保留：加粗、斜体、下划线、删除线、字体族、字号、颜色、上下标。
• 表格框架保留：行列数量、合并单元格、单元格宽度比例、边框可见性。
• 对齐与缩进保留：左对齐/居中/右对齐/两端对齐、首行缩进、悬挂缩进。
• 图片不裂：不管来源是 base64、本地文件路径还是剪贴板二进制，最终在页面上能真实显示。
• 公式可用：常见 Word 公式（OMML 或 OLE 对象）能转成前端可渲染的格式，而不是一张糊图。

做到这六条，用户在实际使用中就不会再抱怨“粘贴后格式丢了”。至于行距是 1.5 倍还是固定值 22 磅这种细节，明确告诉用户不支持，没人会纠结。

2. 方案选型：为什么绕不开 customPaste

2.1 WangEditor v5 的粘贴拦截机制

先说 WangEditor v5 的定制入口。新版编辑器把粘贴逻辑暴露为customPaste配置项，触发时机在内部默认粘贴处理之前。示例：

import { Editor } from '@wangeditor/editor' const editor = new Editor({ selector: '#editor-container', config: { customPaste: (editor, event) => { // 返回 false 阻止默认粘贴行为 return false } } })

更常用的写法是创建编辑器后，通过editor.on('customPaste', fn)挂载监听。两者的区别在于：config 里的函数在编辑器所有内部插件挂载完成前就会注册，适合做全局拦截；editor.on则适合组件内部动态控制。

需要注意一个关键点：只写 return false 是不够的，它只是告诉编辑器“你别动”，但你得自己完成 HTML 的插入。这时候editor.dangerouslyInsertHtml(cleanHtml)就是主角，它能绕过编辑器的二次过滤，把任意 HTML 直接插到光标位置。这个方法名字带 “dangerously” 是因为它信任调用者——我们自己在插入前做了安全清洗，所以没问题。

粘贴事件里能拿到的数据长这样：

editor.on('customPaste', (editor, event) => { const clipboardData = event.clipboardData // 或 event.originalEvent.clipboardData，取决于版本 const html = clipboardData.getData('text/html') const plainText = clipboardData.getData('text/plain') if (!html) { // 有些场景剪贴板只有纯文本，交给默认逻辑即可 return true } const cleanHtml = cleanWordHtml(html) // 安全考虑：只保留清洗后 HTML，移除原本粘贴内容 editor.dangerouslyInsertHtml(cleanHtml) return false })

这里有个很实在的细节：clipboardData.getData('text/html')在部分浏览器里拿到的 HTML 是以file:///开头的路径引用图片，而不是数据本身。这种情况我会在第 5 节展开讲，这里先埋个伏笔。

2.2 为什么不建议“先转纯文本再人工排版”

有些团队为了省事，直接在粘贴事件里clipboardData.getData('text/plain')，拿到纯文本后拆段落后插入。这种方案对“内容不敏感”的聊天框、评论区完全够用，但对企业后台、CMS 内容管理、协同编辑这种场景就是灾难。

我接过一个知识库项目，最早版本就是这么干的。用户从 Word 里复制一篇带三级标题、两栏表格、脚注的规范文档，粘贴过去后标题变成一行大字，表格变成一个长段落里的制表符空格，脚注直接消失。用户反馈永远是“你们这编辑器能不能用”，产品经理也没法跟用户解释“我们故意丢格式”。

最根本的原因是：纯文本信息熵太低。你可以通过正则把“1、”“1.”猜测成列表项，但你猜不回来第一段是什么字体、第二行是否居中、哪些字是红色加粗。HTML 虽然脏，但至少信息都在里面，我们有得选——选择性保留、转译、清理，主动权在自己手里。

2.3 整体处理链路

我的方案核心链路可以概括为五步：

1. 预清洗：先用正则把 XML 头、条件注释、<o:p>、<w:>这类无用节点剥掉，减少后续 DOM 遍历的负担。
2. DOM 解析：用DOMParser把清洗后的 HTML 字符串变成可遍历的节点树，不直接操作字符串。
3. 样式累积与转译：从根节点往下递归，把每一层节点的有效样式合并到一个“渲染上下文”对象里，再把微软私有属性转成标准 CSS 属性。
4. 结构重建：表格统一宽度比例、列表转成标准<ol>/<ul>、图片处理成可显示的真实data URL或blob URL、公式走 LaTeX 或图片兜底。
5. 序列化回插：把处理好的节点树序列化为 HTML 字符串，经 XSS 白名单过滤后，交给dangerouslyInsertHtml。

这五步缺一不可。尤其第 3 步是真正的“无格式丢失”核心，几乎所有格式错乱问题都出在“样式没有正确累积”上。

3. 核心实现：样式还原的细节拆解

3.1 DOM 解析与“样式累积”到底怎么算

Word 生成的 HTML 有个非常坑爹的特点：样式是分散在多层标签上的。一段红色加粗文字可能是这样的结构：

<h1> <span style="font-size:18.0pt;mso-bidi-font-size:16.0pt"> <span style="font-family:等线"> <b> <span style="color:red">这是标题</span> </b> </span> </span> </h1>

如果只取最内层<span>的color:red，字号、字体、加粗就丢了；如果只取最外层<h1>，颜色就丢了。所以在解析阶段，不能“就地覆盖”，而是要维护一个贯穿递归的样式游标——每进入一个节点，就把当前节点的样式合并到游标；该节点的最终样式，就是游标的当前快照。

下面是我常用的一段核心代码骨架：

function parseNode(node, styleCursor) { // 1. 提取当前节点的内联样式 const inlineStyle = node.getAttribute?.('style') || '' const styleObj = parseStyleToObject(inlineStyle) // 把 style 字符串解析成对象 // 2. 合并到游标（当前属性覆盖游标同名属性） Object.assign(styleCursor, normalizeWordStyle(styleObj)) // 3. 标签本身携带的语义，如 strong/b 自动加粗 if (['B', 'STRONG'].includes(node.tagName)) { styleCursor.fontWeight = 'bold' } if (['I', 'EM'].includes(node.tagName)) { styleCursor.fontStyle = 'italic' } if (['U'].includes(node.tagName)) { styleCursor.textDecoration = 'underline' } // 4. 叶子节点：生成带完整样式的 HTML if (node.nodeType === Node.TEXT_NODE) { return wrapTextWithStyle(node.textContent, styleCursor) } // 5. 递归子节点 const children = [] for (const child of node.childNodes) { children.push(parseNode(child, { ...styleCursor })) } // 6. 如果是 p / h1-h6 / li 这样的块级标签，输出块级结构 if (blockTags.has(node.tagName)) { return `<${node.tagName} style="${styleCursorToCss(styleCursor)}">${children.join('')}</${node.tagName}>` } return children.join('') }

上面{ ...styleCursor }每次递归传一个浅拷贝，保证兄弟节点之间的样式不会互相污染。这是我踩过坑之后才加的：一开始我直接传同一个对象，结果第一个子节点的颜色会“传染”给后面所有子节点，整个文档变成最后一种颜色。

真正解析样式时，不要用getComputedStyle——那个东西依赖浏览器渲染，粘贴的内容根本没进入文档流，算出来全是不准的值。直接读style属性字符串再用正则拆解就够。

normalizeWordStyle这一步负责微软私有属性转标准 CSS：

• mso-bidi-font-size映射为font-size（中文版 Word 常见，正文和中文字符分别定义字号，经常把真实字号塞在这里）。
• mso-font-charset、mso-hide这类直接丢弃。
• mso-char-indent-count转成text-indent，根据字号计算 em 值。
• mso-line-height-rule:exactly会配合mso-line-height-alt使用，转成固定行高line-height: 22pt这种。

字体族也要小写规范化：Word 里的是“等线”，网页里就得给font-family: 'DengXian', '等线', sans-serif这种带西文回退的写法，否则 Linux 和 macOS 上直接乱码。

3.2 Word 专属标记清理规则

预清洗我做了一层“暴力正则”，目的是在进入 DOMParser 之前先把体积降下来：

function quickClean(rawHtml) { return rawHtml // 去掉微软条件注释 .replace(/<!--\[if[^\]]*\]>[\s\S]*?<!\[endif\]-->/g, '') // 去掉 XML 声明和命名空间 .replace(/<\\?xml[^>]*>/g, '') // 去掉 o:p 占位段落（保留换行） .replace(/<o:p>[\\s\\S]*?<\\/o:p>/gi, '') // 去掉 v: 和 w: 前缀的标签（VML 矢量图和 Word 内部对象） .replace(/<\\/?[vw]:[^>]*>/g, '') // 去掉 mso-* 私有 CSS 属性和部分无用 class .replace(/mso-[a-z-]+:[^;]+;?/gi, '') }

正则只能做粗筛，像class="MsoNormal"、style="text-autospace:none"这些还需要后续 DOM 遍历时逐节点处理。这里提醒一句：清理完成后一定要把颜色、字号、字体这些关键声明重新提取，因为第 1.1 节里说过，Word 的样式往往是嵌套叠加的，正则一删可能把真实样式也误杀了。所以我的顺序永远是：临时提取关键样式存入游标 → 再清理无用属性 → 最后做序列化。

3.3 表格与列表的重建逻辑

表格是粘贴还原里最让人头大的部分。Word 导出的<table>有几个典型毛病：

• 每个<td>都有width: 123.4pt这种精确值，直接塞进网页，总宽经常超过容器宽度，把布局撑爆。
• 边框定义在mso-border-alt里，一套标准，但浏览器只认border/border-collapse。
• 合并单元格靠vMerge这种 Word 私有属性，而不是标准的rowspan/colspan。

我的处理策略是：

function normalizeTable(tableNode, containerWidth) { // 1. 强制定位布局改为自动，否则列宽卡死 tableNode.setAttribute('style', 'table-layout:auto;width:100%;border-collapse:collapse;') // 2. 遍历 td/th for (const cell of tableNode.querySelectorAll('td,th')) { // 去掉 mso prefix 的边框 cell.style.border = '1px solid #999' // 宽度按比例缩放 const ptWidth = parseFloat(cell.style.width) if (ptWidth) { // 如果容器约 800px，按 1pt ≈ 1.35px 估算，但总量超过容器要等比压缩 cell.style.width = Math.min(ptWidth * 1.35, 240) + 'px' } // 垂直居中还原 cell.style.verticalAlign = 'middle' } // 3. 把 Word 私有合并单元格属性转成标准属性 // vMerge 需要配合同一列里的 vMerge 标记判断 }

这里“1pt ≈ 1.35px”是经验值，Word 的 pt 在 96dpi 屏幕上确实等于 1.333px，但直接换算会出现几像素误差，影响不大。判断总宽是否超容器的逻辑也很简单：第一行所有 td 的宽度加起来，如果超过容器，就统一按比例缩小。

列表也一样。Word 的自动编号不是<ol><li>，而是每个段落都带着mso-list属性和text-indent，浏览器不认。最省事的做法是识别mso-list后面的级别值lfo1 level1，构建一个嵌套列表树，再把每个段落塞进对应层级的<li>。

正常情况下，识别出“有mso-list属性的段落”后，按它的缩进距离分层：缩进少的是一级，多的往深层挂。这样至少能保证“几级标题”和“项目符号”不丢。不过遇到编号格式（罗马数字、字母编号）实在没法完美还原，我只能保留数字序号文本作为兜底。

3.4 图片不是光有 img 标签就行

Word 内容里图片一般有两种形态：

• 新格式（Word 2016+）：直接是<img src="file:///C:/Users/xxx/AppData/Local/Temp/xxx/image001.png">。
• 老格式：VML 描述<v:shape><v:imagedata src="..."/></v:shape>，这个在预清洗阶段几乎被干掉了，需要额外捞回来。

不管是哪种，src里的本地路径浏览器是不可能直接加载的。真正的图片数据哪里找？答案在event.clipboardData里——浏览器复制时，通常会同时把图片以image/png类型塞进剪贴板数据项。

这种情况我写了一个“从剪贴板捞图”的工具函数：

async function getImagesFromClipboard(event) { const items = event.clipboardData?.items || [] const images = [] for (const item of items) { if (item.type.startsWith('image/')) { const file = item.getAsFile() if (file) { const dataUrl = await blobToDataUrl(file) images.push(dataUrl) } } } return images } function blobToDataUrl(blob) { return new Promise((resolve, reject) => { const reader = new FileReader() reader.onload = () => resolve(reader.result) reader.onerror = reject reader.readAsDataURL(blob) }) }

拿回来的图片数组怎么对应到 HTML 里的 img？我用的方法是：遍历提取出来的<img>标签列表，按顺序和图片数组一一匹配。然后给每个 img 替换src为对应的 data URL。实测下来，Word 复制图片的顺序基本和文档内顺序一致，所以这个粗暴匹配法在绝大多数场景下都能对上号。

如果剪贴板里确实没有图片数据（比如用户是通过拖拽而不是复制进入 Word 的），就只能退而求其次，显示为占位符，并在文章开头给个红色提示“图片未随文档复制”。这个提示看着简陋，但总比让用户觉得编辑器把图片吃了强。

4. 完整代码与落地步骤

4.1 编辑器初始化和事件绑定

先把 WangEditor 初始化写完整，并把粘贴拦截挂上：

import '@wangeditor/editor/dist/css/style.css' import { Editor, Toolbar } from '@wangeditor/editor' const editor = new Editor({ selector: '#editor-container', html: '<p>开始编辑...</p>', config: { placeholder: '请粘贴 Word 文档内容', // 关键：关闭默认粘贴行为 customPaste: true, } }) const toolbar = new Toolbar({ editor, selector: '#toolbar-container', mode: 'simple', // 或 'default' }) editor.create() editor.on('customPaste', async (editor, event) => { // 1. 先取 HTML let html = '' if (event.clipboardData) { html = event.clipboardData.getData('text/html') } // 某些浏览器没有 HTML，只有纯文本，走默认即可 if (!html) { return true } try { // 2. 大文档保护：超过 5MB 给提示，不做前端处理 if (html.length > 5 * 1024 * 1024) { alert('文档过大，请分段粘贴或上传附件') return false } // 3. 执行核心处理 const cleanHtml = await cleanWordHtml(html, event) // 4. 安全过滤 const safeHtml = xssFilter(cleanHtml) // 5. 插入编辑器 editor.dangerouslyInsertHtml(safeHtml) } catch (e) { console.error('Word 粘贴处理失败:', e) // 兜底：插入纯文本，至少不丢内容 return editor.insertText(event.clipboardData.getData('text/plain')) } // 6. 阻止默认粘贴 return false })

这里有个cleanWordHtml的异步版本，因为里面要读剪贴板图片转 data URL。如果你不需要图片，同步版本就行。

4.2 Core 处理函数：可以直接抄

下面整理了一个能跑的最小实现，注释写得很细。

import { DOMParser, XMLSerializer } from 'xmldom' // 或在浏览器环境直接用原生 async function cleanWordHtml(rawHtml, pasteEvent) { // Step 1: 正则预清洗，砍掉 Word 私有噪音 const quickCleaned = rawHtml .replace(/<!--\[if[^\]]*\]>[\s\S]*?<!\[endif\]-->/g, '') .replace(/<\\?xml[^>]*>/g, '') .replace(/<o:p>[\\s\\S]*?<\\/o:p>/gi, '') .replace(/<\\/?[vw]:[^>]*>/g, '') .replace(/class="Mso[^"]*"/gi, '') .replace(/mso-[a-z-]+:[^;]+;?/gi, '') // Step 2: 解析为 DOM const doc = new DOMParser().parseFromString(quickCleaned, 'text/html') const body = doc.body || doc.documentElement // Step 3: 从剪贴板捞图片，供后续替换 const clipImages = [] if (pasteEvent) { const items = pasteEvent.clipboardData?.items || [] for (const item of items) { if (item.type.startsWith('image/')) { const file = item.getAsFile() if (file) { const dataUrl = await blobToDataUrl(file) clipImages.push(dataUrl) } } } } // Step 4: 遍历 body 下所有 img，修复 src const imgs = body.querySelectorAll('img') imgs.forEach((img, index) => { const src = img.getAttribute('src') || '' // 本地方案 or 空 src：尝试用剪贴板图片替换 if (src.startsWith('file://') || src === '') { const clipSrc = clipImages[index] if (clipSrc) { img.setAttribute('src', clipSrc) } else { // 不能显示的图片给个占位 img.setAttribute('src', 'data:image/gif;base64,R0lGODlhAQABAAAAACw=') // 1x1 透明 gif img.setAttribute('alt', '图片未随文档复制') } } }) // Step 5: 清理 VML 里的 img（旧格式） body.querySelectorAll('v\\:imagedata, v\\:shape').forEach((el) => { const src = el.getAttribute('src') || el.getAttribute('href') || '' if (el.tagName.toLowerCase() === 'v:imagedata' && src) { const img = doc.createElement('img') img.setAttribute('src', src) img.setAttribute('alt', '图片') el.parentNode?.replaceChild(img, el) } else { el.remove() } }) // Step 6: 表格规范化 body.querySelectorAll('table').forEach((table) => { table.setAttribute('style', 'width:100%;border-collapse:collapse;table-layout:auto;') table.querySelectorAll('td,th').forEach((cell) => { cell.style.border = '1px solid #d0d7de' cell.style.padding = '4px 8px' cell.style.verticalAlign = 'middle' const rawWidth = parseFloat(cell.style.width) if (rawWidth && rawWidth > 0) { cell.style.width = Math.min(rawWidth * 1.35, 300) + 'px' } else { cell.style.width = 'auto' } }) // 去掉 mso 固定布局 table.removeAttribute('cellspacing') table.removeAttribute('cellpadding') }) // Step 7: 块级标签与文本样式累积 const output = normalizeBlockStyles(body) // Step 8: 序列化 return new XMLSerializer().serializeToString(output) }

第 7 步的normalizeBlockStyles就是我上面 3.1 节说的“样式累积”逻辑，这里不再重复。唯一补充一点：不要对整篇文档用一个大函数做到底，我实际开发时是拆成parseNode、normalizeInline、rebuildBlock三个函数分开维护的，这样后续要加“支持 WPS 粘贴”之类的需求时，改动面很小。

4.3 公式与特殊对象的进阶方案

热词里“公式转 LaTeX”非常高，这里我来系统讲一下。

Word 公式有两种常见形态：

• OMML（Office Math Markup Language）：文档里以<m:oMath>形式存在，正确的 HTML 副本里会有<m:oMath>标签。
• OLE 对象：MathType/AxMath 生成的公式，本质是嵌入对象，复制到剪贴板后多数变成图片。

OMML 的处理思路是“转成 LaTeX 再渲染”。前端没有一个特别成熟的 OMML→LaTeX 转换库，我用的方案是后端配合：将<m:oMath>抽取出来，POST 到后端一个 Java/Python 服务，用mathml2latex的 Java 移植版或 Python 的latex2mathml反向转换，拿到 LaTeX 字符串后再回来用 KaTeX 渲染。

前端部分的实现：

function extractMathNodes(body) { const mathNodes = body.querySelectorAll('m\\:oMath') const results = [] mathNodes.forEach((node, index) => { // 转成 MathML 字符串 const mathml = new XMLSerializer().serializeToString(node) // 塞一个占位，后续异步替换 const placeholder = document.createElement('span') placeholder.setAttribute('data-math-index', index) placeholder.textContent = `[公式${index + 1}]` node.parentNode.replaceChild(placeholder, node) results.push({ index, mathml, placeholder }) }) return results }

替换时把 MathML 交给后端转 LaTeX，再生成\(...\)文本插入到 KaTeX 容器里。这里有一个现实妥协：前后端转换链路搭建成本不低，如果项目只是偶尔粘贴几个公式，直接用图片兜底更快——设置一个convertFormulaToImage开关，当公式数量较少时就把<m:oMath>交给后端渲染成 PNG，然后当作图片插入。

MathType 公式转图片其实也有讲究：Word 内容里 MathType 对象一般以img带o:OLEObject属性出现，粘贴后图片往往能正常显示，但要检查图片清晰度。热词里“mathtype与word字号对照表”“axmath插入公式”其实说的就是这类流程——公式字号和文档正文字号不匹配，粘贴后要么糊要么突兀。前端能做的就是提取公式图片时，别过度压缩，保持原始分辨率。

5. 实测踩坑记录与排查表

5.1 表格越粘越宽的根源

我接手过一个文档系统，最经典的 bug：从 Word 粘贴一张 3 列的表格，第一次插入看着正常，但拖动编辑器的容器宽度变小后，表格不仅不随容器缩放，甚至把编辑器撑出横向滚动条。

排查到根因是 Word 给每个td都写了width:"123.4pt"，然后外层table还有一个mso-fixed-layout:yes的私有属性，浏览器会把这套固定布局当权威，无视父容器宽度。解法就是我代码里写的：把每个td的宽度过一遍压缩，并强制table-layout:auto。

另外一个隐性坑：Word 表格的列宽是按比例定义的，直接换算成 px 会过宽。我试过一张总宽度 500pt 的表格（约 675px），换算后塞进 800px 容器没问题，但在 600px 的窄屏容器里就溢出了。所以最终方案是统一把外层 table 设置为width:100%，内部单元格宽度写百分比，按每列原始 pt 占比换算，这样任何屏幕尺寸都不溢出。

5.2 图片全部裂掉的排查方法

“粘贴后图片全裂”这个投诉我收到太多次了，列一个排查顺序：

1. 先看img的src是什么。如果是file:///，浏览器加载不了，就按第 4.2 节的“剪贴板捞图”逻辑处理。
2. 如果src是data:image/png;base64,开头，那问题多半出在dangerouslyInsertHtml之后——检查是不是被编辑器的过滤规则吃掉了data:协议。WangEditor 默认配置里其实允许data:协议，但如果你自定义过安全策略，容易误伤，需要确认白名单里加了img[src^="data:"]。
3. 如果图片显示为 1x1 透明占位，说明剪贴板里根本没有这张图的二进制数据。检查用户的操作方式：从 Word 里“复制图片”而不是“复制文字含图”，前者剪贴板一般有图，后者不一定。

我在项目里还遇到过一种很诡异的情况：同一张图片在 Chrome 里能显示，在 Edge 里裂掉。最后发现是图片 data URL 过长（一张大图 base64 后可能几百 KB），Edge 对dangerouslyInsertHtml的 DOM 插入有性能限制，导致插入过程中被截断。解法是：粘贴的图片统一压缩，限制最长边 1200px、质量 0.8，用 Canvas 转一遍再插入。这样图片体积从几百 KB 降到几十 KB，两全其美。

5.3 大文档卡死、光标跳动与“粘贴后需要刷新”

文档超过 2MB 的时候，DOM 遍历和重建很容易让页面卡死。我在 pre-clean 阶段发现 70% 的标签都是o:p和空 span，先把这些筛掉能减少一半以上的节点数。如果体量还是很大，就分两批插入：先插入前半段，用requestAnimationFrame等下一帧再插入后半段，避免一次布局抖动。

“粘贴之后需要刷新”这个现象，本质是编辑器的内部 model 没有及时同步 DOM 变化。dangerouslyInsertHtml执行后，如果立刻调用editor.getHtml()，拿到的还是旧内容。我摸出来的规律是：插入后立即读取要等setTimeout(0)，但保险起见我一般等 100ms 再读，或者直接监听editor.on('change'事件里的内容变化。如果你的业务需要在粘贴后马上拿 HTML 去后端保存，记得加这个等待逻辑。

另一个和光标相关的小坑：Word 粘贴过来的内容尾部总会多一个<p><br></p>，插入后光标跑到段落末尾还带着一个看不见的空行。处理方式是清洗时把最后一个空块级元素删掉，插入前手动editor.restoreSelection()保证光标位置可控。

5.4 常见问题速查表

这个表基本覆盖了我见过的九成问题。它也是验收清单的一部分——每一项都可以做成测试用例，防止后续改动把功能弄坏。

最后分享两个小技巧

第一，清洗函数不要只服务 WangEditor。我后来把cleanWordHtml抽成了一个独立工具函数，里面不依赖任何编辑器 API，只处理 HTML 字符串。这样后端在导出 PDF 或生成静态页面时，能用同一套逻辑对历史数据做二次清理，前后的渲染结果一致性就好很多。

第二，别迷信正则。我最早也想用正则把 Word HTML 里的样式一次洗干净，但正则无法理解嵌套结构，写出来的 pattern 遇到复杂文档就失灵。后来老老实实切到 DOMParser + 递归遍历，代码虽然长了点，但行为可预期，边界情况也能兜住。我就是这么从“粘贴还原翻车”走过来的，你不妨也按这套思路，把公司的编辑器粘贴体验彻底收拾一遍。