前后端联调的时候经常碰到一个需求“网页上能不能直接导入 Word 文档并且把图文格式都保留下来” 我去年在两个项目里都接到过类似的需求一个是内部知识库的文档上传预览一个是用户上传简历后自动解析生成结构化信息。市面上文档预览方案不少但真正落在“前端”这个边界上还要做到图文不丢、排版不难看其实没有想象中那么现成。这篇文章直接把我试过的方案、踩过的坑、能跑通的代码一起放出来给遇到同样需求的前端同学一个可复用的参考路径。先说结论纯前端解析 Word 并能保留图文格式可行但“保留格式”这四个字得定义清楚。它不等于像 Word/WPS 软件里那样一比一还原页面而是指正文结构、标题层级、图片位置、表格内容这些核心视觉元素能在网页里正常呈现。下面从文件格式开始一步步拆解。1. 为什么网页没法直接“读”Word文档先搞清 docx 的真实结构很多同学第一次接这个需求时下意识会写这样的代码const reader new FileReader(); reader.onload (e) { console.log(e.target.result); // 期望看到正文实际全是乱码 }; reader.readAsText(file);我最早也这么干过然后发现读出来的内容以PK开头后面跟着一堆不知所谓的乱码。这个现象本身已经说明了问题.docx 并不是一个纯文本文件而是一个 zip 压缩包。1.1 用一个解压工具看穿 docx 的骨架在终端里执行一下就能看得清清楚楚。把demo.docx当 zip 解压然后看目录结构unzip demo.docx -d demo_docx tree demo_docx你会看到一个类似这样的结构demo_docx/ ├── [Content_Types].xml ├── _rels/ ├── word/ │ ├── document.xml # 正文XML所有文字、段落结构都在这里 │ ├── media/ # 文档里的图片按 image1.png 编号存放 │ ├── styles.xml # 样式定义 │ ├── numbering.xml # 列表编号规则 │ └── ... ├── docProps/ └── ...document.xml负责语义结构比如标题、段落、表格、图片引用word/media/里才是真正的图片资源styles.xml定义了一套样式规则docx 里的标题为什么有大有小主要靠它。浏览器本身虽然有处理 Blob、ArrayBuffer 的能力但它不会主动帮你解压 zip更不会帮你解析 OOXML 那一套 XML 结构。所以我们的核心工作其实是想办法把 zip 里的内容解析出来再把 XML 描述的结构翻译成 HTML。1.2 docx 和 doc 是两个完全不同的物种提一个非常容易踩的坑.docx和.doc的解析路径完全不同。.doc是老版 Word 的 OLE 二进制格式里面的正文、图片、样式是按二进制结构存储的和.docx的 zip XML 方案八竿子打不着。我见过不少人在网页里实现 Word 导入时用户传了个.doc上来结果所有的解析库都报“格式不支持”。这不是库的 Bug是格式本身不同。如果是纯前端方案目前主流做法都只支持.docx。遇到.doc文件要么后端用转换服务把它转成.docx或 PDF 再处理要么在页面上明确限制仅支持.docx格式。这个限制在 UI 层就要写清楚别等用户传完才提示。2. 选型两个主力库mammoth.js 与 docx-preview 怎么定前端解析 Word 绕不开两个库mammoth.js和docx-preview。它们俩的核心逻辑完全不同选哪个取决于你的“保留图文格式”到底要的是哪种效果。2.1 mammoth.js把“文档语义”翻译成干净语义化 HTMLmammoth.js 的定位是转换器。它做的不是还原 Word 的页面排版而是把document.xml里的结构映射为干净的 HTML。比如Heading1→h1Paragraph→p表格 →tabletrtd图片 →img转换出来的 HTML 是一段语义清晰的富文本没有任何 Word 特有的标签污染CSS 全部由你自己的页面来控制。好处很明显解析结果可以存库、可以继续编辑、可以统一套上你网站自己的样式体系。坏处是Word 里那种复杂的页面版式比如分栏、固定页边距、图文环绕会丢因为 HTML 本身就没有“分栏”这个概念。2.2 docx-preview把“页面排版”尽可能还原成网页docx-preview 做的事情和 mammoth 完全相反。它会尽量把 docx 渲染成“看起来像 Word 里那样”的 HTML标题、页面宽度、分栏效果、表格边框都会尝试还原。输出的 DOM 带着大量内联样式和 Word 的排版逻辑一一对应。听起来是不是更符合“保留图文格式”的需求但它有几个实际问题输出 HTML 结构非常重一个简单文档说变出几千行 DOM内联样式巨大后续如果要“二次编辑”或“套用你自己的 UI 风格”会极其痛苦分栏、页眉页脚这类复杂版式也只是尽力还原不是完全等价复杂文档照样会错位。2.3 我的选型结论两边我都实际用过最终在产品里落地的是mammoth.js。原因可能和大家想的不太一样产品要的不是“打印效果”而是“网页阅读体验”。用户上传一份 Word网页预览时能看清标题层级、正文、图片、表格就够了没必要把 A4 页面尺寸也搬上屏幕。如果你的业务是“在线查看一个 Word 文件的实际排版”比如标书、合同、试卷这类对原版样式要求极高的场景那 docx-preview 在纯前端方案里更接近需求。但要提前做好心理准备它会把格式还原度做到七八成剩下两成还是要手动调样式。两个库的定位对比如下维度mammoth.jsdocx-preview核心定位docx → 语义化 HTMLdocx → 仿 Word 排版 HTML输出形态干净结构化 HTMLCSS 完全可控大量内联样式整体封装分栏支持不支持内容按顺序线性输出尝试还原但复杂分栏仍会偏移后续二次编辑容易前端富文本编辑器可直接接手困难DOM 太重图片处理可抽取 base64也可外链存储自动内嵌渲染适合场景知识库、CMS、内容上传解析合同预览、试卷展示、打印场景3. 用 mammoth.js 实现图文保留完整接入与 CSS 配套选定 mammoth.js 之后剩下的核心问题就是怎么把图片抽出来、怎么让转换后的 HTML 好看、怎么处理各种边界情况。3.1 最小可运行版本第一步先安装依赖npm install mammoth然后写一个最基础的“选择文件 → 解析 → 渲染”流程input typefile idwordFile accept.docx / div idpreview/divimport mammoth from mammoth/mammoth.browser.js; document.getElementById(wordFile).addEventListener(change, async (e) { const file e.target.files[0]; if (!file) return; // 校验文件类型和后缀doc 直接拦掉 if (!/\.docx$/i.test(file.name)) { alert(仅支持 .docx 格式); return; } // 读成 ArrayBuffer这是 mammoth 最常见的输入格式 const arrayBuffer await file.arrayBuffer(); try { const result await mammoth.convertToHtml({ arrayBuffer }); document.getElementById(preview).innerHTML result.value; // messages 里全是解析告警别忽略常见的有图片丢失、样式未识别等 if (result.messages.length 0) { console.warn(解析告警, result.messages); } } catch (err) { console.error(解析失败, err); alert(文档解析失败请确认文件未损坏且格式为 .docx); } });这段代码在本地就能跑通。file.arrayBuffer()是浏览器原生 API兼容性在最近三年内的浏览器环境下都没问题。比我以前用的FileReader.readAsArrayBuffer写法干净很多。3.2 图片保留是头等大事base64 内嵌与外链存储上面最小版本其实有一个大坑如果 Word 里带图片直接跑mammoth.convertToHtml转出来的 HTML 里图片是空的。原因在于 mammoth 默认没有开启图片转换你需要主动告诉它怎么处理图片。我项目里最初就是没配图片用户上传了一份带截图的 Word结果网页预览只有文字整个功能被否了。加上图片处理之后才恢复const result await mammoth.convertToHtml({ arrayBuffer, convertImage: mammoth.images.imgElement((image) { // 先把图片转成 base64 return image.readAsBase64().then((base64) { return { src: data:${image.contentType};base64,${base64}, alt: 文档图片, }; }); }), });如果图片不多这种内嵌 base64 的方式最简单转换结果是一个自包含的 HTML无论存库还是直接展示图片都不会丢。但 base64 内嵌有个问题图片越多HTML 越大。一张 2MB 的图片 base64 之后差不多 2.7MB一份图文并茂的文档转成 HTML 可能直接到十几 MB。这在前端预览时浏览器渲染扛得住但如果你要存数据库字段大小、请求传输都会很考验人。在生产环境里更好的做法是先把图片抽出来传到 OSS / 对象存储再在 HTML 里替换成外链。这时要把convertImage改成异步上传convertImage: mammoth.images.imgElement(async (image) { const base64 await image.readAsBase64(); const blob await (await fetch(data:${image.contentType};base64,${base64})).blob(); const url await uploadImageToOSS(blob); // 你自己的上传方法 return { src: url, alt: 文档图片 }; })注意这里mammoth.images.imgElement返回的也可以是一个 Promise所以 async 函数可以直接用。这个上传过程要在解析阶段完成而不是等 HTML 生成后再去遍历img标签换src会省很多事。3.3 让转换结果好看的配套 CSSmammoth转换出来的 HTML 骨架是干净的语义化标签但如果你的页面没有配套 CSS视觉效果肯定是没有的。我在项目里攒了一套专门给解析结果用的样式核心如下.docx-preview { max-width: 820px; margin: 0 auto; padding: 24px 32px; line-height: 1.8; color: #24292f; font-size: 16px; word-break: break-word; } .docx-preview h1, .docx-preview h2, .docx-preview h3 { margin-top: 24px; margin-bottom: 12px; font-weight: 600; } .docx-preview h1 { font-size: 26px; } .docx-preview h2 { font-size: 22px; } .docx-preview h3 { font-size: 18px; } .docx-preview img { max-width: 100%; height: auto; display: block; margin: 12px auto; } .docx-preview table { width: 100%; border-collapse: collapse; margin: 12px 0; table-layout: fixed; } .docx-preview td, .docx-preview th { border: 1px solid #d0d7de; padding: 8px 12px; } .docx-preview blockquote { margin: 12px 0; padding: 8px 16px; border-left: 4px solid #d0d7de; color: #57606a; background: #f6f8fa; } .docx-preview pre { background: #f6f8fa; padding: 12px 16px; border-radius: 6px; overflow-x: auto; }有几个细节值得单独说。第一是word-break: break-word。Word 文档里经常有超长的英文 URL、文件路径不处理会直接撑破页面产生横向滚动条观感极差。第二是表格宽度。Word 里的表格宽度是按纸张宽度定的到了网页里如果不加max-width: 100%和table-layout: fixed宽表格一定会溢出。我在处理时给表格的外层 div 加了水平滚动容器保证窄屏下用户至少能滑动看全内容.docx-preview table { width: 100%; table-layout: fixed; } .docx-preview table td { overflow: hidden; text-overflow: ellipsis; }第三是图片居中。Word 里的图片默认是嵌入文本流的但网页预览时用户更习惯看到图片居中所以我加了display: block; margin: 12px auto。如果你要完全按 Word 里的左右位置来排那就去掉这两行。3.4 用 styleMap 控制标题和字体映射有时候 Word 文档里用的不是标准“标题 1”而是自定义样式的段落比如手动加粗的大号文字。mammoth 默认会把这些转成普通p视觉层级就丢了。这时可以用styleMap手动指定映射关系const result await mammoth.convertToHtml({ arrayBuffer, styleMap: [ p[style-name标题 1] h1:fresh, p[style-name标题 2] h2:fresh, p[style-name正文] p:fresh, r[style-name强调] em, ], });写法上前面是 docx 里的样式名注意有的文档用中文名有的用英文名后面是你要映射的 HTML 标签。:fresh表示无视默认样式直接按新标签渲染适合强制套用你页面里已有的 CSS 类。字体映射也是一个容易被忽略的坑。docx 里如果指定了宋体、微软雅黑但转换出来你在网页上看着字体没变是因为 mammoth 保留的字体名在页面里没有生效。我在样式里直接统一处理.docx-preview { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Hiragino Sans GB, Microsoft YaHei, Arial, sans-serif; }这样至少保证中文环境下字体渲染最稳定不会出现 Windows 上正常、macOS 上字体发虚的情况。4. 双栏、空白、表格溢出Word 复杂版式在网页端的还原边界“保留图文格式”说完容易真遇到复杂文档时mammoth 的短板非常明显。我以前有个用户上传了一份双栏排版的 Word 试卷转换出来的 HTML 把两栏内容全部按顺序拼成了一列相当于把双栏文字全部合并成了单栏。用户反馈是“内容全乱了”这其实就是 HTML 模型和 Word 排版模型的本质冲突。4.1 为什么分栏在网页版永远做不到“完美还原”Word 的分栏是通过sectPr里的分节属性来实现的一个节可以包含多栏文本文字会在栏与栏之间自动流动。HTML 到目前为止都没有标准的分栏模型CSS 里虽然有column-count可以实现视觉上的分栏但它做不到像 Word 那样“第一栏满自动流到第二栏”的动态排版逻辑更没法精确处理分栏符、跨栏标题。所以如果业务流程必须保留分栏版式纯前端转换 route 走不通必须由后端把 docx 转成 PDF再用 PDF 渲染方案去展示。前端直接做最好的结果就是内容完整、顺序正确但版式变成单栏。这件事你在一开始就要和产品说清楚别等开发完再被挑战。4.2 Word 里“删不掉的空白”是什么热搜里有个问题Word 文档设置成双栏显示局部有空白却无法删除。很多同事在使用 Word 时遇到这个在网页端转换时也会遇到所谓奇怪的空段落。这背后的原因通常是分节符、分页符、文本框、或者页边距与分栏宽度设置不当造成的。前端解析时这些空白会以空p的形式存在你在渲染时处理一下// 过滤掉无意义的空段落 document.querySelectorAll(.docx-preview p).forEach((p) { if (p.innerHTML.trim() p.querySelector(img) null) { p.remove(); } });但注意不要一刀切把所有空p都删掉因为有些空段落是文档结构的一部分比如列表项后的间距。我的经验是先保留下载 Word 原文件功能网页预览只做“可读性展示”遇到空白格的差异不要在前端较劲因为源头在 Word 端网页端只能缓解不能根除。4.3 表格溢出和图片环绕的兜底方案表格溢出是另一个高频问题。Word 里一张 6 列的宽表到了网页上基本必溢出。我在预览容器上加了滚动容器div classdocx-preview div classtable-wrapper table.../table /div /div.docx-preview .table-wrapper { width: 100%; overflow-x: auto; }这样宽表格不会撑破页面用户横向一滑就能看全体验比硬压缩表格列宽好很多。图片的“文字环绕”效果在 Word 里可以选择嵌入型、四周型、浮于文字上方等。mammoth 转 HTML 时对这些基本没有对应实现环绕效果会退化成图片单独一行。前端能做的兜底是把图片统一max-width: 100%同时在图片下方加一个可选的图注说明或者干脆提示作者“复杂版式的图片请在 Word 中转为嵌入型再上传”。5. 大文档与生产环境从本地 Demo 到能上线的完整闭环本地 Demo 跑通只是第一步真正放到生产环境里还会遇到几个绕不开的问题大文档卡顿、解析耗时、图片存储策略、二次编辑能力。5.1 大文档卡顿用 Web Worker 把解析移到后台mac 上打开大型 Word 文档都会卡浏览器更不用说了。几十 MB 的 docxzip 解压 XML 解析全部在主线程里跑页面会直接冻结用户连个 loading 都看不到体验极其糟糕。我的做法是加一个 Web Worker 来跑 mammoth 解析。这里给一个最小实现worker.jsimportScripts(https://cdn.jsdelivr.net/npm/mammoth1.6.0/mammoth.browser.min.js); self.onmessage async (e) { const { arrayBuffer } e.data; try { const result await mammoth.convertToHtml({ arrayBuffer, convertImage: mammoth.images.imgElement((image) { return image.readAsBase64().then((base64) ({ src: data:${image.contentType};base64,${base64}, alt: 文档图片, })); }), }); self.postMessage({ success: true, value: result.value, messages: result.messages }); } catch (err) { self.postMessage({ success: false, message: err.message }); } };主线程const worker new Worker(new URL(./worker.js, import.meta.url), { type: module }); worker.onmessage (e) { if (e.data.success) { document.getElementById(preview).innerHTML e.data.value; } else { alert(解析失败 e.data.message); } loading.hide(); }; worker.postMessage({ arrayBuffer });这里有个细节mammoth.browser.js在 Worker 里可以用importScripts引入。如果用打包工具Vite/Webpack的话直接import mammoth并通过 Vite 的?worker后缀创建 Worker 会更优雅但importScripts的方式在原生环境里最通用。实际测试中一个 20MB 的图文混排 docx加 Worker 之前页面会卡 5~8 秒加完之后主线程一直流畅loading 动画正常转体验完全不一样。5.2 文件侧的限制与异常兜底生产环境里上传文件要做三层校验后缀校验、类型校验、大小限制。mammoth 对超大文件的解析很吃内存50MB 以上的纯前端解析我一般不建议做。做个简单的限制const MAX_SIZE 20 * 1024 * 1024; // 20MB if (file.size MAX_SIZE) { alert(文件超过 20MB请压缩后上传或使用后端解析服务); return; }另外mammoth 解析过程中会返回 messages里面经常会包含警告信息。比如某种样式未识别、某个图片提取失败。这些警告需要在开发阶段打出来排查否则线上出了问题连日志都没有。5.3 解析后的 HTML 怎么存、怎么二次使用解析完成后的 HTML 通常包含 base64 图片开箱就用但存储压力大。我在一个知识库项目里的做法是前端解析得到 HTML服务端把 HTML 里的data:image/...base64 图片提取出来单独存到对象存储将img标签的src替换成对象存储的外链最终只缓存替换后的 HTML。这样整个文档的 HTML 大小可以从十几 MB 降到几十 KB而且图片有独立 CDN 链路预览速度明显提升。如果是简单场景直接把data:image内嵌 HTML 存数据库也够用但要注意 MySQL 的TEXT字段只有 64KB图文混排文档很容易超得用LONGTEXT。这看起来是很基础的问题但我在线上真实遇到过文档解析出来 HTML 有 2MB存库直接被截断页面打开只有半截。5.4 从预览到编辑解析结果能不能回填富文本编辑器很多时候解析 Word 不只是为了预览还要支持用户“继续编辑”。mammoth 转出来的 HTML 是干净的语义化结构这给了我们一个天然优势可以直接喂给富文本编辑器。我自己对接过 Quill 和 TipTap效果都挺稳定。需要注意的坑主要是列表。Word 里手动打的“1. 2. 3.”编号在转换后如果 mapp 没配好会变成纯文本而不是无序列表ul。解决办法是在转换前做一次中转先用 mammoth 输出 HTML再用turndown之类转成 Markdown如果需要或者直接在 styleMap 里把List Paragraph映射成li相关的标记styleMap: [ p[style-nameList Paragraph] p:ul, ],实际效果和一些文档里描述的有点差异我自己的测试结论是对简单列表mammoth 默认能识别 Word 的numbering.xml对复杂嵌套编号最好在编辑阶段手动修复别指望自动转换一次到位。分享一个我最后用的常态化方案如果产品只要求“能看、内容完整、图片不丢”纯前端 mammoth 就够了如果要求“双栏、页边距、页码都还原”别犹豫直接后端转 PDF 再渲染前端只负责预览容器。pdfjs-dist 或者 pdf-viewer 都比较成熟。核心方向定对了后面才不会反复返工。希望这篇文章能帮你把这个需求一次想清楚少走一点我当年走过的弯路。