Word 在线预览选型：纯前端、转 HTML 与服务端转换实战

1. 从需求到选型：Word在线预览这件事到底难在哪

做过文档类产品的同学大概都有过这样的经历：用户上传了一份 Word，产品经理一句"点一下就能看"，结果你打开需求文档才发现后面跟着一长串坑。前端实现在线预览 Word 文件，表面看只是"把 .docx 显示到页面上"，本质上却是在浏览器里重建一套排版引擎的活。Word 是微软用几十年时间打磨出来的桌面排版系统，里面有分页、页眉页脚、浮动对象、域代码、修订痕迹、嵌入字体、OLE 对象，而浏览器只认 HTML 和 CSS，两者之间的鸿沟不是一句iframe src就能填平的。

这篇文章适合三类人：一是正在做 OA、合同、教育、医疗病例这类文档系统的前端开发者，二是准备面试被问到"前端实现在线预览 Word 文件"这个高频题的同学，三是需要给团队定技术方案的技术负责人。我会把三条主流路线——纯前端渲染、转 HTML、服务端转换——各自的原理、适用边界、踩坑点讲透，代码可以直接抄，参数直接能跑。看完你至少能判断：手上的项目到底该选哪个方案，为什么不能选另一个。

先说结论，省得你读到一半着急。没有一种方案能 100% 还原 Word 的排版，所有方案都是在"还原度、性能、成本、可维护性"四个维度上做取舍。谁能想清楚自己的场景更看重哪一项，谁就能少走三个月的弯路。下面我按这个思路一层层拆开。

1.1 为什么浏览器天生"读不懂"docx

很多人以为 .docx 是个二进制文档，其实从 Office 2007 开始它就是标准 ZIP 包了。你把report.docx后缀改成.zip解压，会看到word/document.xml、word/styles.xml、word/media/、word/_rels/这一堆东西。真正的正文内容在document.xml里，是一段段<w:p>（段落）、<w:r>（文本 run）、<w:t>（实际文字）嵌套的 XML，样式则大量通过w:pStyle、w:rPr引用到styles.xml里的定义。

这带来两个直接后果。第一，解析 docx 的门槛其实不高，ZIP 解压加 XML 解析就能拿到纯文本，所以纯前端方案才成立。第二，排版信息被拆散在多个 XML 文件里，段落间距、缩进、编号、制表位、边框、底纹，全靠交叉引用拼起来，少解析一层样式，页面就"变味"。我见过最典型的翻车是：正文是好的，但标题层级全乱了，因为编号定义藏在numbering.xml里，渲染库没读它就退化成了普通段落。

再往深一层，分页是浏览器的死穴。Word 是"分页优先"的排版模型，一行放不下就换页，表格跨页要断行；浏览器是"流式"模型，内容从头往下流，高度是算出来的不是排出来的。所以你会看到纯前端方案里经常出现"该分页的地方没分，不该断的表格断了"，这不是 bug，是两种模型的先天差异。理解了这一点，后面所有的坑你都能对号入座。

1.2 三条技术路线，各自的适用边界

市面上能落地的方案，掰开揉碎就三类，我按"工作量从轻到重"排一下。

第一类是纯前端渲染，代表库有docx-preview、vue-office/docx、mammoth.js。核心思路是在浏览器里解压 docx、解析 XML、拼成 HTML 加 CSS 塞进容器。优点是零后端成本、数据不出浏览器、响应快；缺点是复杂文档还原度有限，超大文件会卡主线程。

第二类是服务端转 HTML，用mammoth的 Node 版或者自己写解析，产出一份干净的语义化 HTML 丢给前端。它比纯前端强的地方在于可以做缓存、可以做统一清洗、可以把结果存库，适合"同一份文档要被很多人反复看"的场景。

第三类是服务端转 PDF 或图片，用 LibreOffice 无头模式或者商用库把 docx 转成 PDF，前端直接用 PDF 预览器或图片查看器渲染。这是还原度最高的路线，因为 PDF 是固定版式，所见即所得。代价是需要服务端算力、转换有延迟、并发高了要排队，而且字体缺失会导致转出来的 PDF 换字体。

