最近一年我至少在四个项目里碰到同一个需求：在页面上直接看到 Word 文档的内容，而不是让用户下载下来用本地软件打开。产品侧的说法五花八门——“合同预览”“简历解析”“公告导入”“把老文档批量搬进富文本编辑器”——但落到技术侧都是同一件事：把一个 Doc/Docx 文件在浏览器里变成 HTML。
先把预期摆正，因为这是后面所有技术决策的前提：在纯前端做这件事，能做到“内容和结构基本正确”，但做不到“打开和 Word 一模一样”。前者 mammoth 这类库已经相当成熟，后者需要一整套排版引擎，前端基本没戏。而如果你的文件是老版.doc，抱歉，纯前端连门都进不去。这篇就按我自己踩过的顺序，从格式本质讲到 React 里的封装，再讲到样式保真的现实边界和排查链路，把这条链路完整走一遍。
1. 先认清 .doc 和 .docx 的格式本质，它直接决定前端能不能做
1.1 一个是可以解压的 zip，一个是二进制黑盒
这个区别值得放在最前面，因为太多人栽在这里。.docx从 2007 版开始就是 OOXML 标准，它的物理形态是一个标准 ZIP 包，你用任何解压工具改后缀都能打开看。里面的目录结构大致是这样：
document.docx ├── [Content_Types].xml ├── _rels/ │ └── .rels └── word/ ├── document.xml ← 正文内容，核心 ├── styles.xml ← 样式定义 ├── numbering.xml ← 编号列表定义 ├── settings.xml ├── fontTable.xml ├── media/ ← 图片资源 │ ├── image1.png │ └── image2.jpeg └── _rels/ └── document.xml.rels ← 资源关系映射关键点在于word/document.xml是一份结构清晰的 XML，段落是<w:p>，文本片段是<w:r>，文字本身在<w:t>里，表格是<w:tbl>。这个结构虽然啰嗦，但是可解析、可映射。前端只要能拿到 ArrayBuffer，解压、读 XML、转 DOM，整条链路都在自己手里。
.doc完全是另一回事。它用的是 CFB（Compound File Binary Format），也叫 OLE2 复合文档，本质是一个小型的“文件系统容器”，内部按扇区存放若干条“流”。正文在WordDocument流里，而且这条流的数据布局是微软私有格式，包含 FIB 文件信息块、片段表（piece table）、字符流与格式化流的交叉引用。这套结构有公开文档，但实现复杂度远超一个业务项目的承受范围，而且不同版本、不同生成工具产出的.doc还各有各的怪脾气。
我做过一次实测：拿一份 20 页的.doc用某开源解析库尝试在前端读，能读出部分纯文本，但段落边界错乱、表格全丢、中文偶发乱码。这种结果拿去做预览，产品经理第一眼就会来找你。
1.2 碰到 .doc 时值得认真考虑的三条路径
第一，服务端兜底转换。用户上传.doc，后端调一个文档转换服务（办公套件命令行工具很常见），先统一转成.docx或 PDF，再回传前端。这条路径最稳，代价是引入了服务端依赖和排队延迟，适合低频、非实时场景。
第二，引导用户另存为。在上传环节就做格式白名单，只接受.docx，用户传.doc时给出明确提示：“请用 Word 打开后另存为 .docx 再上传”。听起来很土，但转化率其实不低，尤其是内部系统。我们有个后台项目用了这招，明确写在帮助文档里，投诉量几乎为零。
第三，分级降级。.docx走完整转换链路，.doc只做纯文本提取 + 提示“格式可能有损，建议下载原件查看”。
我的选择原则很简单：这个功能是不是核心链路。如果是合同、发票这类对内容准确性要求极高的场景，别在前端硬扛.doc，直接堵在入口。如果只是给用户"大概看一眼"，降级方案能接受。
2. 前端转换方案的横向对比与选型依据
2.1 三类方案的能力边界完全不同
市面上能搜到的名字大概有 mammoth、docx-preview、docxtemplater、jszip 手搓、以及一些封装好的在线预览服务。它们解决的根本不是同一个问题，选错方向会浪费大量时间。
| 方案 | 输出形态 | 保真度 | 可否二次编辑 | 体积 | 适用场景 |
|---|---|---|---|---|---|
| mammoth.js | 语义化 HTML 片段 | 中（结构准，样式弱） | 可以，输出干净标签 | 约 300KB | 内容导入、富文本回填、结构化提取 |
| docx-preview | 带绝对定位的 HTML+CSS | 高（还原版面） | 基本不行 | 较大 | 纯预览、只读展示 |
| 自研 JSZip + XML 解析 | 完全自定义 | 取决于你写多少 | 完全可控 | 最小 | 结构极简或要求特殊映射 |
| 服务端转 PDF 后前端渲染 | 图片/PDF | 最高 | 不行 | 前端极小 | 严肃的文档审阅 |
docxtemplater我要单独说一句：它的定位是模板填充，拿一个带占位符的 docx 模板，把数据填进去生成新文档，方向和"转 HTML"正好相反。把它当成转换方案会走很多弯路，我见过不止一个项目在这上面绕。
2.2 为什么默认选 mammoth，以及它的代价
mammoth 的定位是“把 docx 转成语义化 HTML”，注意“语义化”三个字。它关心的是“这是一个一级标题”“这是一个加粗的强调”，而不是“这个标题用的是小二号宋体、段前 12 磅、居左”。所以它输出的 HTML 里通常没有style属性，而是<h1>、<strong>、<em>、<ul>、<table>这样的标签。
这个特性在“内容导入”场景是巨大优势：你把一段 Word 内容灌进富文本编辑器，希望的是干净的语义标签，而不是一堆内联样式把编辑器搞崩。我之前有个项目用别的方案，导入后编辑器里全是<span style="font-family:宋体;font-size:10.5pt">，用户编辑时字体乱跳，后来重写成 mammoth 才消停。
代价也很明确：它不管排版细节。字体、字号、颜色、行距、页边距、分页、页眉页脚、脚注、批注、文本框、公式、艺术字、浮动图片的文字环绕，统统不还原或者直接丢弃。如果你的需求是"看起来像 Word 打印出来的样子"，那应该去看 docx-preview，或者干脆服务端转 PDF。
我在项目里的默认策略是：mammoth 打底做内容层，再叠加一层自研的样式映射表来补足高频样式需求，比如把中文公文常用的“标题 1/2/3”映射成带 class 的<h1>~<h3>，把“正文”映射成<p class="doc-body">，然后由我们自己写 CSS 控制字号字体。这样保真度和可控性达到了一个不错的平衡点。
3. mammoth 的内部转换链路：OOXML 到 HTML 中间发生了什么
3.1 从 document.xml 的段落、运行与编号说起
理解这层链路的价值在于：出问题时你知道该去哪一层看。整个流程可以拆成四步。
第一步解包。mammoth 内部用 JSZip 把 ArrayBuffer 解成文件树，拿到word/document.xml、word/styles.xml、word/numbering.xml、word/_rels/document.xml.rels这几份关键文件。
第二步建关系表。document.xml.rels里记录着rId5 → media/image1.png这样的映射。为什么要这一步？因为正文 XML 里引用图片不是写路径，而是写r:embed="rId5"，得靠关系表才能找到真实文件。
第三步把 XML 转成内部文档模型。这一层是 mammoth 自己的抽象，它会把<w:p>拆成"段落节点"，把段落下的<w:r>（run，可以理解为一段格式一致的文本）拆成"文本节点"，同时带上样式名、是否加粗斜体、是否超链接、是否是图片等信息。这里有个重要概念叫run 的合并：如果连续几个 run 格式完全一致，mammoth 会尝试合并，避免输出一堆碎片化的标签。
第四步按 styleMap 规则生成 HTML。这一步是纯映射，输入是内部文档模型，输出是 HTML 字符串和一份 messages 数组。
messages这个返回值很多人忽略，但它非常有用。它是一个告警列表，每条包含 type（warning/error）和 message，比如"unrecognised style: 图表标题"、"An image of type image/x-emf is unlikely to display in web browsers"。我在开发阶段会把 messages 全量打印出来，它能直接告诉你哪段内容被丢掉了，比自己猜快得多。
const result = await mammoth.convertToHtml({ arrayBuffer }, options); console.log("HTML 长度", result.value.length); result.messages.forEach((m) => console.warn(m.type, m.message));3.2 styleMap：把 Word 的样式名翻译成 HTML 标签
这是 mammoth 最需要动手配置的部分，也是决定输出质量的关键。它的语法是匹配器 => HTML路径，左边按 Word 的文档结构匹配，右边决定输出什么标签。
const options = { styleMap: [ // 段落样式名匹配，:fresh 表示强制新起一个元素不合并 "p[style-name='Title'] => h1.doc-title:fresh", "p[style-name='标题 1'] => h1:fresh", "p[style-name='标题 2'] => h2:fresh", "p[style-name='标题 3'] => h3:fresh", // 字符样式匹配（run 级别） "r[style-name='Strong'] => strong", "r[style-name='Emphasis'] => em", // 自定义样式输出带 class 的 div，方便自己写 CSS "p[style-name='提示框'] => div.doc-tip:fresh", // 兜底规则：所有没匹配上的段落都输出 p "p => p:fresh", ], // 保留空段落，某些排版场景靠它撑间距 ignoreEmptyParagraphs: false, // 允许 docx 内嵌的样式映射覆盖（默认 true） includeEmbeddedStyleMap: true, };这里有几个实战要点值得单独强调。
中文样式名要能匹配上。Word 中文版的"标题 1"和英文版的"Heading 1"在 XML 里<w:styleId>可能都是Heading1，但<w:name w:val="..."/>存的是本地化名称。用户从不同语言环境保存的文档，样式名写法不同。所以我的 styleMap 一般会写成多套并列：
"p[style-name='Heading 1'] => h1:fresh", "p[style-name='标题 1'] => h1.fresh",注意这里我故意写成h1.fresh——这是个错误写法，不存在的，正确的强制新元素语法是冒号加 fresh：h1:fresh。我把它放在这里是提醒你：写错的时候 mammoth 不一定报错，可能只是静默地按默认规则处理，然后你在页面上看到两个标题粘在了一起。判断依据就是看messages，或者直接看输出 HTML 里有没有连续的<h1>标题一标题二</h1>这种明显异常。
p => p:fresh这条兜底规则很关键。不加它，非标准样式的段落可能输出成裸文本拼接，段落边界丢失。加上之后至少保证每段有标签包着。
不要指望 styleMap 能处理字体和颜色。它只能映射标签层级和 class 名称，具体长什么样靠你自己的 CSS。这也是我推荐的做法：把样式职责从 Word 手里接过来，交给前端样式表统一控制，视觉一致性反而更好。
3.3 图片走的是关系表加回调，base64 还是 blob 要想清楚
mammoth 对图片的处理是暴露一个convertImage钩子，你拿到图片对象后自己决定怎么产出src。实测下来有两个成熟做法。
// 方案 A：转 base64 内联，HTML 自包含，但字符串会膨胀 const optionsA = { convertImage: mammoth.images.imgElement(function (image) { return image.read("base64").then(function (base64) { return { src: "data:" + image.contentType + ";base64," + base64, }; }); }), }; // 方案 B：转 blob URL，内存占用小，但需要手动回收 const objectUrls = []; const optionsB = { convertImage: mammoth.images.imgElement(function (image) { return image.readAsArrayBuffer().then(function (buffer) { const blob = new Blob([buffer], { type: image.contentType }); const url = URL.createObjectURL(blob); objectUrls.push(url); return { src: url }; }); }), };选哪个？看使用场景。如果是"转换完就存进数据库/富文本编辑器"，base64 更合适，因为 HTML 自包含，序列化后不会因为刷新页面丢图。缺点是 base64 相比原始字节膨胀约 33%，一份 5MB 图片的文档转换后 HTML 可能 7MB 上下，塞进数据库字段或者 React state 都会很难受。
如果是"只在当前页面预览"，blob URL 更划算，DOM 里只存一个短字符串。但一定要记得回收：组件卸载、重新转换、路由切换时把objectUrls里所有 URL 挨个URL.revokeObjectURL。这一条我踩过实打实的坑——一个简历预览页，用户来回切了二十份简历，Chrome 任务管理器里该标签页内存从 80MB 涨到 900MB，原因就是 blob URL 一直没释放。
4. 在 React 里把它封装成可复用转换能力的具体做法
4.1 文件读取、格式校验与一个必踩的打包坑
先说一个几乎百分百会遇到的问题：npm 装下来的 mammoth 默认入口是 Node 版，在浏览器里直接用会报fs、path找不到。你需要引浏览器构建版本。
// 报错的写法（默认走 node 入口） import mammoth from "mammoth"; // 正确的写法：显式指向浏览器构建产物 import mammoth from "mammoth/mammoth.browser";不同构建工具（webpack / vite / rspack）对深层路径的处理略有差异，有些会提示找不到模块。稳妥写法是查一下包内实际文件路径，通常是mammoth/mammoth.browser.js。Vite 项目里如果还有问题，可以在optimizeDeps.include里加上这个路径强制预构建。
文件读取部分，我推荐统一走 ArrayBuffer，比 FileReader 的 readAsDataURL 干净：
async function readAsArrayBuffer(file) { return await file.arrayBuffer(); } function validateFile(file) { const MAX_SIZE = 20 * 1024 * 1024; // 20MB const name = file.name.toLowerCase(); if (name.endsWith(".doc")) { throw new Error("DOC_LEGACY"); } if (!name.endsWith(".docx")) { throw new Error("UNSUPPORTED_TYPE"); } if (file.size > MAX_SIZE) { throw new Error("FILE_TOO_LARGE"); } }注意这里用后缀判断而不是file.type。原因很实在：.docx的 MIME 类型在不同系统不同浏览器下可能是application/vnd.openxmlformats-officedocument.wordprocessingml.document，也可能是空字符串，甚至被识别成application/octet-stream。以前有个用户从某网盘下载的文件，MIME 是空的，按 MIME 校验直接被拒，投诉说"我的文档明明是对的"。改成后缀判断之后问题消失。
4.2 大文档卡主线程的问题，以及 Web Worker 的接入方式
mammoth 的转换是同步 CPU 密集操作。一份 3 万字的文档配十几张图，主线程能卡 3~8 秒，期间页面完全无响应，用户点按钮没反馈，会一直点，最后触发多次转换，内存直接起飞。
标准解法是丢进 Web Worker。mammoth 的浏览器构建在 Worker 里是可以跑的，关键是把 ArrayBuffer 用 Transferable 传过去，避免结构化克隆的开销。
// convert.worker.js import mammoth from "mammoth/mammoth.browser"; self.onmessage = async (e) => { const { id, buffer, styleMap } = e.data; try { const result = await mammoth.convertToHtml( { arrayBuffer: buffer }, { styleMap, ignoreEmptyParagraphs: false } ); self.postMessage({ id, ok: true, html: result.value, messages: result.messages, }); } catch (err) { self.postMessage({ id, ok: false, error: err.message }); } };// useDocxConverter.js import { useCallback, useEffect, useRef, useState } from "react"; export function useDocxConverter() { const workerRef = useRef(null); const pendingRef = useRef(new Map()); useEffect(() => { const worker = new Worker( new URL("./convert.worker.js", import.meta.url), { type: "module" } ); worker.onmessage = (e) => { const { id, ok, html, messages, error } = e.data; const task = pendingRef.current.get(id); if (!task) return; pendingRef.current.delete(id); ok ? task.resolve({ html, messages }) : task.reject(new Error(error)); }; workerRef.current = worker; return () => { worker.terminate(); pendingRef.current.clear(); }; }, []); const convert = useCallback((arrayBuffer, styleMap) => { return new Promise((resolve, reject) => { const id = crypto.randomUUID(); pendingRef.current.set(id, { resolve, reject }); workerRef.current.postMessage({ id, buffer: arrayBuffer, styleMap }, [ arrayBuffer, ]); }); }, []); return { convert }; }这段代码里有三个细节值得说。第一，transfer 之后原 buffer 会被置空，所以调用方不能再拿它做别的事，要么先复制一份buffer.slice(0)，要么保证传进去就不再用。第二，pendingRef用 Map 存 Promise 的 resolve/reject，是为了支持并发转换时能按 id 对上。第三，清理函数里必须terminate，否则 HMR 频繁热更时会积攒一堆 Worker，这个现象在开发环境特别恶心，表现为改了代码之后转换变慢、内存涨。
还有一点超出 Worker 方案范围的问题：如果文档特别大（比如 50MB 以上），光是 ArrayBuffer 本身就很占内存，Worker 加解压后的文件树会翻好几倍。这种量级我的建议是直接上服务端，前端不要逞强。
4.3 状态机、取消与大文件的分级反馈
别只用loading: true/false两个状态。用户上传后到看见内容之间可能有好几秒，中间什么都不显示就是灾难。我给的状态通常是idle | validating | converting | success | failed，每个状态对一句文案：
| 状态 | 界面反馈 | 触发时机 |
|---|---|---|
| validating | 校验文件格式 | 选中文件后瞬时 |
| converting | 正在解析文档，请稍候 | 进入 Worker |
| success | 显示预览 | 收到 HTML |
| failed | 分类错误提示 | 捕获异常 |
错误提示一定要分类。DOC_LEGACY就提示"暂不支持旧版 .doc，请另存为 .docx 后重试"，FILE_TOO_LARGE就说明 20MB 上限，PARSE_ERROR就提示文档可能已损坏。笼统的"上传失败"会让人反复试，增加你的日志量。
至于"取消转换"，技术上你可以terminate掉 Worker 再新建一个，但老实说在 10 秒以内的转换里，取消按钮的收益很低。我更倾向做防重入：转换中禁用上传按钮，用一个自增的 requestId 判断结果是否过期（用户快速换了文件时，旧结果直接丢弃）。
5. 样式保真的现实边界：哪些值得救，哪些别浪费时间
5.1 表格是最容易出问题的地方，合并单元格尤其要实测
mammoth 输出的表格是标准的<table><tr><td>，基础结构没问题，但有两个地方要特别注意。
一是合并单元格。横向合并（w:gridSpan）mammoth 会输出colspan，纵向合并（w:vMerge）会输出rowspan，这块基本可用。但复杂的斜线合并、嵌套合并、以及某些工具生成的畸形表格，输出可能错位。我的处理是一定要写一个固定的测试集，至少准备五份表格各异的文档：普通网格、横合并、纵合并、嵌套、跨页表格。每次升级依赖跑一遍，用肉眼对一遍。
二是表格样式全丢。边框、底色、列宽都不会保留，输出就是一个无样式表格。所以必须自己写 CSS：
.docx-content table { border-collapse: collapse; width: 100%; margin: 12px 0; } .docx-content td, .docx-content th { border: 1px solid #d9d9d9; padding: 6px 10px; vertical-align: top; word-break: break-word; } .docx-content table td p { margin: 0; }最后那条规则很重要。Word 表格里的每个单元格内容其实都包在<w:p>里，mammoth 会输出<td><p>内容</p></td>，而很多 CSS reset 会给p加上下 margin，导致单元格高度被撑开，看起来特别松散。清零之后视觉立刻正常。
另外表格宽度也要防一手。Word 里固定的列宽到网页上往往超出容器，加table-layout: fixed或者给max-width: 100%都能缓解，但真遇到超宽表，横向滚动容器比强行压缩更好读。
5.2 编号列表、页眉页脚、文本框：该放弃就早点放弃
多级编号列表是第二个高频问题。mammoth 能识别numbering.xml里的定义，普通有序无序列表没问题，但多级嵌套的编号格式（比如"1.1.1"这种带层级前缀的）还原经常不准，可能变成平铺的<ol>或者干脆丢了编号。如果业务对编号极度敏感，比如制度文件，我的做法是在样式表里给<li>加>import DOMPurify from "dompurify"; const clean = DOMPurify.sanitize(html, { ALLOWED_TAGS: [ "p", "br", "span", "div", "h1", "h2", "h3", "h4", "h5", "h6", "strong", "b", "em", "i", "u", "s", "ul", "ol", "li", "table", "thead", "tbody", "tr", "td", "th", "a", "img", "blockquote", "pre", "code", "hr", ], ALLOWED_ATTR: [ "href", "src", "alt", "title", "colspan", "rowspan", "class", "width", "height", "target", "rel", ], ALLOWED_URI_REGEXP: /^(?:https?|data|blob):/i, });
几个要点。ALLOWED_URI_REGEXP只放行 http/https/data/blob，直接掐断javascript:。a标签建议统一加rel="noopener noreferrer"，如果开了target="_blank"更是必须。class要保留，因为你的 styleMap 输出的 class 是样式控制的关键，砍了之后整篇文章就变白板了。
还有一点容易忽略：DOMPurify 清洗会改变 HTML 字符串，如果你后续要把 HTML 存库、或者在编辑器里二次编辑，清洗后的结果才是应该存的版本。先清洗再入库，别反过来。
6.2 base64、blob URL 和 React state 三处的内存账
内存问题在这类功能里格外容易翻车，原因是有三份数据同时存在：原始 ArrayBuffer（几 MB）、转换后的 HTML 字符串（可能十几 MB）、渲染进 DOM 后的节点树（内存占用可能是字符串的几倍）。三者叠加，一份 10MB 文档轻松吃掉上百 MB。
几个具体的做法：
第一，ArrayBuffer 用完立刻释放引用。Worker transfer 之后主线程那份就空了，正好，不要为了"还能重试"而留着。真需要重试就让用户重新选文件。
第二，blob URL 集中在转换结束时统一清理，包括转换失败的分支：
useEffect(() => { return () => { objectUrlsRef.current.forEach((url) => URL.revokeObjectURL(url)); objectUrlsRef.current = []; }; }, [html]);第三，HTML 字符串不要塞进 Redux 或者 Context 长期持有。它只应该在当前预览组件里存在，组件卸载就跟着走。我见过把转换结果直接 dispatch 进全局 store 的实现，导致切换页面之后整份 HTML 还挂在内存里，来回切几次直接把浏览器拖垮。
第四，如果确实要缓存转换结果（比如同一份文档用户会反复打开），缓存策略应该是存到服务端或者 IndexedDB，而不是内存。内存缓存只适合很小的文档。
7. 一次"转换成功但页面空白"的完整排查链路
7.1 现象描述与第一层定位
把事情讲具体一点。某次上线后收到反馈：某类文档上传后，控制台没有任何报错，状态也变成了 success，预览区就是一片空白。转换函数返回的确实是有内容的 HTML，长度还有几千字符。这种"有输出但看不到"的情况，比直接报错难查得多。
我的第一层动作是把 HTML 打出来看。不是看长度，是把前 500 个字符完整打印。结果发现输出的内容是这样的：一堆<p>里只有空格，正文一字没有。这说明问题不在渲染层，而在转换输入层——mammoth 读到的就是空段落。
第二层动作，解压源文件对照。把出问题的 docx 改后缀解压，打开word/document.xml，搜索正文里实际存在的那句话。结果一句话都搜不到。但文件里确实有个word/embeddings/目录，还有一个oleObject1.bin。
到这里根因就清楚了：这份文档的正文不是普通的段落文本，而是嵌入的 OLE 对象——用户在别的软件里粘贴进来一个对象，Word 把它整个存成了二进制嵌入内容，正文层只剩占位。mammoth 不支持解析 OLE 嵌入对象，自然什么都读不到。
7.2 修复方案与同类问题的排查清单
修复分两层。
第一层是用户可见的提示。既然解析不出内容，就不能假装成功。做法是对比输出 HTML 的"有效文本长度"（去掉标签和空白后的字符数）和文件大小，如果文件不小但文本极少，就提示："文档内容可能以嵌入对象形式存在，无法完整解析，建议下载原件查看"。这个判断很土，但非常有效，一次就覆盖了 OLE 嵌入、大量图片、文本框等多种情况。
function effectiveTextLength(html) { return html.replace(/<[^>]+>/g, "").replace(/\s/g, "").length; } if (effectiveTextLength(result.value) < 20 && file.size > 50 * 1024) { // 判为可疑，给出降级提示 }第二层是在开发期把这类异常暴露出来。我把result.messages里 type 为 error 的项全部收集起来上报，同时把"输出文本长度 / 文件体积"这个比值也带上。跑了一段时间后，发现了几类高频异常文档：扫描件转存成的伪 docx（正文全是图片）、带大量文本框的封面模板、以及从某些在线文档工具导出的结构特殊版本。这些数据直接指导了后续的提示文案和帮助文档。
顺着这条链路，我把这类"内容缺失"问题的排查步骤固化成了一份清单，遇到类似情况按顺序走，基本十分钟内能定性：
| 步骤 | 动作 | 判断依据 |
|---|---|---|
| 1 | 打印输出 HTML 前 500 字符 | 有标签无内容 → 输入层问题 |
| 2 | 解压 docx 看 document.xml | 搜不到正文 → 上下文不在常规段落 |
| 3 | 检查 media / embeddings 目录 | 有 oleObject → 嵌入对象，放弃 |
| 4 | 检查 txbxContent 出现位置 | 有 → 文本框内容，放弃 |
| 5 | 看 messages 里的 error 项 | unrecognised style / unsupported image |
| 6 | 换浏览器 / 换构建版本 | 排除 mammoth node 版被误引入 |
第 6 条单独说一下。有次排查了两小时，最后发现是某个依赖打包配置把mammoth的 node 入口一起打进去了，浏览器里运行时走了降级分支，静默返回了空字符串。判断方法是看typeof mammoth.convertToHtml是不是函数，或者直接看构建产物体积——如果 mammoth 只有几十 KB，那多半打错入口了，正常浏览器版三四百 KB。
最后再补一个我自己吃过亏的细节：不要把转换结果直接塞进一个带overflow: hidden的小容器里就完事。Word 文档里的表格和图片经常超宽，如果父容器把溢出裁掉，表现就和"内容丢失"一模一样，用户根本不知道右边还有内容。给预览区配一个横向滚动，或者至少overflow-x: auto，能省掉一批莫名其妙的反馈。这个坑我踩过两次，第一次查了半天转换逻辑，第二次才形成肌肉记忆——先看 CSS，再看转换。
