1. 需求边界先划清，别一上来就写代码

前端实现在线预览 Word 文件，这需求听着人畜无害，实际是个坑位密度极高的活儿。我在过去几年里至少接过四次类似的需求：合同管理后台要看签署文本、在线教育平台要看随堂讲义、招聘系统要在浏览器里翻简历、OA 报销流要预览附件。每一次甲方说出来的话都一样——"就是点一下能看内容就行"。但真正落地时会发现，"看内容"这三个字背后藏着完全不同的技术底线。

先把结论撂在前面：如果你只需要"能看"，纯前端方案三天能上线；如果你需要"和 Word 里长得一模一样"，纯前端方案永远做不到，必须走服务端转换。这个判断标准不取决于你用了 docx-preview 还是 mammoth，而取决于版式引擎的归属问题——浏览器没有 Word 的排版引擎，这是物理层面的差距，任何库都补不上。

1.1 三种业务场景，对应三套完全不同的底线

第一种是轻内容场景，比如简历、通知、简单公文。这类文档的特点是段落 + 少量图片 + 简单表格，没有分栏、没有文本框、没有复杂页眉页脚。纯前端渲染出来的效果能达到 95% 相似度，用户根本感知不到差异。这种情况我强烈建议走纯前端，因为省掉了一整条服务端转换链路，也就省掉了并发队列、文件缓存、转换失败的兜底逻辑，运维成本接近零。

第二种是强版式场景，比如合同、投标书、财务报表、带公章的 PDF 化文档。这类文档经常有合同编号在页眉、页码在页脚、签署区用表格排版、还可能有水印和文本框。纯前端渲染会把这些元素打散甚至丢掉，用户一眼就能看出"这不是原件"。这时候必须走服务端转 PDF，然后前端用 PDF 渲染库展示——因为 PDF 是固定版式，所见即所得，不需要浏览器去猜。

第三种是可编辑/可批注场景，比如审阅流程。这种就别自己造轮子了，直接对接成熟的文档协作服务，前端只负责嵌入容器和权限校验。硬做纯前端预览再做批注，等于自己实现一个富文本编辑器加协作层，投入产出比极其难看。

1.2 五套主流方案的横向对比

我把这几年实际用过或者评估过的方案整理成一张表，参数是我在真实项目里测出来的，测试环境是 Chrome 120 + 8 核 16G 的机器，文档样本是一个 3.2MB、47 页的合同文档。

这张表最关键的一列是"服务端依赖"。很多人一上来就排斥服务端方案，觉得多一个服务就多一份麻烦。但你要算另一笔账：纯前端方案的还原度缺口，最后是要用前端工程师的时间去填的。我见过一个团队为了把页眉页脚对齐到 2px 以内，前后改了两个月，最后还是放弃了。而服务端装一个转换服务，改配置只花了半天。技术选型的第一原则不是"哪个最先进"，而是"哪个的坑是我付得起的"。

顺带说一句，表格里"外部在线预览服务"这一类，我一般不建议在涉及商业数据的系统里用。文档要出域到第三方服务器，这在很多行业的合规审查里是直接一票否决的。真要用，至少得确认数据不留存、传输全程加密、且业务方书面同意。

2. docx 文件的解剖课：为什么纯前端预览这么难

想搞清楚纯前端预览为什么还原度上不去，得先知道 docx 到底是个什么东西。很多人以为 docx 是一种"文件格式"，其实它本质是一个ZIP 压缩包，把.docx后缀改成.zip解压出来，你会看到一堆 XML 和媒体文件。这个认知转变很重要，因为它意味着前端完全可以自己解析——只要你会解压和读 XML。

2.1 一个 ZIP 包里的世界

解压之后的目录结构大致是这样：

