1. 为什么要在 Vue 里做文档预览兼谈方案选型做前端的人迟早会遇到这个需求项目里有一堆 PDF、Word、Excel 文件用户不想下载到本地再打开而是希望直接在页面上点一下就能看。“vue 预览 pdf、word、excel”这个话题在社区里讨论度高居不下本质原因是这三种文件格式的技术栈完全不同没有一套代码能通吃每一类都得单独处理。先说结论PDF 用 pdf.jsWord 用 docx-previewExcel 用 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 :srcpdfUrl stylewidth: 100%; height: 100% / /templatetemplate embed :srcpdfUrl typeapplication/pdf stylewidth: 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-dist3.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 refcanvasRef/canvas div button :disabledpageNum 1 clickpageNum--; renderPage(pageNum)上一页/button span{{ pageNum }} / {{ pageTotal }}/span button :disabledpageNum pageTotal clickpageNum; 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-dist3.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) } })除了 Blobpdf.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 refcontainerRef classdocx-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或者转换 PDFlibreoffice --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-nameTitle] h1:fresh, p[style-nameHeading 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 文件拿到单元格数据后用 HTMLtable渲染一个简单可看的二维表出来。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 reftableRef classexcel-preview/div /templatesheet_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 列的 .xlsxsheet_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 classsheet-tabs button v-for(name, index) in sheetNames :keyname clickswitchSheet(index) {{ name }} /button /div div reftableRef classexcel-preview/div /div /templateconst 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 classfile-preview PdfPreview v-iftype pdf :urlurl / WordPreview v-else-iftype word :urlurl / ExcelPreview v-else-iftype excel :urlurl / ImagePreview v-else-ifimageTypes.includes(type) :urlurl / VideoPreview v-else-ifvideoTypes.includes(type) :urlurl / /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. 常见问题与排查技巧实录这一节我整理一些在开发和支持中高频出现的现象直接以“症状—原因—解法”的方式列出方便你排查时对照。症状原因解决办法PDF 页面渲染后文字模糊Canvas 缩放比例没有匹配 devicePixelRatio使用window.devicePixelRatio动态计算 scalePDF 渲染后中文变成方框PDF 内嵌字体的 cmap 表未加载配置cMapUrl和cMapPacked: truepdf.js 一直报 “fake worker”workerSrc 路径配置错误或版本不匹配检查 workerSrc 是否指向正确文件必要时用 import.meta.urliframe 打开 PDF 显示空白接口返回的是 Blob 而非可访问 URLsrc 无法携带请求头放弃 iframe改用 pdf.js 解析 BlobWord 渲染后表格没有边框全局 CSS 覆盖了表格默认样式在预览容器作用域内补上 table/th/td 的边框样式docx-preview 渲染大文件卡顿文件内含大量图片或超长文本先进行后端转 PDF或开启 breakPages 减少单页 DOM 量.doc 文件预览乱码老格式使用 OLE 复合文档结构无法用 docx-preview 解析后端用 LibreOffice 转 .docx 或 PDFExcel 预览时表格出现横向滚动条列宽超出容器宽度sheet_to_html后设置table { width: 100% }或限制最小宽度Excel 大数据量渲染浏览器崩溃DOM 一次性挂载数万行tr分页或引入虚拟滚动组件预览后再次打开文件速度明显变慢无缓存机制每次重新加载并解析文件使用组件级缓存或服务端缓存预览地址多个文件切换时内存持续攀升objectURL 未释放、Canvas 实例残留在 onBeforeUnmount 中 revokeObjectURL 并清除 Canvas 尺寸再补充几个我在实际业务里踩过的、文档里很少提到的小坑。坑 1PDF 文件接口返回的 Content-Type 是 application/octet-stream 而不是 application/pdf。这种情况 createObjectURL 之后传给 pdf.js 可能能渲染但某些依赖 Content-Type 判断的逻辑会出错。最稳的方法是预览前把 Blob 的 type 重新设置一下const newBlob new Blob([oldBlob], { type: application/pdf })坑 2docx-preview 渲染后页面的滚动容器错位。如果你的页面外层有一个overflow: hidden的弹窗容器渲染出来的 Word 内容高度很大内部滚动会失效。排查半天才发现是 CSS 的overflow冲突。解决方式是给预览容器设独立的高度并使用overflow-y: auto。坑 3SheetJS 读取手机端上传的 .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-idcurrentFile.id :file-typecurrentFile.type /我在实际项目中就是这么组织的后面来新需求比如增加 PPT 预览只需要新增一个PptPreview.vue并在index.vue里加一个分支不用动任何业务页面。维护成本一下就降下来了。有一点要特别提醒在做方案选型时不要一开始就在工程里引入重量级的 OnlyOffice也不要一上来就要求后端“文件统一转 PDF”。正确的做法是先了解你的业务里实际有哪几种文件类型、用户对这些文件预览的样式还原要求有多高然后对照这篇文章里的方案做矩阵评估哪种划算用哪种。以我的经验来说大部分内部管理系统三类文件都只需要“能看、不下载、支持缩放或翻页”那pdfjs-dist docx-preview xlsx这套方案够用。如果未来业务升级到需要在线编辑协作成本再怎么逃也逃不掉那时候再上 OnlyOffice反而是最省钱的方式。