选型的时候我一般问自己三个问题：文档复杂吗？访问频繁吗？能上服务器吗？如果文档是用户随手传的合同、简历，格式五花八门，那就别指望纯前端完美还原，直接上转换。如果是系统自己生成的固定模板报表，模板你能控制，那纯前端方案又快又省。

1.3 一个容易被忽略的前置问题：文件从哪来

在写任何代码之前，先确认文件怎么到前端。常见的三种：一是后端返回文件流，前端fetch拿ArrayBuffer；二是后端返回一个带签名的临时 URL，前端拿到 URL 再请求；三是用户本地input[type=file]上传后直接在前端处理。

这里有个经典坑：直接拿文件 URL 塞进预览库，往往预览不出来，因为库需要的是二进制数据不是链接。正确姿势是用fetch把 URL 转成ArrayBuffer：

async function getFileBuffer(url) { const res = await fetch(url); if (!res.ok) throw new Error('文件下载失败'); return await res.arrayBuffer(); }

拿到ArrayBuffer后，docx-preview这类库就能直接吃了。跨域的话记得后端配好Access-Control-Allow-Origin，否则fetch会在控制台报一个很迷惑的 CORS 错误，很多人第一反应是库坏了，其实是跨域。这一步看着简单，但我在实际项目里至少见过五次"预览空白"的根因都在这。

2. docx-preview：纯前端渲染方案的主力选手

如果你的场景是"用户上传文档，页面里快速看一眼"，docx-preview基本是当前纯前端方案里综合体验最好的。它把 docx 解析成 DOM，样式用内联 CSS 还原，图片转成 base64 塞进页面，分页用 CSS 模拟，对接起来非常顺。这一章我把它从安装到调参到踩坑讲全。

2.1 安装、引入与最小可用示例

安装很直接：

npm install docx-preview --save

Vue、React 里都一样用。核心 API 只有一个renderAsync：

import { renderAsync } from 'docx-preview'; async function previewDocx(fileBuffer, container) { await renderAsync(fileBuffer, container, container, { className: 'docx-preview', inWrapper: true, ignoreWidth: false, ignoreHeight: false, ignoreFonts: false, breakPages: true, experimental: true, breakPagesOnParagraphStart: true, }); }

第一次跑之前，我建议你先把这几个参数的含义刻进脑子，因为它们直接决定预览效果：

• inWrapper：是否在内容外面包一层容器。开成true方便你统一控制背景、滚动，默认就是true，一般别关。
• ignoreWidth/ignoreHeight：是否忽略文档里写死的页面宽高。如果页面要自适应屏幕宽度，把ignoreWidth设成false并配合外层 CSS 缩放，不然定宽会让移动端横向滚动。
• breakPages：是否按 Word 的分页显示成一张张"纸"。这是 docx-preview 的招牌功能，开了之后视觉上会有一页一页的白纸和阴影，用户一看就懂。
• experimental：实验性渲染，会把更多复杂的排版特性打开，比如更好的表格和浮动处理。建议开，代价是个别极端文档会渲染得慢一点。

最小闭环就这些。剩下的工作全在"调"和"兜底"上。

2.2 容器样式：预览好不好看全在这几行 CSS

很多人抱怨 docx-preview 出来的东西"丑"，其实库本身把该渲染的都渲染了，只是容器背景、纸张阴影、字体这些需要你补。一个我用了很久的样式模板：