word/ document.xml # 正文内容，最重要 styles.xml # 样式定义（标题1、正文、强调…） numbering.xml # 项目符号和编号规则 settings.xml # 文档级设置 fontTable.xml # 字体声明 theme/theme1.xml # 主题色和字体主题 media/ # 所有图片资源 header1.xml # 页眉 footer1.xml # 页脚 footnotes.xml # 脚注 [Content_Types].xml # 内容类型声明 docProps/ app.xml, core.xml # 元数据

正文的document.xml里，所有内容都是嵌套的<w:p>（段落）和<w:r>（run，一段连续格式的文本）结构。举个最直观的例子，一句"合同编号：HT-2024-001"如果前半段加粗、后半段正常，那它在 XML 里会被拆成两个<w:r>，各自带自己的<w:rPr>属性块。这种粒度的结构意味着：前端解析器要做的事情，是把一棵 XML 树翻译成一棵 DOM 树，同时把每个节点的格式属性翻译成 CSS。

这个过程听起来简单，实际难点在于 OOXML 规范有几千页，Word 的排版能力远超 CSS 的表达范围。表格里的单元格合并、文字的环绕方式、段落的孤行控制、中文的避头尾规则——这些在 OOXML 里都有明确的属性定义，但 CSS 里根本没有对应概念。

2.2 单位换算：twips、EMU、half-point 与 px

这是我在做自定义解析时踩得最狠的一块。docx 内部至少用了三套长度单位，如果换算搞错，页面尺寸就会整体偏移。

拿一张标准 A4 纸举例：A4 宽 210mm，换算成 twips 是210 / 25.4 * 1440 ≈ 11906。在 96 DPI 的屏幕上，对应像素是11906 / 15 ≈ 794px。docx-preview 给页面容器设置的宽度就是这个值附近。所以如果你看到渲染出来的页面比容器窄了一截，大概率是没考虑缩放系数，而不是库有 bug。

字号也一样。Word 里正文默认五号字是 10.5pt，对应<w:sz w:val="21"/>。换算成 px 是10.5 * 1.333 ≈ 14px。如果你发现渲染出来的字比 Word 里小一号，去检查是不是把 half-point 直接当成 px 用了——这是新手最常犯的错，val="24"直接写成font-size: 24px，结果字大得离谱。

一句实操建议：所有换算统一用函数封装，别在业务代码里散落魔法数字。我一般会写一个units.ts，把twipToPx、emuToPx、halfPointToPx三个函数放一起，后面排查问题的时候能省掉大量时间。

2.3 分页、浮动对象与版式引擎的鸿沟

这里要说一个残酷现实：纯前端方案的分页是"模拟"出来的，不是"计算"出来的。

Word 保存文档时，会把上一次渲染的分页位置以<w:lastRenderedPageBreak/>的形式写进 XML。docx-preview 这类库就是靠读这个标记来切页的。问题在于：如果文档是在别的编辑器里生成的，或者用户改过内容但没重新分页保存，这个标记要么缺失、要么位置已经过时。结果就是分页线跑到奇怪的地方，或者干脆整篇不分页。

更麻烦的是文本框和浮动图片。OOXML 里用<w:drawing>配合<wp:anchor>描述浮动对象，会指定相对于段落、页面、页边距的水平和垂直位置，还有环绕方式。CSS 里能勉强用position: absolute模拟定位，但"文字环绕图片"这种效果，纯 CSS 只能做到矩形环绕，遇到不规则形状就无能为力了。

所以你看，问题不在库写得好不好，而在于浏览器压根没有一套和 Word 对等的排版模型。这是结构性差距，任何前端库都只是在做逼近，不是在做等价。

3. docx-preview 实操：从装载到渲染出第一页

选型定了纯前端之后，我的默认选择是 docx-preview。理由有三条：它直接操作 DOM 输出完整 HTML 结构（而不是像 mammoth 那样只输出语义化标签），它对页眉页脚和分页线有处理，它基于 JSZip 可以完整访问原始包结构，方便二次加工。缺点也明显：它的 API 文档比较薄，很多行为得读源码才知道。

3.1 环境准备与依赖引入

