Vue中实现PDF、Word、Excel在线预览的完整方案解析

1. 为什么要在 Vue 里做文档预览，兼谈方案选型

做前端的人迟早会遇到这个需求：项目里有一堆 PDF、Word、Excel 文件，用户不想下载到本地再打开，而是希望直接在页面上点一下就能看。“vue 预览 pdf、word、excel”这个话题在社区里讨论度高居不下，本质原因是这三种文件格式的技术栈完全不同，没有一套代码能通吃，每一类都得单独处理。

先说结论：PDF 用 pdf.js，Word 用 docx-preview，Excel 用 SheetJS（也就是 xlsx 库），这是目前社区验证过的最主流、最可控的前端方案。如果你的项目不要求实时编辑，只要求“打开能看、样式基本不丢”，这套组合拳足够覆盖 90% 的业务场景。

那为什么不推荐把文件传到第三方平台，或者干脆让后端转 PDF 再统一预览？原因我在第三节详细展开。这里先记住一点：前端能自己解决的，尽量不把流量绕到后端，尤其文件预览这种高频操作，一次后端转换动辄几百毫秒到几秒，用户体验很难受。

这篇文章我按“每种格式独立一个章节”来讲，把你实际开发中会遇到的问题、代码怎么写、踩过什么坑，全部摊开说清楚。文章比较长，但看完你能直接照抄到项目里。

1.1 三类文件的技术本质决定了处理方向

PDF 是一种“页面即画布”的版式文档，它的内容是排版好的、锁定位置的，所以前端预览 PDF 的本质是把 PDF 的每一页渲染成图像或者矢量图形，展示到浏览器里。浏览器其实自带 PDF 显示能力（Chrome、Firefox、Edge 都有内置 PDF 查看器），但问题在于这个查看器不能定制，你不能控制工具栏、不能监听翻页事件、不能把 PDF 嵌入到自己的业务界面里，所以绝大多数 Vue 项目不会直接用浏览器原生能力，而是引入 pdf.js 来自行渲染。

Word 和 PDF 完全不同。Word 本质是一个 ZIP 压缩包，里面装着一堆 XML 文件，描述文字、段落、分页、样式、图片、表格等。这意味着浏览器原生根本没法直接渲染 Word 文件，必须解析。docx-preview 这个库做的事情就是从 ZIP 中解出 XML，再按 XML 的描述逐个绘制到 HTML 上。它还原的是内容，不是像素级排版。

Excel 又不一样。Excel 文件的核心是二维表格数据加上样式、公式、图表。前端预览 Excel 通常有两种思路：一种是把表格数据读出来，用 HTML table 重新画一个，这是 SheetJS 方案；另一种是调用 Excel 自身的渲染引擎（比如用 OnlyOffice、LibreOffice 转图片或转HTML），这个成本太高了。对绝大多数业务场景，SheetJS 把“数据不丢、列宽不错”做到位，就够用了。

2. PDF 在线预览：从原生标签到 pdf.js 的进阶路径

PDF 预览是所有文档预览里最简单、也是坑最少的，但依然有几个很关键的细节要处理，尤其是流文件接口的兼容、多页渲染性能和中文环境下的字体加载这三个问题。

2.1 浏览器原生嵌入方案的适用范围

如果你的 PDF 是静态地址（或者后端返回的是可直接访问的 URL），而且你对界面没有任何自定义要求，直接用<iframe>或<embed>就能完成预览：

<template> <iframe :src="pdfUrl" style="width: 100%; height: 100%" /> </template>

<template> <embed :src="pdfUrl" type="application/pdf" style="width: 100%; height: 800px" /> </template>

这种方式的优缺点非常清晰。优点：零依赖、不写一行逻辑。缺点：浏览器的内置查看器带你飞，工具栏、右键菜单、打印按钮全部是浏览器默认样式，你没办法控制；而且 Safari 对 embed 的显示兼容性一直不太好。最关键的问题是，很多项目的文件接口是需要带 Token 的 POST 请求或者自定义 Header 的，这种时候src根本没法直接拼 URL，原生方案直接失效。

所以原生标签只适合“内部系统 + 静态文件 + 无鉴权要求”的极简场景，稍微正规一点的项目都建议直接上 pdf.js。

