最近被安排了一个听上去很标准的预览需求在 vue3 vite 项目里在线预览 docx、pdf、pptx文件可能来自外网也可能来自纯内网环境而且用户会在手机上打开。等真正动手做才发现这个需求就像一棵挂满装饰品的圣诞树每个灯泡都有踩碎的可能。PDF 有 pdf.js 这种成熟方案docx 也有相对靠谱的开源渲染库唯独 pptx前端圈几乎没有一个能打的纯本地方案再加上内外网这个变量直接把很多网上抄来的代码判了死刑。这篇文章把我从选型到落地、从桌面端到移动端的完整过程写出来包括三类文件各自的最优预览链路、内外网差异下的工程化处理、以及移动端的手势和适配细节。如果你也要接一个这样的文档预览模块这篇文章能帮你少走至少一周的弯路。1. 三类文件预览难度完全不同先认清对手再选型1.1 PDF 是渲染型文档pdf.js 几乎是不二之选PDF 的页面是固定版式每个字符、图片、线条在输出时位置已经钉死所以浏览器才可能直接显示。但不要图省事用 iframe 或 embed 直接塞一个 PDF URL桌面 Chrome 里看着还行换到 Safari、iOS WebView、安卓内置浏览器表现差别非常大有的直接白屏有的只显示第一页而且手机上没有翻页工具栏用户只能干瞪眼。pdf.js 是 Mozilla 官方维护的渲染库能在浏览器 Canvas 里把每一页画出来翻页、缩放、旋转都自己控制彻底摆脱浏览器内核差异。另一个关键点是内网场景pdf.js 可以完整打包到本地不依赖外网 CDN这对离线环境的稳定性是决定性的。所以 PDF 这条链路从第一天起就没犹豫过。1.2 DOCX 本质是个 zip 包得解析成可渲染内容DOCX 后缀看着像文档实际上是一个 zip 压缩包里面装的是 OpenXML 文本浏览器根本不认识。想让 Word 文档在网页里显示要么把 XML 解析成 HTML 放进去要么走在线转换服务。解析成 HTML 这条路可行但选库要谨慎。mammoth 很轻量但对复杂样式还原度低表格、批注、复杂版式经常丢docx-preview 直接在浏览器里执行渲染还原度高很多代价是包体积大、渲染出来的 DOM/canvas 节点多。先给结论做真正的文件预览选 docx-preview如果只是提取正文内容给 AI 处理或者做搜索索引再考虑 mammoth。1.3 PPTX 才是真正的硬骨头纯前端方案基本不现实很多人以为 PPTX 和 DOCX 一样找个库解析 XML 就能渲染。实际操作过就会发现完全不是一回事。PPTX 内部是绝对定位的画布模型每个形状、图片、文本框都带坐标和尺寸动画、渐变、SmartArt、母版字体、图表各种效果叠加纯 JS 解析的工程量不亚于做一个简化版 PowerPoint 渲染引擎。目前开源的 pptxjs、pptx2html 等项目要么停更多年要么还原度差到没法交付。工程上的出路只有两条外网环境用微软或谷歌的在线预览服务把文件公网 URL 拼到 iframe 里内网环境部署 LibreOffice把 PPTX 转成 PDF 再走 pdf.js 链路。这个转换替代渲染的思路是 PPTX 预览唯一靠谱的落地姿势。1.4 内外网环境决定方案上限动手前必须问清楚同样是预览外网和内网的可用资源完全不同。外网可以引 CDN、可以调在线转换 API内网可能连公网 DNS 都不通所有渲染依赖都得本地化第三方在线服务更是想都别想。我见过有人在内网项目里套网上的 CDN 方案部署上线后预览按钮全部白屏就是因为 pdf.js 和 docx-preview 的资源全在公网 CDN 上。所以选型之前一定要把部署环境问清楚。我的原则是能本地打包的库就本地打包别赌浏览器和服务器一定能访问外网必须依赖第三方服务的功能比如 PPTX 在线预览单独留一个开关内外网构建时切换。2. 环境准备把 vue3 vite 的底座搭对2.1 为什么这里选 Vite 而不是 Webpackvue3 项目初始化我直接用的 Vite。对文件预览这个场景Vite 有两个 Webpack 很难替代的优势一是开发服务器快改代码秒级热更新二是内置对?worker、?url这类静态资源参数的原生支持pdf.js 的 Web Worker 在 Vite 里配置起来非常干净。如果用 Webpackworker 和静态资源处理还要额外装 loader 配 rule绕一大圈。pnpm create vite my-preview-app --template vue-ts2.2 依赖安装与版本注意点pnpm add pdfjs-dist pnpm add docx-preview jszip pnpm add -D postcss-px-to-viewportpdfjs-dist 建议锁定大版本因为它的 API 在 v3 和 v4 之间存在细微差异Worker 初始化方式也不同网上很多教程混用版本导致各种诡异报错。docx-preview 依赖 jszip安装时一起装上防止某些包管理器没有自动解析依赖后续在运行时才暴露 Cannot find module 这种问题。postcss-px-to-viewport 是给移动端适配用的第6章会详细讲它的适用边界。2.3 组件与目录规划预览模块我拆成六个部分src/ views/Preview/index.vue # 预览页面入口 components/PreviewRouter.vue # 按后缀名分发组件 components/PdfPreview.vue # PDF 浏览器 components/DocxPreview.vue # Word 文档渲染 components/PptxPreview.vue # PPT 预览外网 iframe / 内网转换 utils/file.ts # 文件类型判断、blob 获取这样拆是为了让 PreviewRouter 只做一件事判断文件后缀返回对应组件。以后要再加 xlsx、txt 的预览不用改入口页面扩展成本非常低。每个预览组件各自独立是因为三个文件类型的生命周期完全不同PDF 和 PPTX 转出来的 PDF 需要管理 canvas 渲染docx 需要处理 DOCX 解析和样式容器混在一个组件里会把状态搞得非常乱。2.4 环境变量文件先行因为后面要做内外网切换项目初始化时就把环境变量文件建好.env.external .env.internal两个文件里放VITE_PREVIEW_MODEexternal|internal、VITE_API_BASE这类变量程序里统一用import.meta.env.VITE_xxx读取。这个习惯越早建立后面第7章做构建分流越省事。很多团队项目都上线了还没有环境变量文件临时要加一个内网包结果只能改代码再部署一次非常被动。3. PDF 预览落地worker 配置是最容易翻车的一环3.1 最简渲染链路从 blob 到画布pdf.js 的核心链路非常清晰拿文件数据传给getDocument得到 PDFDocumentProxy 对象然后按页调用getPage和render。为了保证跨域和内网可用我建议前端先 fetch 文件转成 ArrayBuffer 再传给 pdf.js而不是直接把 URL 丢给它内部加载因为内网文件服务跨域配置可能不全直接依赖 pdf.js 内部加载会在 CORS 上踩更多坑。import * as pdfjsLib from pdfjs-dist const loadingTask pdfjsLib.getDocument({ data: arrayBuffer }) const pdfDoc await loadingTask.promise单页渲染async function renderPage(pdfDoc: PDFDocumentProxy, pageNum: number, scale: number) { const page await pdfDoc.getPage(pageNum) const viewport page.getViewport({ scale }) const canvas canvasRef.value! canvas.width viewport.width canvas.height viewport.height const ctx canvas.getContext(2d)! await page.render({ canvasContext: ctx, viewport }).promise }3.2 Vite 里 Worker 配置的几种正确姿势pdf.js 渲染依赖 Web Worker否则大 PDF 的页面缩放、翻页会明显卡顿。Worker 在 Vite 里怎么配置是新手最容易翻车的地方。我试下来有两种可靠写法完全等价按团队习惯选一种即可。第一种是用?worker后缀让 Vite 把 Worker 文件单独打包并返回一个构造函数import PdfWorker from pdfjs-dist/build/pdf.worker.min.js?worker pdfjsLib.GlobalWorkerOptions.workerPort new PdfWorker()第二种是用?url拿到打包后的文件地址再赋给workerSrcimport workerUrl from pdfjs-dist/build/pdf.worker.min.js?url pdfjsLib.GlobalWorkerOptions.workerSrc workerUrl两种写法不要混用也不要直接import pdfjs-dist/build/pdf.worker.min.js那会试图在主线程执行 worker 文件必然报Invalid or unexpected token之类的语法错误。网上很多 pdf.js 引入报错帖十有八九是这一步出了问题。外网场景下为了让首屏更轻可以把 worker 指向公网 CDNpdfjsLib.GlobalWorkerOptions.workerSrc https://cdn.jsdelivr.net/npm/pdfjs-dist3.11.174/build/pdf.worker.min.js内网场景就用?url让它打进本地静态资源。这也是内外网差异在第一个技术点上的具体体现后面第7章会用构建模式把这两种场景做成自动化分流。3.3 翻页、缩放、旋转的状态管理预览器本质上是一个当前页码 缩放比例的状态机。我在 PdfPreview.vue 里维护pageNum和scale每次变化重新调用 renderPage。渲染前要先清理 canvas渲染调用链上要拿到 Promise 并 await避免连续快速翻页时上一次异步渲染覆盖掉下一次结果。页码边界用pdfDoc.numPages兜住防止越界。缩放实现推荐调整scale后重新渲染 canvas而不是用 CSS transform 直接放大。CSS 放大 canvas 会把文字弄得模糊而 pdf.js 重新渲染一次实际像素清晰度完全不一样。可以加一层节流scale 变化时 200ms 内只触发一次重绘移动端低性能设备上的体验会明显更顺滑。3.4 大文件与内存冷启动慢比白屏好PDF 越大getDocument 阶段越慢扫描版文件经常几十上百 MB。我的处理策略是先展示 loading 状态显示文件大小和加载进度超过 20 秒给出文件过大建议下载后查看的提示而不是让页面一直转圈。另外页面销毁时一定要执行pdfDoc.destroy()否则 Web Worker 和 canvas 的 GPU 内存不会立刻释放。用户在预览列表里连续打开几个大 PDF浏览器内存会肉眼可见地涨移动端这里尤其敏感。这个习惯属于典型的不报错但不做就出事的细节建议写进团队的代码规范。4. DOCX 预览落地docx-preview 是还原度最优解4.1 为什么放弃 mammothmammoth 的定位是把 Word 转成干净的 HTML内部做的是有损转换正文文字基本能出来但复杂的表格宽度、合并单元格、页眉页脚、批注、修订痕迹经常丢或者错位。如果需求只是给后台运营看内容概要也许够用但做正式文件预览用户拿 Word 原文件和页面一对比发现差异就会来反馈。docx-preview 是直接把 OpenXML 解析成页面结构用 canvas 把看到的 Word 页面画出来段落、表格、图片、页码的还原度都明显高一个档次。代价是包体积大、DOM 节点多但文件预览正确性优先这个代价值得。4.2 接入代码与容器要求import { renderAsync } from docx-preview const res await fetch(url) const blob await res.blob() const container docxContainerRef.value! await renderAsync(blob, container, container, { className: docx-preview, inWrapper: true, ignoreWidth: false, ignoreHeight: false, })renderAsync 的第三个参数是样式作用容器通常直接传同一个 container。如果你用 axios 获取文件记得设置responseType: blob否则文件会被解析成 JSON 字符串渲染直接失败。容器的高度建议设成自适应内部内容而不是写死 100%外层再用 overflow: auto 提供滚动这样文档多长都能浏览。4.3 图片、字体、表格的还原经验docx 里内嵌的图片会随 blob 一并解析基本不用额外处理。真正的坑在字体docx 指定了宋体、微软雅黑这类字体如果预览端操作系统没有安装浏览器会回退到默认字体排版肉眼可见地变松。内网系统尤其常见因为很多服务器/瘦客户机没装全量中文字体。遇到后可以用font-face引入一套常用中文字体但字体文件体积很大要根据实际文档使用情况决定是否全面引入。表格是另一个重灾区。docx-preview 的ignoreWidth和ignoreHeight配置默认 false意思是严格按文档宽度渲染。我建议保持 false因为 true 虽然能适配窄屏手机但会把表格挤得很难看后台系统桌面端体验会打折扣。移动端给表格外层容器加overflow-x: auto保底。4.4 超长文档的性能问题一份 100 页以上的 Word渲染出来的节点数量非常可观手机上低端机可能直接卡到 10fps 以下。我实测过50 页普通文档在 iPhone 上滚动尚可100 页带大量表格的文档就明显掉帧。折中方案是分页渲染用分页参数或者自己按高度懒加载后续页面但实现成本不低。如果业务场景确实频繁预览超长文档我建议后端额外做一道 PDF 转换方案和第5章 PPTX 内网方案一样用 LibreOffice前端走 PDF 预览性能比纯 DOM 渲染稳定得多。技术方案没有银弹文档类型和体量分布决定了你要在纯前端优化上花多大力气。5. PPTX 预览落地外网走在线服务内网只能转 PDF5.1 PPTX 内部结构决定了渲染不可行PPTX 和 DOCX 一样是 zip 加 OpenXML但结构完全不同。DOCX 是流式文档段落从上到下排列解析成可滚动页面相对可行PPTX 是画布模型每张 slide 里是几十个绝对定位的形状节点每个形状有 x、y、cx、cy 坐标真正的视觉效果还依赖母版、主题、字体替换、渐变、动画。纯前端还原等于要重做一个 PowerPoint 渲染引擎。这也是为什么 PPTX 的预览方案在行业里基本没有纯开源答案。我见过一些团队自己做简易渲染最后只能显示文字和图片稍微复杂点的模板就乱了交付给业务方验收根本过不了。所以正确思路是不要试图渲染 PPTX把它转换成 PDF或者用现成在线引擎解析然后复用成熟的 PDF/iframe 链路。5.2 外网方案微软和谷歌的在线预览 iframe如果文件服务部署在外网文件有公网可访问的 URL最简单的是用它拼接在线预览服务template iframe :srcofficeViewerSrc stylewidth: 100%; height: 100%; border: 0 / /template script setup langts import { computed } from vue const props defineProps{ fileUrl: string }() const officeViewerSrc computed(() { return https://view.officeapps.live.com/op/view.aspx?src${encodeURIComponent(props.fileUrl)} }) /script谷歌的链接格式类似https://docs.google.com/gview?url${encodeURIComponent(fileUrl)}这个方案的好处是零依赖、还原度极高因为背后是微软或谷歌的官方渲染引擎坏处也很明显文件必须能公网访问第三方服务的可用性不受你控制不同网络环境下访问这两个服务的稳定性需要实测不能想当然。如果只是内网系统这个方案直接不成立。5.3 内网方案LibreOffice headless 转 PDF内网想要还原度高的 PPTX 预览最可靠的是在后端部署 LibreOffice把 PPTX 转成 PDF前端复用第3章的 PDF 预览链路。后端核心就是一条命令soffice --headless --convert-to pdf --outdir /data/convert/ input.pptx在 Node 服务里用 child_process 封装一层import { execFile } from node:child_process async function convertPptxToPdf(inputPath: string, outputDir: string) { return new Promise((resolve, reject) { execFile( soffice, [--headless, --convert-to, pdf, --outdir, outputDir, inputPath], (err, stdout) (err ? reject(err) : resolve(stdout)), ) }) }这里有几个服务器运维经验要分享soffice 进程对并发处理支持很差两个转换任务同时来会互相阻塞甚至报错后端要做一个简单的任务队列首次冷启动很慢可能要 3 到 5 秒加载组件库后续转换会快一些转换过程内存占用高容器内存别给太少建议 2GB 起步否则批量转换时进程可能被 OOM kill 掉。5.4 前端按模式分流PptxPreview 组件内部不直接决定用哪个方案而是读环境变量const isExternal import.meta.env.VITE_PREVIEW_MODE external const officeViewerSrc computed(() { if (isExternal) { return https://view.officeapps.live.com/op/view.aspx?src${encodeURIComponent(props.fileUrl)} } return }) async function loadInternalPreview() { const res await fetch(/api/preview/convert?url${encodeURIComponent(props.fileUrl)}) const blob await res.blob() // 把 blob 交给 PdfPreview 组件的 source }外网用户打开是 iframe 在线预览内网用户打开是转好的 PDF体验链路统一但底层完全不同。这也是整个内外网方案里最关键的分岔逻辑。外网如果不想用第三方服务也可以用 LibreOffice 转换方案只是需要多部署一个转换服务。6. 移动端适配布局、手势与 canvas 的联动改造6.1 移动端三大痛点移动端预览的坑集中在这三块第一桌面网页塞进手机视口缩得跟邮票一样大字小得点不到第二触摸交互和鼠标不一样单指滑动、双指缩放、工具栏点击都要自己处理第三内存和 GPU 比桌面机弱大 PDF 和大 DOCX 分分钟白屏或卡死。如果直接把桌面版预览组件塞到手机用户会得出一个结论别用手机看。但业务方既然提了移动端适配就说明这个场景躲不掉只能从布局、手势、内存三个方向逐个解决。6.2 视口和布局100dvh 是个容易被忽略的细节预览页最外层容器用height: 100dvh而不是 100vh区别在于移动端浏览器地址栏和底部手势条会动态改变可视高度100vh 在 iPhone 上底部会被手势条遮住。dvh 是动态视口单位会跟着浏览器 UI 伸缩底部工具栏就不会被手势条挡住。工具栏固定顶部翻页按钮区固定底部中间留一个可以滑动的预览区。所有可点击控件的触摸区域要大于 44px这是苹果 HIG 和安卓 Material 设计规范里的建议值。我后来把手动设置的按钮改成了 min-width 和 min-height 兜底点按误触率明显下降。6.3 给 PDF/PPT 加手势单指翻页、双指缩放PDF 预览器在移动端需要的交互和桌面端完全不一样。桌面端是滚动加滚轮缩放移动端最自然的操作是单指左右滑动切页双指缩放调整页面大小。实现逻辑不算复杂touchstart 记录起始坐标和初始缩放值touchmove 里判断两点距离变化得出缩放比例touchend 时如果只是小位移单击则忽略位移超过阈值就翻页。基础代码如下let startX 0 let startDistance 0 let startScale 1 function onTouchStart(e: TouchEvent) { if (e.touches.length 1) { startX e.touches[0].clientX } else if (e.touches.length 2) { startDistance Math.hypot( e.touches[0].clientX - e.touches[1].clientX, e.touches[0].clientY - e.touches[1].clientY, ) startScale scale.value } } function onTouchMove(e: TouchEvent) { if (e.touches.length 2) { const d Math.hypot( e.touches[0].clientX - e.touches[1].clientX, e.touches[0].clientY - e.touches[1].clientY, ) scale.value Math.min(4, Math.max(0.5, startScale * (d / startDistance))) } }实现后要在容器 CSS 上写touch-action: pan-y pinch-zoom避免浏览器默认行为抢走手势。注意canvas 的缩放要重新用 pdf.js 渲染不能只靠 CSS transform否则文字会糊这点在第3章说过移动端更明显因为手机屏幕 PPI 高位图被放大一点点都能看出来。6.4 postcss-px-to-viewport 的适用边界借助 postcss-px-to-viewport 可以把设计稿的 px 自动转 vw让整个后台管理系统的移动端样式整体等比缩放这是很多团队做移动端适配的惯用手段。完整配置如下// postcss.config.cjs module.exports { plugins: { postcss-px-to-viewport: { viewportWidth: 390, unitPrecision: 5, viewportUnit: vw, fontViewportUnit: vw, minPixelValue: 1, exclude: [/node_modules/], }, }, }这里要泼一盆冷水postcss 只能处理写进 CSS 的 pxcanvas 里的页面尺寸是 JS 控制的postcss 管不到。用 pdf.js 渲染时如果宿主页面用 vw 缩放了canvas 还是按像素尺寸画两边就会出现不一致。处理方法是给 PDF 预览容器单独设定max-width: 100%canvas 只根据实际容器像素宽度计算缩放比例不要把 canvas 塞进 vw 布局里。这个坑的原理和pxtorem 对 echarts 没起到效果完全一样图表库内部 canvas 尺寸不受 CSS 插件控制。6.5 移动端 docx 的滚动与缩放docx-preview 渲染出的内容本质上是 canvas 绘制和 PDF 类似不是天然可滚动的 HTML。移动端想浏览长文档不能指望浏览器原生滚动行为要在外层容器维护滚动或分页视图并把外层容器高度设为动态视口单位让内容按页浏览。字体已经很小的情况下不建议加缩放按钮容易和页面滚动冲突。如果明确有这个需求可以在预览容器上做双击缩放但要注意 transform 后内部文本选择、点击位置会偏移体验打折扣。绝大多数场景按页浏览加手势翻页已经够用把交互做重不如做稳。7. 内外网构建切换与实测build mode 才是真正的管理开关7.1 两种构建模式怎么配内外网差异本质是环境变量差异我用构建模式区分。项目的 package.json scripts 这样写{ scripts: { build:external: vite build --mode external, build:internal: vite build --mode internal } }然后在.env.external和.env.internal里写不同的配置# .env.internal VITE_PREVIEW_MODEinternal VITE_API_BASE/internal-api# .env.external VITE_PREVIEW_MODEexternal VITE_API_BASE/api构建时 Vite 会自动加载对应模式的环境变量。程序里所有跟内外网相关的分支都通过import.meta.env.VITE_PREVIEW_MODE读取不要自己再猜环境。这个习惯从我第一次因为混淆环境导致线上预览全挂之后就再也不敢省了。7.2 按需加载与分包别让首屏扛下所有pdfjs-dist 和 docx-preview 打包出来都不小如果把三个预览组件都静态 import首屏 JS 会非常臃肿。正确做法是用 defineAsyncComponent 按文件后缀懒加载const PdfPreview defineAsyncComponent(() import(./PdfPreview.vue)) const DocxPreview defineAsyncComponent(() import(./DocxPreview.vue)) const PptxPreview defineAsyncComponent(() import(./PptxPreview.vue))同时在 vite.config 里做 manualChunks把大的基础库单独拆文件方便浏览器长缓存build: { rollupOptions: { output: { manualChunks: { pdf: [pdfjs-dist], docx: [docx-preview], }, }, }, },实测下来外网模式下 PDF chunk 和 DOCX chunk 都是按需加载的未预览文档时首页 JS 体积能少一半以上。内网模式虽然资源都打在本地方便但由于静态资源走本地服务加载速度通常反而比外网 CDN 更容易稳定因为不需要做证书校验、跨地域回源这些不可控环节。7.3 取舍与实测观察含踩坑最后分享几个真实观察。文档预览在后台管理系统里很常见但纯前端方案总会有边界。我把三类文件的预览链路上线后跑了半个月最深的体会有三个第一pdf.js 版本要锁死。v3 和 v4 的 Worker 配置、部分 API 名称都有差异升级大版本前先在测试环境把各类 PDF 都过一遍再上线。依赖不升级不是懒是稳定优先。第二移动端的任务不是说能用就结束要让业务方把手伸到真实手机上滑一滑。预览界面在 Android WebView 里出现过两个问题一个是大 PDF 渲染过程中切后台回来 canvas 黑屏需要在 visibilitychange 事件里重新渲染当前页另一个是 docx 渲染大量表格时某些国产手机浏览器直接崩溃后来加了超大文档转 PDF 预览的兜底逻辑才解决。第三内外网构建模式这种功能逻辑上只影响几行代码但部署上必须写清楚。我在内部文档里明确标注外网包走在线预览内网包走本地渲染加转换服务避免运维同事用错构建包。如果后续业务里出现了 xlsx、csv 在线预览方案也可以沿用这套框架xlsx 用 SheetJS 解析成表格csv 直接文本解析新加一个 PreviewXlsx 组件在 PreviewRouter 里加一个 case 即可需要转 PDF 的统一走 LibreOffice 转换服务。这套路由加懒加载加环境变量分流的架子撑三五年没有问题。