先装依赖。注意 docx-preview 内部依赖 JSZip，如果你项目里已经有 JSZip 的其他版本，要留意打包器会不会合并出问题。

npm install docx-preview jszip

最简调用长这样：

import { renderAsync } from 'docx-preview'; async function previewDocx(fileUrl, container) { // 关键点一：必须拿到 ArrayBuffer 或 Blob，不能是字符串 const response = await fetch(fileUrl, { headers: { Authorization: `Bearer ${token}` } }); if (!response.ok) throw new Error(`文件获取失败: ${response.status}`); const blob = await response.blob(); await renderAsync(blob, container, null, { className: 'docx-preview', inWrapper: true, breakPages: true, renderHeaders: true, renderFooters: true }); }

这段代码有两个地方容易出事。第一，fetch拿到的如果是跨域资源，必须服务端配合返回Access-Control-Allow-Origin，否则blob()会直接抛错，而且报错信息很难懂，经常只报一个TypeError: Failed to fetch。第二，如果是需要鉴权的接口，不要用window.open或者iframe.src直接指向文件地址，因为这两种方式带不上自定义请求头，正确做法就是上面这样先 fetch 成 Blob，再用URL.createObjectURL生成本地地址。

3.2 第二个参数不是"容器"那么简单

renderAsync(data, bodyContainer, styleContainer, options)这个签名里，第二个和第三个参数的区别是很多人的盲区。

• bodyContainer：文档正文渲染到这里，docx-preview 会在这个节点里创建.docx-wrapper和多个section.docx。
• styleContainer：生成的样式表（<style>标签）插入的位置。如果传null，样式会插到bodyContainer内部；如果传document.head，样式就变成全局的。

这个设计直接影响你的样式隔离策略。举个例子，如果页面上同时挂了两个预览组件，样式都注入到 head，后渲染的那个会覆盖前一个的字体和页面宽度设置，表现为"第二个预览一打开，第一个就变形了"。我在一个对比审阅的功能里就踩过这个坑，两个版本并排显示，右边一渲染左边就乱了。

解决办法就是给每个预览实例传独立的styleContainer，或者干脆用 Shadow DOM 彻底隔离。

// Shadow DOM 隔离方案 const host = document.getElementById('preview-host'); const shadow = host.attachShadow({ mode: 'open' }); const styleRoot = document.createElement('div'); const bodyRoot = document.createElement('div'); shadow.append(styleRoot, bodyRoot); await renderAsync(blob, bodyRoot, styleRoot, options);

注意：Shadow DOM 内部的字体不会自动继承外部样式表声明的字体，需要在 shadow 内单独引入一份@font-face，否则中文会回退到浏览器默认字体，看起来"字变了"。

3.3 配置项逐个拆解，哪些能改哪些别碰

docx-preview 的 options 有十来个，我按实用度分个类。下面这些是我实际项目里会动的：

const options = { inWrapper: true, // 包一层灰色背景容器，像 Word 的纸张预览 ignoreWidth: false, // 关掉才会按文档实际页宽渲染，开了会撑满容器 ignoreHeight: false, // 同上，控制页面高度 ignoreFonts: false, // 开了会用默认字体，中文文档会明显变丑 breakPages: true, // 按分页标记切页，必须开 ignoreLastRenderedPageBreak: false, // 开了会忽略 Word 预存的分页点，慎用 renderHeaders: true, // 页眉 renderFooters: true, // 页脚 renderFootnotes: true, // 脚注 renderEndnotes: true, // 尾注 useBase64URL: false, // 图片转不转 base64，见下面说明 trimXmlDeclaration: true, // 去掉 XML 声明，避免解析器报错 debug: false // 真出问题时打开，会打印解析日志 };

useBase64URL这个选项值得单独讲。默认情况下，docx-preview 会把word/media/里的图片通过 Blob URL 引用。这有个隐患：Blob URL 的生命周期绑在创建它的 document 上，如果预览组件被销毁或者页面跳转，Blob URL 会被回收，图片就全白了。如果预览结果要截图、要导出成 HTML、要跨窗口展示，就得开useBase64URL: true，把图片内联成 base64 字符串。代价是内存占用会明显上升——我测过一个含 20 张高清图的文档，base64 化之后内存从 8MB 涨到 34MB，长列表场景下要谨慎。

ignoreLastRenderedPageBreak这个选项名字很绕，实际作用是：开了之后，库会忽略 Word 预存的分页标记，改用其他方式判断分页。我的建议是保持默认的false，因为绝大多数从 Word 导出的文档，预存标记是准的，关掉反而更容易出错。

4. 样式与交互的硬骨头怎么啃

到这一步，文档已经能显示出来了。但你会发现，能显示和能交付之间还隔着几道墙：样式串味、目录点不动、缩放变形、手机上没法看。这一章专门处理这些。

4.1 样式隔离：三条路线的取舍

前面提过样式注入的问题，这里展开讲三种隔离策略的实际效果。

第一种是作用域类名。给预览容器加一个唯一类名，然后用后处理器把生成的样式限定在这个类名下。docx-preview 生成的 DOM 里，正文样式基本是 inline style（比如<p style="margin-left: 720px">），但页面容器和 wrapper 的样式来自它注入的<style>。你可以在 CSS 里加前缀覆盖：

.docx-preview-host .docx-wrapper { background: #f5f5f5; padding: 20px 0; } .docx-preview-host .docx-wrapper > section.docx { box-shadow: 0 2px 12px rgba(0, 0, 0, 0.12); margin-bottom: 16px; }

第二种是Shadow DOM，前面给了代码。它的优点是彻底，内部样式出不去、外部样式进不来，多实例并存毫无压力。缺点是调试麻烦、字体要单独引入、还想做全局的主题切换（比如暗色模式）需要往 shadow 里传 CSS 变量。

第三种是iframe 沙箱。这个最重，但隔离最彻底，适合预览要嵌入到不受控的第三方页面里。代价是你得在 iframe 内部再引一遍库，通信靠postMessage，复杂度和打包体积都会上去。

我的实际选择是：内部系统用第一种，需要多实例并存或者嵌入到不可控环境用第二种，几乎不用第三种。顺带提一个细节，很多团队的全局 CSS 里有* { box-sizing: border-box }或者重置了p的 margin，这些规则会污染预览效果。加上 Shadow DOM 之后这类问题一次性消失，这是我推荐它的主要理由。

4.2 目录锚点跳转：点一下就到目标章节

这个需求是热词里反复出现的——"word 文档目录如何不用点 ctrl 就到所在页"。这个问题的根源很有意思：在桌面版 Word 里，正文中的超链接需要按住 Ctrl 才能点击跳转，这是 Word 的默认交互设计。用户从 Word 迁移到网页预览时，会本能地按住 Ctrl 去点目录，结果网页上根本不需要按，反而因为按了 Ctrl 触发了浏览器的其他快捷键，体验很割裂。

网页里要做的是：把 docx 里的书签和超链接关联起来，实现点击直接滚动。

实现路径分两条，我建议先试简单的。

简单路径：渲染后自动给标题打 id。

docx-preview 渲染后，标题段落会带上类似docx-heading1、docx-heading2的类名（具体类名取决于文档里定义的样式 ID，不保证一定叫这个）。渲染完成后遍历一遍 DOM，按顺序给标题节点加 id，然后生成侧边目录。

function buildOutline(container) { const headings = container.querySelectorAll( 'p[class*="Heading"], p[class*="heading"]' ); const outline = []; headings.forEach((el, index) => { const levelMatch = el.className.match(/[Hh]eading(\d)/); const level = levelMatch ? Number(levelMatch[1]) : 1; const id = `docx-heading-${index}`; el.id = id; outline.push({ id, level, text: el.textContent.trim().slice(0, 60) }); }); return outline; } // 点击目录项时 function jumpTo(id) { const target = document.getElementById(id); if (!target) return; target.scrollIntoView({ behavior: 'smooth', block: 'start' }); target.classList.add('docx-highlight'); setTimeout(() => target.classList.remove('docx-highlight'), 1500); }

复杂路径：解析书签和内链。

如果文档自带目录页，目录项在 XML 里是<w:hyperlink w:anchor="bookmarkName">，对应的目标位置是<w:bookmarkStart w:name="bookmarkName" w:id="N"/>。docx-preview 对内部锚点的处理并不完整，很多时候渲染出来的<a>只有文字没有有效 href。稳妥做法是自己用 JSZip 解一遍document.xml，建立bookmarkName → 段落顺序的映射，再在渲染后的 DOM 上按顺序对齐。

import JSZip from 'jszip'; async function parseBookmarks(blob) { const zip = await JSZip.loadAsync(blob); const xmlText = await zip.file('word/document.xml').async('string'); const parser = new DOMParser(); const xml = parser.parseFromString(xmlText, 'application/xml'); const order = []; const bookmarks = {}; // 按文档顺序遍历所有节点，记录书签和超链接的出现次序 const nodes = xml.getElementsByTagName('*'); for (const node of nodes) { if (node.nodeName === 'w:bookmarkStart') { const name = node.getAttribute('w:name'); if (name && !name.startsWith('_')) { bookmarks[name] = order.length; } order.push({ type: 'bookmark', name }); } else if (node.nodeName === 'w:hyperlink') { const anchor = node.getAttribute('w:anchor'); if (anchor) order.push({ type: 'link', anchor }); } } return { order, bookmarks }; }

这里的关键思路是：XML 里的节点顺序和渲染后 DOM 里的元素顺序基本一致，所以可以用"第 N 个书签对应第 N 个可见锚点"的方式做映射。这个假设在绝大多数文档里成立，但如果文档里有大量被隐藏的内容（比如<w:vanish/>隐藏文字），映射就会错位。我的处理方式是：映射完成后做一次校验，如果跳转位置明显不对，就降级到"按标题文本模糊匹配"的方案兜底。

提示：给目标标题加一个短暂的高亮动画（比如背景色淡出），能极大提升"我确实跳过去了"的确定感。这个细节用户不会主动提，但加上之后反馈会明显变好。

4.3 缩放、拖拽与移动端手势

docx-preview 渲染出来的页面宽度是固定的（按 twips 换算出来的像素值），在小屏幕上会横向溢出。有人会想着去改width属性，这是错的方向——改了宽度，内部所有绝对定位的元素、表格列宽、图片尺寸全部会跟着错乱。

正确做法是外层包裹一层缩放容器，用transform: scale()整体缩放。

.docx-viewport { overflow: auto; width: 100%; } .docx-scale-layer { transform-origin: 0 0; transition: transform 0.15s ease-out; }

function applyZoom(scale) { const layer = document.querySelector('.docx-scale-layer'); layer.style.transform = `scale(${scale})`; // 关键：缩放后要把外层滚动区域的高度改掉， // 否则原本 1123px 高的页面缩放后仍占用原高度，底部会留大片空白 const inner = layer.firstElementChild; if (inner) { layer.style.height = `${inner.offsetHeight * scale}px`; } }

这段里的高度修正是我踩过两次才记住的。transform不影响布局尺寸，缩放后元素的"占位高度"还是原值，所以滚动条范围会算错，用户往下滚会发现到底部还有一大片空白，往上滚又觉得顶部被裁掉了。

移动端还要处理双指缩放。监听touchstart/touchmove，用两个触点的距离变化算出缩放比例，映射到scale上。注意要preventDefault阻止浏览器的默认页面缩放，但要小心别把纵向滚动手势也吃掉了——判断条件是"两个触点"时才接管。另外，移动端渲染长文档会非常耗内存，建议加一个开关：页数超过 30 页的文档，移动端默认只渲染前 10 页，剩下的按需加载。这个策略在教务类 App 里救过我的命。

5. 性能、大文件与工程化落地

功能跑通只是及格线，能不能扛住真实数据是另一回事。这一章讲的是从 demo 到上线的那些事。

5.1 大文件解析的耗时账

先说数据。docx-preview 的解析分三步：JSZip 解压、XML 解析、DOM 构建。我实测过几组数据：

注意最后一行的 DOM 构建花了 4.2 秒。这段时间主线程是完全阻塞的，页面上任何动画、点击、输入都会卡住。用户看到的画面是"卡死"，不是"加载中"。

这里有个很多人会犯的思路错误：想把 docx-preview 整个塞进 Web Worker。做不到，因为它的输出是真实 DOM 节点，Worker 里没有document。所以正确的优化方向不是"移走计算"，而是"拆分计算 + 让出主线程"。

我的做法是三点：

第一，把 JSZip 解压放进 Worker。解压纯粹是二进制处理，不碰 DOM，放进 Worker 完全没问题。把解压得到的各个 XML 字符串传回主线程，能省掉 20%~30% 的总耗时。

// worker.js importScripts('https://cdn.jsdelivr.net/npm/jszip@3.10.1/dist/jszip.min.js'); self.onmessage = async (e) => { const zip = await JSZip.loadAsync(e.data.buffer); const documentXml = await zip.file('word/document.xml').async('string'); const stylesXml = zip.file('word/styles.xml') ? await zip.file('word/styles.xml').async('string') : ''; self.postMessage({ documentXml, stylesXml }); };

第二，分页渐进渲染。不要一次性renderAsync整篇，而是按lastRenderedPageBreak把文档切段，每渲染一段就await new Promise(r => setTimeout(r, 0))让出一次主线程，顺便更新进度条。用户在等待过程中能看到"第 12 / 47 页"在跳动，感知等待时间会短很多。这个改造需要动到 docx-preview 内部逻辑，成本不低，但 130 页的文档从"卡死 6 秒"变成"流畅地一页页出来"，体验差距是量级的。

第三，先出骨架屏再有内容。至少先把灰色纸张背景和工具栏渲染出来，让用户看到结构，比白屏好得多。

5.2 微前端环境下的资源路径与样式冲突

现在很多后台是微前端架构，主应用 + 若干子应用。预览组件经常放在一个子应用里，然后被主应用的弹窗容器挂载。这种场景有两个必踩的坑。

第一个坑是静态资源路径。docx-preview 本身不依赖外部资源，但如果你顺手用了 Worker 或者 WebAssembly 做优化，就要注意 Worker 文件在微前端打包后的路径问题。子应用被主应用加载时，import.meta.url或者相对路径可能指向主应用的域，导致 Worker 加载 404。稳妥做法是把 Worker 用new Worker(new URL('./docx.worker.js', import.meta.url))的方式声明，让打包器处理路径，同时在构建配置里确认 Worker 会被单独产出。

第二个坑是全局样式覆盖。微前端里主应用经常有一套全局的p、table、img重置规则，命名空间隔离做得不彻底的话，会直接作用到预览出来的文档上。表现为：预览里的表格线消失、图片宽度被强制 100%、段落间距被压扁。这个问题的排查很费时间，因为你在子应用单独跑的时候完全正常。最省事的预防措施就是从一开始就用 Shadow DOM，把预览结果关进影子树里，主应用的样式就碰不到了。

另外提一句多语言。预览组件的工具栏（缩放、下载、全屏）文案要做国际化，但文档内容本身绝不能做任何替换——那是用户的原始文件，动了就是数据篡改。我见过有同事在需求评审时提"要不要把预览里的日期格式本地化一下"，被法务直接否了。

5.3 MIME 类型与文件类型识别的坑

热词里有一条"word 文件图标显示 txt 图标"，这是同一个问题域的事：浏览器的文件类型判断主要看 MIME，而 MIME 来自服务端响应头或者文件名后缀，两者经常不一致。

典型场景：后端把上传的 docx 统一以application/octet-stream返回，前端拿到 Blob 之后，blob.type是空字符串或者application/octet-stream。这时候如果代码里有if (blob.type === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')这样的判断，就会走到错误的兜底分支，表现成"文件打不开"或者"显示成纯文本"。

我的处理方式是双保险：

const DOCX_MIME = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'; function isDocx(file) { const extOk = /\.docx$/i.test(file.name); const mimeOk = [ DOCX_MIME, 'application/octet-stream', 'application/zip', '' ].includes(file.type); return extOk && mimeOk; }

还有一个更隐蔽的坑：老版本的.doc文件和.docx完全是两种格式。.doc是二进制的 OLE 复合文档，docx-preview 处理不了，传进去会直接抛解析异常，错误信息还特别模糊。所以上传组件里必须把.doc拦掉，提示用户另存为.docx再上传。这个前置校验能省掉后面 80% 的客服工单。

提示：不要用文件头魔数（magic number）去判断是不是 docx 就完事。docx 和普通 zip 的文件头都是PK\x03\x04，仅凭前四个字节区分不了。要判断得更准，得读 zip 里的[Content_Types].xml，看有没有 wordprocessingml 的声明。这是重操作，只在需要严格校验的场景做。

6. 高频报错速查与踩坑心得

这一章是我从各种线上事故和排查记录里整理出来的，建议直接收藏。

6.1 报错速查表

"打开文件时遇到错误，请尝试下列方法"这个提示是 Word 客户端侧的经典报错，出现在前端场景里通常是两种原因：一是文件传输过程中被截断，比如后端流式返回时中途断开，前端拿到的 Blob 是残缺的；二是文件带了打开密码或者受保护视图的标记。排查时先比对文件大小，服务端记录的文件大小和前端blob.size不一致的话，基本就是传输问题。

6.2 几条用血换来的经验

第一条，永远给预览加一个"下载原件"的入口。不管你的还原度做到多高，总会有用户遇到显示异常的情况。有个下载按钮，用户就能自己用 Word 打开验证，客服压力立刻减半。这个按钮的成本几乎为零，价值极高。

第二条，不要在预览组件里做内容搜索。有人会想加个 Ctrl+F 搜索框，听起来不错，实际很麻烦：文档内容是跨页的，搜索结果的定位、高亮、跳转都要自己实现，而且和浏览器原生搜索体验冲突。真要做，用window.find()这类原生 API 是最省事的，但它在不同浏览器上行为不一致。我的建议是先不做，等真有人提了再说。

第三条，服务端转换方案一定要做转换结果的缓存。同一份文档被反复预览是常态，每次都转一遍 PDF，服务端 CPU 会顶不住。用文件的 hash 做 key 缓存转换结果，命中率通常能到 70% 以上。缓存过期策略跟文档版本绑定，文档一更新就失效，别用纯时间过期。

第四条，给预览加一个"渲染失败自动降级"的逻辑。流程是：纯前端渲染 → 检测关键指标（页面数量、是否含图片、是否有可见文字）→ 指标异常时自动切到服务端转图片的方案兜底。我在一个合同系统里加了这个逻辑之后，预览相关的工单从每周十几条降到一两条。代价是要维护两套渲染路径，但换来的是"永远不会白屏"这个底线保障。

最后分享一个小技巧。如果你的场景里文档是公开的、不涉及商业机密，而且不需要鉴权，那最快的落地方案其实是用浏览器的原生能力：把服务端返回的 PDF 直接丢给<embed>或<iframe>，浏览器自带的 PDF 查看器会处理分页、缩放、搜索、打印。这条路径零依赖、零体积增加，是很多团队绕了一大圈之后才发现的捷径。前提是服务端能给你 PDF——所以你看，绕来绕去，问题的关键始终不在前端渲染那几百行代码上，而在于「版式由谁来算」这个架构层面的决定。想清楚这一点，剩下的都是工程量问题。