2.2 pdf.js 在 Vue 工程里的标准用法

pdf.js 是 Mozilla 出品的开源 PDF 解析和渲染库，目前最新稳定版 API 相对清爽。在 Vue 项目里，我会推荐用pdfjs-dist这个 npm 包来安装。

安装：

npm install pdfjs-dist

本人实测下来最稳的版本搭配是 Vue 3 + pdfjs-dist@3.x（这里指的是使用legacy/build/pdf那条路径的 API 版本）。4.x 之后包结构调整较大，worker 导入方式和 3.x 不同，很多老文章里的写法会失效，需要注意区分版本。

基础渲染代码：

<script setup> import { onMounted, ref } from 'vue' import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf' // 关键一步：指定 worker 路径，否则会报 "Setting up fake worker" 警告 pdfjsLib.GlobalWorkerOptions.workerSrc = new URL( 'pdfjs-dist/legacy/build/pdf.worker.min.js', import.meta.url ).toString() const canvasRef = ref(null) const pageNum = ref(1) const pageTotal = ref(0) let pdfDoc = null const renderPage = async (num) => { const page = await pdfDoc.getPage(num) const viewport = page.getViewport({ scale: 1.5 }) const canvas = canvasRef.value const context = canvas.getContext('2d') canvas.width = viewport.width canvas.height = viewport.height const renderContext = { canvasContext: context, viewport } await page.render(renderContext).promise } const loadPdf = async (url) => { const loadingTask = pdfjsLib.getDocument(url) pdfDoc = await loadingTask.promise pageTotal.value = pdfDoc.numPages renderPage(1) } onMounted(() => { loadPdf('/static/sample.pdf') }) </script> <template> <div> <canvas ref="canvasRef"></canvas> <div> <button :disabled="pageNum <= 1" @click="pageNum--; renderPage(pageNum)">上一页</button> <span>{{ pageNum }} / {{ pageTotal }}</span> <button :disabled="pageNum >= pageTotal" @click="pageNum++; renderPage(pageNum)">下一页</button> </div> </div> </template>

这里有两个细节值得展开说。

第一，Worker 配置。pdf.js 的解析过程比较重，官方默认使用 Web Worker 来避免阻塞主线程。如果不配置workerSrc，它会尝试加载pdf.worker.js，但在 Vue 的打包环境下经常找不到，你会看到控制台有一条Setting up fake worker的警告，意思是它走了降级方案——用主线程模拟 Worker，这会导致页面长时间卡顿，尤其是大 PDF 文件。解决方式就是上面代码里写的，用new URL(..., import.meta.url)来确保打包时能正确产出 worker 文件路径。

第二，Canvas 的缩放比例。你可以看到我直接用了scale: 1.5，这个值是经验值。如果屏幕是普通笔记本（1x 或 1.25x 缩放），1.5 倍渲染出来的清晰度是够的。但如果你的用户群体里有一堆 4K 屏或者 Retina 屏（MacBook 用户），建议根据window.devicePixelRatio动态调整缩放：

const scale = window.devicePixelRatio > 2 ? 2 : window.devicePixelRatio || 1 const viewport = page.getViewport({ scale })

这里需要注意，如果 devicePixelRatio 是 2，但你还用 1.5，出来效果就是字发虚；设太大也不行，Canvas 的内存占用会成倍增长。

第三，字体问题。中文 PDF 文件在 pdf.js 中偶尔会出现某些字显示成方框的“豆腐块”，这是因为 PDF 里嵌入了子集字体，但 pdf.js 在解析时没找到对应的 cmap 表。绝大多数情况下不用处理，但如果你要处理的 PDF 里包含特殊字体（比如用 Illustrator 生成的设计稿 PDF），可以检查cMapUrl配置，确保加载cmaps目录：

const loadingTask = pdfjsLib.getDocument({ url, cMapUrl: `https://unpkg.com/pdfjs-dist@3.11.174/cmaps/`, cMapPacked: true })

提示：cMaps 文件可以直接从打包产物里复制到你的 public 目录，避免依赖 CDN 导致离线不可用。具体路径是 node_modules 下 pdfjs-dist 的 cmaps 文件夹。

2.3 流文件接口的兼容方案