.docx-preview-wrapper { background: #f5f6f8; padding: 16px; overflow: auto; height: 100%; display: flex; flex-direction: column; align-items: center; } .docx-preview-wrapper .docx-wrapper { background: transparent; padding: 0; } .docx-preview-wrapper .docx { background: #fff; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12); margin-bottom: 16px; padding: 48px 56px; box-sizing: border-box; }

.docx这个类就是库给每一页生成的容器，你把它做成"一张白纸加阴影"，视觉上立刻从"裸 HTML"变成"文档预览"。padding要跟 Word 的页边距对齐，2.54cm 大约对应 96px（按 96dpi 算），我一般取 48 到 56px 左右的上下内边距，具体看文档。

注意：容器一定要设height并且overflow: auto，否则长文档会把整个页面撑开，用户滚不到底部的翻页控件。这是个高频翻车点。

2.3 让页面自适应屏幕：缩放计算的正确姿势

Word 文档默认宽度是 A4 的 21cm，按 96dpi 换算约 794px，加上纸张内边距，一页大概 800px 出头。手机屏幕才 375px，直接显示必然横向滚动。我的做法是用 transform 缩放，而不是改宽度：

function fitToContainer(wrapper, pageWidth = 794) { const available = wrapper.clientWidth - 32; const scale = Math.min(1, available / pageWidth); const pages = wrapper.querySelectorAll('.docx'); pages.forEach((page) => { page.style.transform = `scale(${scale})`; page.style.transformOrigin = 'top center'; page.style.marginBottom = `${16 - page.offsetHeight * (1 - scale)}px`; }); }

为什么要减掉被缩放造成的空白？因为transform不改变元素占位，缩小之后原来的高度还在，页与页之间会出现大片空隙。手动补偿marginBottom是最省事的方式。另一种思路是不缩放、让容器横向滚动，但移动端体验很差，不推荐。

实操心得：document.addEventListener('DOMContentLoaded')里直接调fitToContainer经常拿不到正确宽度，因为容器还没布局完。放到renderAsync的.then()里，再包一层requestAnimationFrame最稳。

2.4 目录跳转：应对"word文档目录如何不用点ctrl就到所在页"

这个需求非常真实。热词里那条"word文档目录如何不用点ctrl就到所在页"其实是在说：用户点目录里的章节，希望能直接跳到正文那一页，而不是像 Word 里那样按住 Ctrl 点。做预览的时候这个功能得自己实现，因为库不会帮你绑定锚点。

思路是两步。第一步，渲染完之后扫描 DOM，把 Word 里生成的标题找到，给它们打上唯一 id：

function buildToc(container) { const headings = container.querySelectorAll('h1, h2, h3'); const toc = []; headings.forEach((h, i) => { const id = `doc-heading-${i}`; h.id = id; toc.push({ id, text: h.textContent.trim(), level: h.tagName.toLowerCase() }); }); return toc; }

第二步，自己渲染一个侧边目录，点击时scrollIntoView：

function jumpTo(id) { const el = document.getElementById(id); if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' }); }

关键点在于：docx-preview 渲染出来的标题是不是h1/h2，取决于库里对styles.xml中标题样式的映射。如果你的文档标题层级没被识别成 HTML 标题标签，就得退而求其次，去扫段落文本匹配编号规则（比如以"第一章""1.1"开头的段落）。这条路会糙一点，但能兜住很多不规范文档。

3. mammoth.js 与 vue-office：两条差异化的路

docx-preview 不是唯一选择。如果你的目标是"内容准确、样式简化"，mammoth.js反而更合适；如果你追求"五分钟接完、少写代码"，vue-office系列值得一看。这一章把它们讲清楚，方便你做横向比较。

3.1 mammoth.js：把 Word 转成干净语义化 HTML

mammoth 的设计哲学和 docx-preview 完全相反。它不追求还原 Word 的视觉，而是把 Word 的语义提取出来：标题变h1、h2，加粗变strong，列表变ul、ol，表格变table。产出的 HTML 干净、可读、易被 CSS 控制。

import mammoth from 'mammoth'; async function convertToHtml(arrayBuffer) { const result = await mammoth.convertToHtml( { arrayBuffer }, { styleMap: [ "p[style-name='Title'] => h1:fresh", "p[style-name='Heading 1'] => h1:fresh", "p[style-name='Heading 2'] => h2:fresh", ], } ); return result.value; }

styleMap是它的灵魂。Word 里的样式名五花八门，中文版里可能是"标题 1"，英文版是"Heading 1"，不同用户上传的东西完全不一样。你可以在这里做映射，把各种样式名统一映射到 HTML 标签。

它最大的坑是丢样式。字号、行距、缩进、背景色基本都会丢，只剩结构。所以它适合的是"我要的是内容和排版层次，不要花里胡哨视觉"的场景，比如知识库、帮助中心、AI 训练语料预处理。如果你拿它去还原一份精美的合同，客户会打你。

提示：mammoth 还能直接提取纯文本mammoth.extractRawText({ arrayBuffer })，做全文检索和关键词匹配特别顺手，比转 HTML 再扒文本干净。

3.2 vue-office：Vue 项目里的"开箱即用"

Vue 技术栈的同学可以考虑vue-office，它把 docx、pdf、xlsx 的预览整合成统一组件，配一次就通吃三种格式，很适合管理系统这种"一个预览弹窗要兼容多格式"的场景。

npm install @vue-office/docx vue-demi

<template> <vue-office-docx :src="fileBuffer" @rendered="onRendered" /> </template> <script setup> import VueOfficeDocx from '@vue-office/docx'; import '@vue-office/docx/lib/index.css'; import { ref, onMounted } from 'vue'; const fileBuffer = ref(null); onMounted(async () => { const res = await fetch('/api/doc/123'); fileBuffer.value = await res.arrayBuffer(); }); function onRendered() { console.log('渲染完成'); } </script>

它的底层其实也是同类解析思路，胜在封装好、支持src直接传 URL 或二进制、支持事件回调。注意 vue-office 对 Vue2 和 Vue3 的兼容是通过vue-demi做的，热词里有人问"vue2 txt 在线预览"，其实 vue-office 就能覆盖 txt 之外的主流办公格式，Vue2 项目也接得上，前提是安装时选对版本。

3.3 三者到底怎么选

把三个库放在一起，我给一张很直白的对照表：

我的实际建议是：管理系统、后台、快速交付，先上 vue-office 或 docx-preview；做知识库、搜索、内容加工，用 mammoth.js。不要一个项目里三个都塞，维护成本会爆炸。

4. 什么时候必须走服务端：转换方案与前后端配合

纯前端再有本事，也有够不到的地方。遇到超大文件、复杂表格、严格合同排版，或者要求"可以选中、可以打印、可以导出"的高保真场景，就得让后端上。这一章讲服务端转换怎么落地，以及前端怎么配合。

4.1 判断是否需要服务端的三个信号

我一般看三个信号，出现任意一个就考虑转服务端：

第一，文档体积大。超过 5MB 的 docx，纯前端解析经常让主线程卡死几秒甚至十几秒，用户以为页面崩了。第二，格式复杂。带大量浮动图片、文本框、分栏、页眉页脚的文档，纯前端渲染几乎是灾难。第三，访问频次高。同一份文件被几百人反复打开，每次都在浏览器里重算一遍是纯浪费，转一次缓存起来才是正解。

服务端方案里最主流的是LibreOffice 无头模式，一条命令把 docx 转 PDF：

soffice --headless --convert-to pdf --outdir /data/out /data/in/report.docx

然后前端用任意 PDF 预览组件渲染这份 PDF 就行，比如 pdf.js 或者 vue-office 的 pdf 版本。这条路还原度是三类里最高的，因为它借用的就是真正的排版引擎。

注意：LibreOffice 转换需要服务器装对应字体，否则中文可能变成一堆方块。部署时记得把常用中文字体（思源、仿宋、黑体等）装进系统字体目录，并执行一次fc-cache -fv刷新缓存。这个坑我见一次记一次。

4.2 缓存策略：别让同一个人等两次

转换是有成本的，第一版上线时很多人忘了加缓存，结果每刷新一次页面就转换一次，服务器直接冒烟。正确的做法是用文件指纹做 key：

function buildCacheKey(fileId, fileHash) { return `docx:preview:${fileId}:${fileHash}`; }

文件内容不变，fileHash就不变，转换结果可以缓存在对象存储或本地磁盘，第二次直接返回。文件被重新上传导致哈希变化时，缓存自动失效。对于加急场景，还可以做"先返回进度、后台异步转、转完通知前端"的异步模式，前端显示"正在生成预览，请稍候"，转完再加载，体验比死等好得多。

4.3 鉴权与临时链接

服务端转换方案里，前端拿到的通常是转换结果的 URL。这里有个安全问题：别把对象存储的地址直接裸奔给前端，否则别人改一下文件名就能下载别人公司的合同。标准做法是后端签发一个带过期时间的临时签名 URL：

async function loadPreview(fileId) { const { url } = await fetch(`/api/preview/token?fileId=${fileId}`).then((r) => r.json()); const pdf = await fetch(url).then((r) => r.arrayBuffer()); return pdf; }

签名 URL 的有效期我一般设 10 到 30 分钟，足够一次预览。前端拿到 URL 后没必要再存起来，用完即弃最安全。另外要注意，预览接口要做权限校验，确认当前登录用户有权看这份文件，别只管签链接不管身份。

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

这一章是精华，全是我在项目里真金白银踩出来的。建议收藏，遇到问题直接对号入座。

5.1 样式丢失、字体错乱，先从这几处查

最常见的问题是"渲染出来和 Word 里不一样"。排查顺序我固定成四步：一看是不是字体缺失，二看是不是样式映射没配，三看是不是容器 CSS 覆盖了库的内联样式，四看是不是文档本身用了特殊特性。

字体问题占了一大半。浏览器里没有 Word 用的那款字体，就会退化到默认字体，行高、字宽全变，页面自然"变味"。解决办法是显式指定一套 Web 字体兜底：

.docx { font-family: "Microsoft YaHei", "PingFang SC", "Source Han Sans SC", sans-serif; }

样式映射没配是第二大类，尤其 mammoth.js。Word 中文版的样式名可能是"标题 1"带空格，也可能不带，你只配了英文名就全丢。排查技巧是把用户的样式中断打印出来看一眼，mammoth 提供了transformDocument钩子，可以打印出所有样式名。

注意：容器 CSS 里如果写了* { line-height: 1.5 }这种全局样式，会把库内联在元素上的行高覆盖掉，导致段落忽高忽低。预览容器里的样式尽量加作用域前缀，别用全局选择器。

5.2 图片显示不出来、表格错位怎么处理

图片裂开一般有三种原因。一是图片是外链引用（Word 里插入的是网络图片），浏览器加载被跨域或防盗链拦了；二是图片在word/media里但没被解析成 base64；三是图片本身是 EMF、WMF 这类浏览器不支持的矢量格式。第一、三种情况前端基本没辙，只能走服务端转换。第二种是库的问题，升级版本或者换库。

表格错位绝大多数是合并单元格 + 定宽惹的祸。Word 里表格列宽经常写死成厘米，浏览器里按像素还原时会有取整误差，几行下来就错位了。缓解办法是在容器里给表格加table-layout: fixed和word-break: break-all，让列宽按比例分配而不是按像素。

.docx table { table-layout: fixed; width: 100% !important; border-collapse: collapse; } .docx table td { word-break: break-all; }

这会让表格在视觉上稍微偏离原版，但至少不会撑破页面。这是个取舍，我的原则是宁可整体比例对一点，也不要横向滚动条。

5.3 性能问题：主线程卡死与内存泄漏

大文档渲染卡顿是纯前端方案的宿命。renderAsync虽然叫 async，但解析和 DOM 操作仍然占用主线程，几十页的文档能把页面冻住好几秒。可行的优化有这么几层：

第一层，把解析放到 Web Worker 里。docx-preview 本身主线程操作 DOM，不好完全搬进 Worker，但你可以把"下载 + 解压 + 解析 XML"这部分预处理放进 Worker，主线程只负责最后渲染。

第二层，分页懒渲染。先只渲染前 5 页，用户滚动到底部再渲染下一批，能显著降低首屏时间。

第三层，及时清理。切换文档前一定要把旧容器的内容清空，container.innerHTML = ''，否则 N 次切换之后 DOM 节点堆积，内存飙上去页面越来越卡。

实操心得：我在一个合同系统里就是把"每次切文档先清空容器"这一条加上之后，连续预览二十份文件的卡顿问题直接消失了。内存泄漏类的 bug，九成都是忘了清旧内容。

5.4 问题速查表

我把高频问题整理成一张表，遇到情况直接查：

6. 生产环境里还得注意的几件工程化的事

技术跑通了只是入门，能上生产才算数。这一章讲几个上线后才暴露出来的问题，都是血泪。

6.1 安全与合规：预览器不是浏览器

预览本质上是把用户上传的内容渲染进你的页面，这里有个高风险点：如果渲染出来的 HTML 里包含脚本，等于给别人开了 XSS 后门。docx-preview 这类库一般会做转义，但你不能指望它兜住所有情况。

我的做法是在渲染前后各做一层保险。渲染完先用container.querySelectorAll('script')扫一遍移除，再对外部链接加rel="noopener noreferrer"，最后如果条件允许，给预览区域套一层iframe做沙箱隔离。多一层隔离，就少一类事故。

另外，渲染出来的内容属于用户数据，别拿去做任何超出预览用途的事。该加密存储加密存储，该脱敏脱敏，合规这根弦始终得绷着。

6.2 移动端与微前端的适配细节

移动端最核心的问题就是宽度，前面讲的fitToContainer缩放方案必须用上。此外要注意触屏滚动和缩放手势的冲突，容器上别加touch-action: pan-x pan-y之外的拦截，否则用户两指缩放会把整个页面搞乱。

如果项目用了微前端（比如 qiankun），有个隐蔽的坑：主应用和子应用的样式会互相污染。docx-preview 会给页面注入一些全局样式类，子应用退出时没清理干净，回到主应用可能发现某个地方样式变了。解决办法是给预览容器加一个高优先级的作用域前缀，所有相关样式都挂在它下面，退出时整体移除。

6.3 做多格式预览时的统一抽象

真实项目里很少只预览 Word，往往还要看 PDF、Excel、图片，甚至热词里提到的 glb 三维模型。与其每来一种格式接一套代码，不如做一层统一抽象：定义FilePreviewer接口，每种格式一个实现，用一个工厂函数按类型分发。

const previewers = { docx: renderDocxPreview, pdf: renderPdfPreview, xlsx: renderXlsxPreview, image: renderImagePreview, }; async function preview(file, container) { const type = file.name.split('.').pop().toLowerCase(); const renderer = previewers[type] || renderUnsupported; container.innerHTML = ''; await renderer(file, container); }

这样新增格式只用加一个 key，界面和逻辑都不用大改。我在一个工程管理平台里就是靠这套抽象，从最初只支持 PDF 扩展到支持 Word、Excel、图片、CAD，前后只动了分发层，其他业务代码一行没改。

至于预览之外还能做什么延展，我最常加的三个功能是：全文检索（用 mammoth 抽纯文本建索引）、划词批注（在预览 DOM 上叠一层浮层）、导出图片（用 canvas 截当前页）。这三个都属于"预览做好了顺手就能加"的能力，价值却比预览本身高不少。

最后分享一个我个人的体会：做文档预览这行，最值钱的不是会调某个库，而是知道每个库的天花板在哪。你越早接受"没有完美的还原"，就越能把精力放在用户真正在意的地方——能不能快速看到、能不能看清关键内容、能不能顺畅翻页。剩下那 5% 的排版差异，绝大多数用户其实根本不关心。踩过几次大坑之后我现在接这类需求，第一句话都是先跟产品对齐"还原度到什么程度算验收通过"，这句话能帮你省掉后面无数扯皮。