真实项目中 PDF 文件更多时候不是静态地址，而是后端接口返回的二进制流——通常你使用axios发起请求，设置responseType: 'blob'，收到的是一份 Blob 对象。此时直接用 pdf.js 打开 Blob 有几种方式。

最推荐的做法是借助URL.createObjectURL生成临时地址：

import axios from 'axios' const getPdfBlob = async (fileId) => { const response = await axios.get(`/api/file/pdf/${fileId}`, { responseType: 'blob', headers: { Authorization: `Bearer ${localStorage.getItem('token')}` } }) return response.data // Blob } const loadPdfFromBlob = async (blob) => { const url = URL.createObjectURL(blob) const loadingTask = pdfjsLib.getDocument(url) pdfDoc = await loadingTask.promise // 渲染逻辑同上 }

使用URL.createObjectURL有一个隐藏问题，如果你一直观察浏览器内存会发现问题——生成的 object URL 在你不再需要它时必须手动revokeObjectURL释放，否则页面会持续积压内存。建议在组件卸载时统一清理：

onBeforeUnmount(() => { if (tempUrl) { URL.revokeObjectURL(tempUrl) } })

除了 Blob，pdf.js 还支持直接传Uint8Array，如果你拿到的流是 ArrayBuffer，可以直接用：

const loadingTask = pdfjsLib.getDocument({ data: new Uint8Array(arrayBuffer) })

这种方式不需要 createObjectURL，也就没有内存泄漏问题。建议优先考虑。

2.4 用 pdf.js 也是要看场景上限的

pdf.js 在主流方案里已经是体验比较好的了，但它也不是万能的。体积大、页面多的 PDF（比如一本几百页的技术手册），前端渲染到 Canvas 上会出现两个问题：一是首次加载慢，二是翻页时每一页都要重新渲染，用户能感受到明显的延迟。这种情况你需要引入懒加载和页面缓存策略——提前渲染下一页，而不是等用户点击了才开始画。我自己的经验是把当前页、上一页、下一页三页同时渲染，用户翻页时浏览器直接展示缓存好的页面，体验会顺滑很多。

3. Word 预览：docx-preview 是主力，mammoth 做备胎

在 Vue 中预览 Word，很多人第一步会想到类似 PDF 那样用 iframe 或者 Office Online 的在线查看器，这俩方案都有硬伤。

先说iframe直接打开 .docx 文件，浏览器不会渲染，它会直接触发下载（除非你装了 Office 插件或浏览器扩展）。这个方案可以直接排除。

再说微软官方提供的 Office Online Viewer（也就是view.officeapps.live.com那个地址），它的用法是把 Word 文件的公网 URL 拼到页面上，然后 iframe 指向这个地址就行。看起来完美，但它有一个致命前提：文件必须是公网可访问的地址。公司内网系统根本没有公网 IP，内部文件服务器更不可能暴露出去，所以这个方案基本只能用在外网公开文档的场景。而且微软官方对 office viewer 这个服务的使用量是有限制的，量一大就会被拒绝访问。

排除以上方案，社区认可的方案就落在docx-preview和mammoth.js两家。

3.1 docx-preview 完整实操

docx-preview 这个库很直接，输出目标可以是一个容器元素，它会把 Word 内容解析后以 HTML 的方式渲染到这个容器里。它的还原度在纯前端方案里算第一梯队，段落、标题、图片、表格都能正常显示。

安装：

npm install docx-preview

核心代码：

<script setup> import { ref, onMounted } from 'vue' import { renderAsync } from 'docx-preview' const containerRef = ref(null) const previewDocx = async (blob) => { await renderAsync(blob, containerRef.value, null, { className: 'docx-preview-container', inWrapper: true, ignoreWidth: false, ignoreHeight: false, ignoreFonts: false, breakPages: true, ignoreLastRenderedPageBreak: false, experimental: false, trimXmlDeclaration: true, useBase64URL: false, useStyle: true, debug: false }) } const fetchAndPreview = async (fileId) => { const response = await axios.get(`/api/file/word/${fileId}`, { responseType: 'blob' }) await previewDocx(response.data) } onMounted(() => { fetchAndPreview(123) }) </script> <template> <div ref="containerRef" class="docx-wrapper"></div> </template>

这里有几个配置项你需要知道它们干什么。

• breakPages: true表示是否按 Word 的分页符来分页渲染。设为 true，渲染出来的内容会保持 Word 的页码划分；设为 false，所有内容无缝拼接成一个大长文档。如果你们只要求“内容能看”，不关注页码，其实设 false 在视觉上更连贯，适合移动端连续滚动阅读的场景。
• ignoreWidth和ignoreHeight控制是否忽略源文档中设置的页面宽高。如果你发现渲染结果超出你的容器宽度，导致出现横向滚动条，建议把ignoreWidth设为 true，让内容强制适配容器宽度。
• useBase64URL决定文档里的图片用什么形式在 HTML 中展示。这个强烈建议不要开，开了后图片会以 base64 的形式内嵌，文档一长字符串会非常大，影响渲染速度和内存占用。保持默认 false，库里会自己处理成 Blob URL。

3.2 docx-preview 的样式还原能力边界

注意，docx-preview 不是一个“像素级还原”的工具，它的目标是内容级还原。Word 里的复杂版式，比如文本框里的内容、艺术字、某些复杂的页眉页脚，渲染出来可能会走样或丢失。我在实际项目中遇到过几种典型的丢样式情况：

表格边框消失：如果源文档里的表格使用了“自动格式”或“默认表格样式”，docx-preview 偶尔会出现边框不显示的问题。排查到最后发现是 CSS 里全局重置了表格样式导致的。解决方式很简单，在你的全局 CSS 里给预览容器加上一层作用域：

.docx-wrapper table { border-collapse: collapse; width: 100%; } .docx-wrapper td, .docx-wrapper th { border: 1px solid #d0d0d0; padding: 6px 8px; }

这样就算解析时丢了些样式，至少表格的结构和可读性还在。

图片无法加载：Word 文档里的图片是嵌在 ZIP 包里的，docx-preview 会先解压再转 Blob URL。如果文档本身很大的话，图片可能延迟显示，这时你给容器加一个min-height并配上 loading 占位图，能避免页面跳动。

嵌入的 Excel 对象无法显示：Word 里有嵌入的 Excel 表格对象时，docx-preview 只显示一个图标，不能预览实际内容。这个问题无解，除非你把源文档拆开处理。

3.3 .doc 老格式怎么处理

上面讲的是.docx（新版格式），如果你的项目里还有一批古董.doc文件（Office 2007 之前的二进制格式），那docx-preview读了就是乱码，因为 .doc 不是 ZIP 压缩包，而是 OLE 复合文档格式。

处理 .doc 目前前端没有好的纯 JS 方案，最实际的办法是后端做转换，把 .doc 统一转成 .docx 或 PDF 再返回给前端。后端转换工具用得很普遍的是 LibreOffice，一条命令就能完成：

libreoffice --headless --convert-to docx --outdir /output /path/to/old.doc

或者转换 PDF：

libreoffice --headless --convert-to pdf --outdir /output /path/to/old.doc

转换完走 PDF 预览链路，体验更好。

注意：不要试图在前端用 FileReader 读 .doc 的二进制自己解析，成本极高且很容易出错，纯 .doc 的 XML 没有暴露给 JS 的解析库，硬啃得不偿失。

3.4 mammoth.js 什么时候用

mammoth.js 的存在价值是“把 Word 转成干净的 HTML”，它的输出模型不追求还原分页，而是追求结构化语义。它的优点是很轻量，渲染结果可以随你的页面样式走，适合那种“我只要文本内容，不关心分页和复杂版式”的场景，比如在线帮助文档、合同信息抽取。

使用方式大致是：

import mammoth from 'mammoth/mammoth.browser' mammoth.convertToHtml({ arrayBuffer: docArrayBuffer }, { styleMap: [ "p[style-name='Title'] => h1:fresh", "p[style-name='Heading 1'] => h2:fresh" ] }) .then(result => { container.innerHTML = result.value })

老实说，我自己的项目里 docx-preview 用得更多，因为用户拿 Word 文件给你预览，潜意识是希望“看到的东西和 Office 里尽量一样”，而 mammoth 的序列化会丢掉很多版式信息。所以这里我的建议很明确：如果目标只是文字提取，用 mammoth；如果目标是给用户看，用 docx-preview。

4. Excel 预览：SheetJS 读取数据，HTML 表格渲染

Excel 预览和前面两类有本质区别。PDF 讲究的是“还原页面”，Word 讲究的是“还原排版”，而 Excel 的核心是表格数据——大家打开 Excel 文件，第一眼关注的是单元格里有什么，而不是表格长得有多漂亮。所以 Excel 预览的通用做法是：用 SheetJS 解析 .xlsx 文件，拿到单元格数据后，用 HTML<table>渲染一个简单可看的二维表出来。

4.1 SheetJS 读取 Excel 的完整流程

安装：

npm install xlsx

这里值得注意的是，npm 上的包名虽然是xlsx，但项目的正式名称是 SheetJS，作者维护多年，属于这类工具里的首选。

解析流程：

<script setup> import { ref } from 'vue' import * as XLSX from 'xlsx' const tableRef = ref(null) const previewExcel = (blob) => { const reader = new FileReader() reader.onload = (e) => { const data = new Uint8Array(e.target.result) const workbook = XLSX.read(data, { type: 'array' }) const firstSheetName = workbook.SheetNames[0] const worksheet = workbook.Sheets[firstSheetName] const html = XLSX.utils.sheet_to_html(worksheet) tableRef.value.innerHTML = html } reader.readAsArrayBuffer(blob) } const fetchAndPreview = async (fileId) => { const response = await axios.get(`/api/file/excel/${fileId}`, { responseType: 'blob' }) previewExcel(response.data) } </script> <template> <div ref="tableRef" class="excel-preview"></div> </template>

sheet_to_html是 SheetJS 提供的一个便捷方法，它会把工作表直接转换成一段 HTML 字符串，包含<table>、<tr>、<td>标签，并且原样保留单元格的合并信息、数字格式、超链接等元数据。你只需把这段 HTML 插入容器即可。

4.2 样式还原不要抱期待

我必须说清楚一点：SheetJS 不是渲染引擎，它只负责数据，不负责样式还原。你用sheet_to_html拿到的表格，默认没有 Excel 里那些背景色、字体颜色、边框粗细，除非样式信息写在单元格对象里（比如cell.s），它才会带出部分内联样式。你如果打开一个花里胡哨的 Excel，预览出来会是一个“脱了妆”的素颜表格。

所以业务上要提前对齐预期。如果领导或客户要求“和 Excel 里看起来一模一样”，纯前端方案做不到，你得考虑把 Excel 转成图片或 PDF，或者部署 OnlyOffice。

4.3 大数据量 Excel 的性能优化

Excel 的性能问题和 PDF 不一样。PDF 大文件是渲染慢，Excel 大文件是直接卡死浏览器。你用 SheetJS 读取一个 5 万行、20 列的 .xlsx，sheet_to_html会生成一个巨长的 HTML 字符串，插入 DOM 后浏览器要一次画出 5 万行tr标签，不卡才怪。

解决思路是分页或虚拟滚动。分页最简单，控制每次只渲染前 100 行：

const rows = XLSX.utils.sheet_to_json(worksheet, { header: 1 }) const pageSize = 100 const pagedRows = rows.slice(0, pageSize)

如果业务上必须滚动查看全量数据，那你不能直接渲染 HTML 表格了，需要换成虚拟滚动方案（比如配合el-table-v2或vue-virtual-scroller来做），把行数据 feed 进虚拟列表，只渲染可视区域内的行。这套方案能支撑几万行数据的流畅滚动，但实现复杂度上一个台阶。

4.4 多 Sheet 文件的 Tabs 切换

一个 Excel 工作簿通常包含多个工作表（Sheet），而workbook.SheetNames可以拿到全部工作表名。你可以把文件名循环出来，做成 Tabs 菜单，用户点击哪个 Sheet 就渲染哪个：

<template> <div> <div class="sheet-tabs"> <button v-for="(name, index) in sheetNames" :key="name" @click="switchSheet(index)" > {{ name }} </button> </div> <div ref="tableRef" class="excel-preview"></div> </div> </template>

const sheetNames = workbook.SheetNames const switchSheet = (index) => { const worksheet = workbook.Sheets[workbook.SheetNames[index]] tableRef.value.innerHTML = XLSX.utils.sheet_to_html(worksheet) }

这个功能看起来简单，但很实用。很多业务 Excel 的第一页是汇总数据，后面几个 Sheet 才是明细，如果只能看第一个 Sheet，等于白做。

4.5 xlsx 解析的版本陷阱

SheetJS 在 npm 上有一个比较曲折的版本历史。早期版本（0.18.x 及之前）是免费使用的，后面作者把 npm 上的版本更新到 0.20 之后，只能通过官网渠道安装最新的 CDN 构建版，npm install xlsx拉下来的还会停留在 0.18.5。好消息是 0.18.5 功能已经非常完整，社区里绝大多数项目也都在用它，不用刻意升级。如果你遇到一个.xls（老格式）文件解析出来是乱码，大概率是版本太老，检查一下 package.json 锁定的版本。

提示：SheetJS 的 CDN 版本功能更全，支持.xls、.xlsx、.csv、.ods等多种格式。如果 npm 版本不够用，可以直接在 index.html 里引入 CDN 脚本，然后用全局XLSX变量访问。

5. 统一预览方案与后端兜底策略

如果说前面的内容解决了“单格式预览怎么做”，那这一节解决的是“整个平台有几十种文件格式怎么办”。实际上，你项目里大概率不止 PDF、Word、Excel 这三种文件，还会有 PPT、CAD 图纸、TXT、MP4、MP3 等。如果每种格式都单独实现一个前端预览器，工作量会爆炸。所以这里需要引入“统一入口 + 分类处理”的设计思路。

5.1 前端按扩展名分发预览器

在 Vue 工程里可以做一个全局的文件预览组件，接收文件 URL 和文件类型，内部根据类型动态路由到不同的渲染组件：

<template> <div class="file-preview"> <PdfPreview v-if="type === 'pdf'" :url="url" /> <WordPreview v-else-if="type === 'word'" :url="url" /> <ExcelPreview v-else-if="type === 'excel'" :url="url" /> <ImagePreview v-else-if="imageTypes.includes(type)" :url="url" /> <VideoPreview v-else-if="videoTypes.includes(type)" :url="url" /> </div> </template>

类型判断可以从 URL 后缀或后端返回的 MIME 类型中获取。我个人的建议是不要完全相信 URL 后缀，因为有些后端下载接口不保留文件后缀，你需要在接口里额外返回一个fileType字段，或者从Content-Type里解析。传文件类型给前端的做法最可靠。

5.2 后端转换兜底：LibreOffice 和 OnlyOffice

前端方案有一个天花板：它永远无法做到“一个组件全类型兼容”。所以很多企业级系统会做一层后端兜底——将文件统一转成 PDF，前端只负责 PDF 预览。这相当于把复杂问题转化为已经解决过的问题，用工程上以空间换时间、用王者方案治百病的思路来化解。

LibreOffice是这条路的核心工具，它支持的命令行转换覆盖了 Office 家族几乎所有格式。你可以用 Java 的JODConverter或者直接命令行调用：

soffice --headless --convert-to pdf --outdir /tmp/converted /tmp/upload/xxx.docx

转换完成以后，前端拿到 PDF 地址走 pdf.js 渲染流程。这个方案最大的优势是预览效果和 Office 里几乎一致，因为 LibreOffice 的排版引擎把格式吃得很透彻。缺点也一样明显：转换本身需要耗时，一个大文件在服务器上可能要转十几秒。所以一般建议在文件上传后就异步转换，把预览地址缓存起来，而不是等用户点击预览时再转。

如果是更复杂的需求（需要在线编辑、协作、评论），那就要上 OnlyOffice 或 Office online 私有化部署那套了，它们自带完整的文档预览和编辑能力，自带用户界面，前端只需要 iframe 嵌入。但部署和维护成本都比较高，适合大型企业项目。

5.3 文件预览组件的权限控制

在真实的业务系统里，文件预览比打印、下载的权限要求往往还高。预览走的是“只读”路径，但预览接口如果暴露给用户，用户完全可以绕过你的前端直接把接口 URL 拿到手里，用 Postman 刷你的文件流。

所以我在项目里会采用两种措施：

全部走带 Token 的接口请求。文件预览不要用<iframe src="/file/123">这种裸 URL，必须通过 axios 请求把文件流拿回来，再转 Blob 渲染，这样你可以在拦截器上统一校验鉴权，后端也能通过 Token 判断用户是否有文件访问权限。

预览地址一次性有效。如果文件是外部 URL 类型，比如存储公网 OSS，那要看这个文件本身是否敏感。不敏感的文件可以直接公开地址；敏感文件应当使用带签名的临时链接，过期自动失效。

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

这一节我整理一些在开发和支持中高频出现的现象，直接以“症状—原因—解法”的方式列出，方便你排查时对照。

再补充几个我在实际业务里踩过的、文档里很少提到的小坑。

坑 1：PDF 文件接口返回的 Content-Type 是 application/octet-stream 而不是 application/pdf。这种情况 createObjectURL 之后传给 pdf.js 可能能渲染，但某些依赖 Content-Type 判断的逻辑会出错。最稳的方法是预览前把 Blob 的 type 重新设置一下：

const newBlob = new Blob([oldBlob], { type: 'application/pdf' })

坑 2：docx-preview 渲染后页面的滚动容器错位。如果你的页面外层有一个overflow: hidden的弹窗容器，渲染出来的 Word 内容高度很大，内部滚动会失效。排查半天才发现是 CSS 的overflow冲突。解决方式是给预览容器设独立的高度并使用overflow-y: auto。

坑 3：SheetJS 读取手机端上传的 .xlsx 文件时，偶尔会遇到文件损坏的报错。原因往往是手机上清理工具把文件尾部不必要的数据截断了。这种情况建议前端做一个文件完整性校验（检查文件大小是否和上传时一致），并在报错时抛出友好的提示，让用户重新上传一次。

坑 4：文本型数字丢失精度。这是 SheetJS 最经典的问题之一。Excel 单元格里存了1000000000000000001这种长数字，SheetJS 默认按数字解析，JS 的浮点精度不足以表示完整数值，解析出来会变成1000000000000000000。解决办法是在读取时强制按文本类型读取：

const rows = XLSX.utils.sheet_to_json(worksheet, { header: 1, raw: false })

raw: false会返回格式化后的字符串，数值就不丢失精度了。但代价是数字格式的单元格也变字符串了，排序会受影响。所以这个参数需要你按业务权衡来设。

7. 方案演进与代码组织建议

如果你要在一个中大型项目里落地文档预览，我不建议每个页面都各自引用 pdfjs-dist、docx-preview、xlsx，然后重复写一遍加载逻辑。更好的组织方式是在前端项目里抽象出一个FilePreview目录，把各格式的预览器拆成独立组件，对外暴露统一的 props 和 events。

一个比较理想的目录结构大概是这样的：

src/components/FilePreview/ ├── index.vue // 入口组件，按文件类型分发 ├── types.js // 类型常量定义 ├── PdfPreview.vue // pdf.js 封装 ├── WordPreview.vue // docx-preview 封装 ├── ExcelPreview.vue // SheetJS 封装 ├── ImagePreview.vue // 图片预览（可选，用 el-image-viewer） ├── VideoPreview.vue // 视频预览（用 video 标签） └── useFilePreview.js // 组合式函数，处理文件流获取、Blob 管理

这个目录负责统一接收一个{ fileId | url, type }的对象，内部自己完成鉴权请求、文件流 H5 渲染、加载态展示和错误处理。这样业务页面只需要一行代码就能调用：

<FilePreview :file-id="currentFile.id" :file-type="currentFile.type" />

我在实际项目中就是这么组织的，后面来新需求，比如增加 PPT 预览，只需要新增一个PptPreview.vue并在index.vue里加一个分支，不用动任何业务页面。维护成本一下就降下来了。

有一点要特别提醒：在做方案选型时，不要一开始就在工程里引入重量级的 OnlyOffice，也不要一上来就要求后端“文件统一转 PDF”。正确的做法是先了解你的业务里实际有哪几种文件类型、用户对这些文件预览的样式还原要求有多高，然后对照这篇文章里的方案做矩阵评估，哪种划算用哪种。

以我的经验来说，大部分内部管理系统三类文件都只需要“能看、不下载、支持缩放或翻页”，那pdfjs-dist + docx-preview + xlsx这套方案够用。如果未来业务升级到需要在线编辑协作，成本再怎么逃也逃不掉，那时候再上 OnlyOffice，反而是最省钱的方式。