做了几年后台管理系统前端预览 PDF 这个需求几乎每个项目都会遇到。早先我习惯直接甩一个iframe嵌浏览器自带预览器后来发现移动端兼容差、样式没法定制、工具栏也不可控直到把渲染内核换成 PDF.js 之后才算是真正“收放自如”。这篇文章就把我在 vue3 项目里接入 PDF.js 的完整过程写出来从版本选型、worker 配置、首屏渲染链路到翻页缩放、文本选中复制再到我在实际项目里踩过的各种坑和排查思路一次性讲透。1. 集成 PDF.js 之前先想清楚这三件事1.1 PDF.js 到底是个什么角色PDF.js 是 Mozilla 维护的一个纯前端 PDF 解析与渲染引擎。它的核心思路是浏览器本身不提供统一的 PDF 解析接口PDF.js 就在 JavaScript 层面自己解析 PDF 文件结构再通过 Canvas 2D 把每一页画出来。也就是说你看到的 PDF 页面本质上是一张由 JavaScript 生成的 canvas 位图。这个“自己解析文件格式”的做法好处很明显不依赖浏览器厂商的 PDF 插件行为在 Chrome、Firefox、Edge 甚至 WebView 里都能保持一致。但也要接受一个现实——PDF.js 不是一个开箱即用的“预览组件”它提供的是 API 级别的能力页面的布局、工具栏、交互逻辑都需要你自己用 vue3 的响应式系统去组织和封装。1.2 版本选择不能拍脑袋先看 API 差异pdfjs-dist 是 PDF.js 的 npm 包名。我用过 2.x、3.x也用过 4.x、5.x最大的体会是这个库的大版本升级经常伴随“破坏性变更”尤其是 worker 的引入方式和模块格式。如果你在网上搜索教程很容易搜到 2.x/3.x 时代的老写法比如import pdfjsLib from pdfjs-dist pdfjsLib.GlobalWorkerOptions.workerSrc pdfjs-dist/build/pdf.worker.min.js或者 Webpack 项目里的import pdfjs-dist/webpack这些写法放在当前较新的 4.x/5.x 版本里不能说完全失效但已经不再推荐而且直接照抄往往会碰到 worker 找不到、构建报错、CORS 报错等一系列问题。实战建议如果是新项目直接锁定 4.x 或 5.x 系列并固定到具体版本号安装不要用裸的latest。我当前的推荐版本是pdfjs-dist5.3.0左右这一代API 稳定并且官方示例 Vite 写法可以直接套用。老项目保持原版本也可以但下面讲到的代码逻辑我会优先按 4.x/5.x 的写法来遇到版本差异我会单独说明。1.3 你需要的到底是“预览”还是“渲染内核”在动手写代码前还应该想清楚一点你是只需要在页面上显示 PDF还是需要嵌入到自己的业务逻辑里如果只是“能看就行”那我建议你别用 PDF.js直接用iframe :srcpdfUrl或者object省事得多。但一旦你有下面这些需求就必须考虑自建渲染链路需要自定义上一页/下一页、缩放、旋转、页码跳转等操作需要让用户选中 PDF 里的文字并复制文本层需要深度定制加载失败、加载中、页数提示等 UI需要在移动端 H5 或 WebView 里保持一致体验需要统计页面阅读时长、上报当前页等业务数据我的经验是80% 的管理系统“PDF 预览”需求其实都有工具栏控制要求所以直接用 PDF.js 的收益远大于维护成本。接下来的内容我会按“可复用的 vue3 组件”标准来拆解整个接入过程。2. 环境初始化和 worker 配置新版写法与老写法的差异2.1 创建 vue3 项目并安装 pdfjs-dist我用的是 Vite 作为构建工具这也是 vue3 生态最常见的组合。创建项目的过程不展开说了直接进入安装这一步。npm create vitelatest pdf-preview-demo -- --template vue cd pdf-preview-demo npm install npm install pdfjs-dist5.3.0安装完之后先不要急着写组件我建议先确认一下安装的版本因为后续很多 API 细节跟版本强相关npm list pdfjs-dist如果你的 package.json 里出现了 4.x 或者 5.x那么接下来这套配置就是给你准备的。如果显示的是 3.x说明你可能是历史遗留项目或 install 时没锁版本请额外留意 worker 配置的差异。2.2 最新版 worker 配置new URL 方式PDF.js 的解析逻辑由主线程发起但真正消耗 CPU 的解析计算是在 Web Worker 里完成的。官方文档要求你提供一个 worker 文件的地址让库内部去创建 Worker。如果不配置PDF.js 会回退到“fake worker”模式在主线程模拟 Worker 行为轻则卡顿重则直接报错。在 Vite 项目里最标准的没用之一是用new URL让构建工具识别并打包 worker 资源import * as pdfjsLib from pdfjs-dist pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.mjs, import.meta.url ).toString()这行代码我建议放在独立模块里比如src/utils/pdf.ts因为多个组件都要用到避免重复定义。为什么是这样写而不是直接import worker from pdfjs-dist/build/pdf.worker.min.mjs?worker这两种方式在 Vite 里都能跑但?worker方式会把 worker 作为一个独立的 chunk 输出逻辑上更“包工”而new URL(..., import.meta.url)方式会生成一个资源 URLPDF.js 内部拿这个 URL 去new Worker()兼容性更稳。我实测过在部署到子路径的项目里new URL方式能自动按 base 调整路径踩坑概率更小。2.3 旧版 3.x 的配置方式GlobalWorkerOptions 时代的做法如果是 3.x 的历史项目通常你会看到这样的配置import * as pdfjsLib from pdfjs-dist pdfjsLib.GlobalWorkerOptions.workerSrc require(pdfjs-dist/build/pdf.worker.entry)或者import pdfjs-dist/webpack原因在于 3.x 之前 utils 模块是 CommonJSpdf.worker.entry会按当前模块系统自动选择 worker 入口。而 4.x 之后包体改成纯 ESMbuild/pdf.worker.min.mjs是显式路径配合import.meta.url是官方示例的标准做法。这个差异本质上是模块体系变迁带来的配置方式变化。如果你在升级一个老项目遇到控制台报Setting up fake worker或Failed to fetch dynamically imported module大概率就是 worker 路径没有正确指向 4.x/5.x 的.mjs文件。等一下我在踩坑章节再详细展开。2.4 Vite 构建时的额外建议因为 PDF.js 体积不小web worker 文件又必须单独加载我建议在vite.config.js里适当调高 chunk 大小警告阈值避免打包时被警告刷屏export default defineConfig({ build: { chunkSizeWarningLimit: 2000 } })这不会影响构建结果只是让输出日志更清爽。另外如果项目部署在 CDN 或子路径要注意 Vue Router 的base和 Vite 的base要一致否则new URL生成的 worker 路径可能会 404。这个坑我在部署阶段踩过后面会专门讲。3. 第一页渲染链路从 PDF 文件到 Canvas 的完整实现3.1 getDocument 加载流程一次异步的解析协议PDF.js 对外的主入口是pdfjsLib.getDocument()它接收url、data或file参数返回一个PDFDocumentLoadingTask对象。这个对象上有promiseawait之后拿到PDFDocumentProxy这才是整个 PDF 文档的“句柄”。const loadingTask pdfjsLib.getDocument({ url: pdfUrl }) pdfDoc await loadingTask.promise console.log(总页数, pdfDoc.numPages)这里我习惯用对象参数{ url }而不是直接getDocument(pdfUrl)因为后面想加httpHeaders、withCredentials、cMapUrl等配置时对象形式更清晰。PDFDocumentProxy上有numPages、getPage()、destroy()等方法和属性它不直接参与绘制但所有页面操作都要先经过它。如果是本地文件上传后预览可以直接把File对象转成 ArrayBuffer然后用data传入const buffer await file.arrayBuffer() const loadingTask pdfjsLib.getDocument({ data: buffer })不建议用URL.createObjectURL(file)生成的临时 URL 传给getDocument虽然也能跑但内存生命周期管理更麻烦尤其是组件卸载时要记得revokeObjectURL少做一步就容易泄漏。3.2 依据 scale 计算 viewport设置 canvas 尺寸拿到PDFPageProxy之后要调用page.getViewport({ scale })得到页面在指定缩放比下的视口信息。这个viewport包含页面宽高、缩放矩阵等绘制所需参数。const page await pdfDoc.getPage(pageNum) const viewport page.getViewport({ scale: 1.5 })这里的scale可以理解为“渲染清晰度”和“显示尺寸”的乘积。scale 1.5意味着 PDF 页面按 1.5 倍输出尺寸绘制到 Canvas。实际项目中我建议基准值设为 1.0~1.5 之间后续再根据屏幕和用户操作动态调整。canvas 的width和height属性是物理像素尺寸style.width和style.height是 CSS 显示尺寸。如果直接都用viewport.width/height在高 DPI 屏幕上会显得模糊。正确做法是把 devicePixelRatio 考虑进去const dpr window.devicePixelRatio || 1 canvas.width Math.floor(viewport.width * dpr) canvas.height Math.floor(viewport.height * dpr) canvas.style.width ${viewport.width}px canvas.style.height ${viewport.height}px同时渲染前要把 canvas 的 2D context 做一个 setTransform 复位否则在重复渲染时会出现“越画越糊”或内容偏移const ctx canvas.getContext(2d) ctx.setTransform(dpr, 0, 0, dpr, 0, 0)这一步等同于告诉绘制系统接下来我以 dpr 倍的物理像素来画但坐标逻辑仍然按 CSS 像素走。很多教程不写这一行你会发现放大页面时 canvas 模糊或者每次渲染文字边缘发虚其实就是没处理 dpr。3.3 用 page.render 绘制到 Canvas注意 renderTask 的取消与等待渲染动作由page.render(params)触发参数里最重要两个就是canvasContext和viewport它返回一个RenderTask对象。这个对象上有promise和cancel()方法if (renderTask) { renderTask.cancel() } renderTask page.render({ canvasContext: ctx, viewport }) await renderTask.promisecancel()在快速翻页时特别关键。如果不做取消用户点击下一页后上一页的渲染任务仍然在跑渲染结果返回后可能覆盖到新页面造成画面闪烁、串页甚至白屏。正确姿势是每次开始新渲染之前先把上一次的renderTask.cancel()掉。一个容易被忽略的细节是renderTask.promise被 cancel 之后会 reject 一个RenderingCancelledException。如果你用await等待它又没有 catch控制台会冒红。所以我把渲染函数设计成 try/catch 包裹专门吞掉取消异常async function renderPage(pageNum) { if (!pdfDoc || !canvasRef.value) return try { const page await pdfDoc.getPage(pageNum) const viewport page.getViewport({ scale: scaleRef.value }) // 尺寸设置、dpr 适配… if (renderTask) renderTask.cancel() renderTask page.render({ canvasContext: ctx, viewport }) await renderTask.promise } catch (err) { if (err?.name RenderingCancelledException) return console.error(渲染失败, err) } }判断RenderingCancelledException时不同版本异常名可能叫RenderingCancelledException也有的版本是DOMException。稳妥做法是看err.name里是否包含cancel字样或者干脆在 catch 里判断renderTask是否处于 cancelled 状态。这个细节我在踩坑章节还会提。3.4 一个能跑起来的 vue3 单组件示例把上面的逻辑串起来就是一个最简单可用的 vue3 组件。我习惯用script setup组合式 API 来组织template div classpdf-container canvas refcanvasRef/canvas /div /template script setup import { ref, onMounted, onBeforeUnmount } from vue import * as pdfjsLib from pdfjs-dist pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.mjs, import.meta.url ).toString() const props defineProps({ pdfUrl: { type: String, required: true } }) const canvasRef ref(null) let pdfDoc null let renderTask null let ctx null const scale 1.5 async function loadPdf(url) { const loadingTask pdfjsLib.getDocument(url) pdfDoc await loadingTask.promise const totalPages pdfDoc.numPages await renderPage(1) } async function renderPage(pageNum) { if (!pdfDoc) return const page await pdfDoc.getPage(pageNum) const viewport page.getViewport({ scale }) const canvas canvasRef.value ctx canvas.getContext(2d) const dpr window.devicePixelRatio || 1 canvas.width Math.floor(viewport.width * dpr) canvas.height Math.floor(viewport.height * dpr) canvas.style.width ${viewport.width}px canvas.style.height ${viewport.height}px ctx.setTransform(dpr, 0, 0, dpr, 0, 0) if (renderTask) renderTask.cancel() renderTask page.render({ canvasContext: ctx, viewport }) try { await renderTask.promise } catch (err) { if (err?.name RenderingCancelledException) return console.error(err) } } onMounted(() { if (props.pdfUrl) { loadPdf(props.pdfUrl) } }) onBeforeUnmount(() { if (renderTask) renderTask.cancel() if (pdfDoc) pdfDoc.destroy() }) /script这个组件是后面所有扩展的地基。接下来我讲的翻页、缩放、文本层都是在它基础上加状态和方法。4. 实操扩展翻页、缩放、文本选中与复制4.1 翻页操作与状态管理的正确姿势实现上一页/下一页按钮很简单核心是维护currentPage和totalPages两个状态。但这里有个 vue3 特有的坑不要把pdfDoc、renderTask、ctx这些非纯数据对象放进reactive或ref否则 Vue 会给它们做响应式代理徒增性能开销甚至在某些版本下触发奇怪的报错。我实测下来的经验是currentPage、totalPages、scale这些页面状态用ref管理pdfDoc、renderTask用普通let变量。页面 DOM 需要绑定状态时模板里只依赖ref变量。翻页的逻辑里加一个边界判断防止用户狂点按钮导致页码越界async function nextPage() { if (currentPage.value totalPages.value) return currentPage.value await renderPage(currentPage.value) } async function prevPage() { if (currentPage.value 1) return currentPage.value-- await renderPage(currentPage.value) }每次 querycurrentPage变化会触发页面状态更新canvas 重绘。这里还可以顺便做一个加载态翻页过程中把按钮置灰避免重复触发。不过用了renderTask.cancel()之后即使连点按钮也不会出大问题因为新渲染会立刻取消旧渲染。4.2 缩放适配scale 计算与高清屏细节缩放看似是改一个scale变量重新渲染但要做得顺手必须理解 viewport 和 CSS 尺寸的联动。我的做法是把scale放进ref用户点放大按钮时修改它然后重新调用renderPage(currentPage.value)const scaleRef ref(1.5) function zoomIn() { scaleRef.value Math.min(5, scaleRef.value 0.25) renderPage(currentPage.value) } function zoomOut() { scaleRef.value Math.max(0.5, scaleRef.value - 0.25) renderPage(currentPage.value) }渲染函数内部引用scaleRef.value而不是外部固定常量这样缩放和翻页共用一套逻辑不会出现“缩放了翻页又变回原样”的问题。如果你做的不是按钮缩放而是像地图那样“以鼠标位置为锚点缩放”那么还需要在缩放前记录鼠标相对页面内容的位置缩放后调整滚动条偏移保证用户盯着的文字不跑偏。这个逻辑不复杂但比较繁琐普通业务用按钮缩放就够了我暂时不展开。还有一个容易忽视的点PDF.js 渲染出的页面宽度是固定的如果外层容器宽度小于 canvas 宽度会出现横向滚动条。在管理系统里通常希望 PDF 自适应容器宽度。这时候可以通过容器宽度反推 scaleconst containerWidth containerRef.value.clientWidth scaleRef.value containerWidth / viewport.width相当于“让页面刚好铺满容器”。但要注意这么做之后用户再手动放大缩小scale 就会被固定值替换。更好的方案是维护一个baseScale容器自适应时的 scale和userScale用户手动缩放倍率实际渲染 scale 等于两者相乘。篇幅关系我提一下思路实战中按这个结构设计状态就很清晰了。4.3 文本层实现让用户能选中和复制 PDF 里的文字canvas 渲染出来的页面是一张位图浏览器默认无法选中文字。如果你做过合同预览、论文阅读类的项目肯定知道“不能复制文字”是个致命体验缺陷。PDF.js 的解决方案是用page.getTextContent()解析页面里的文本和位置然后用 DOM 元素叠加在 canvas 上方实现“看起来是 PDF文字却能选中复制”的效果。文本层的基本结构是一个绝对定位的容器包裹在 canvas 外层或旁侧容器内每个文本片段是一个span通过绝对定位设置left、top、fontSize、transform等样式。下面是简化版实现async function renderTextLayer(page, viewport, container) { const textContent await page.getTextContent() container.innerHTML container.style.width ${viewport.width}px container.style.height ${viewport.height}px textContent.items.forEach((item) { if (!item.str || !item.transform) return const span document.createElement(span) span.textContent item.str span.className pdf-text-span // 关键把 PDF 内容坐标转换为屏幕坐标 const tx pdfjsLib.Util.transform(viewport.transform, item.transform) const fontHeight Math.hypot(tx[2], tx[3]) const fontScale fontHeight ? fontHeight / 1000 : 0.01 span.style.left ${tx[4]}px span.style.top ${tx[5] - fontHeight}px span.style.fontSize ${fontHeight}px span.style.transform rotate(${Math.atan2(tx[1], tx[0])}rad) span.style.fontFamily item.fontName ? ${item.fontName} : sans-serif container.appendChild(span) }) }这里的viewport.transform是渲染时的坐标变换矩阵item.transform是 PDF 内部为这个文本项定义的变换矩阵两者通过pdfjsLib.Util.transform合成得到屏幕上每个字的位置。我这个实现里fontSize直接取变换后的高度是因为 PDF 里字体高度按抽象单位存储需要经过变换矩阵映射到屏幕像素。样式上文本层容器要放在 canvas 正上方并用 CSS 保证透明和穿透.pdf-text-layer { position: absolute; top: 0; left: 0; overflow: hidden; line-height: 1; user-select: text; pointer-events: none; color: transparent; } .pdf-text-span { position: absolute; white-space: pre; transform-origin: 0% 0%; }pointer-events: none让鼠标事件穿透文本层不影响页面自身的点击交互user-select: text则保证文字仍然可以被选中。这个组合看起来矛盾实际在浏览器里的表现是可以用鼠标拖选文字但不会拦截 canvas 上的点击事件。如果你的项目需要滚动条或缩放文字层记得在每一次renderPage成功后都重新调用renderTextLayer并先container.innerHTML 清掉旧 span否则旧文字会叠在新的上面。4.4 文本层的局限与替代方案手动实现文本层有一个绕不开的局限文本位置和样式只能做到“近似还原”遇到旋转文字、跨行、复杂字体时可能出现位置偏移或者被 canvas 内容盖住一半。如果你做的是 PDF 批注、文字搜索高亮这类对坐标精度要求很高的功能更推荐用官方在新版本里封装的TextLayer它接收textContentSource、viewport等参数帮你处理了更多边界情况。不过它 API 变动幅度较大我用过的版本迁移成本不低。如果你的项目实际上不做文字交互只想屏蔽选中效果那可以直接不做文本层也能少很多适配工作。我的原则是按需实现别为了“炫技”给每个 PDF 组件都配一层文本。5. 高频踩坑记录worker 报错、白屏、内存泄漏的排查链路5.1 worker 报错从“Setting up fake worker”说起很多第一次在 vue3 Vite 里接入 PDF.js 的朋友控制台会看到这样的提示Setting up fake worker Failed to fetch dynamically imported module: http://localhost:5173/pdf.worker.min.mjs这个报错的本质是PDF.js 尝试创建真正的 Web Worker但拿不到 worker 脚本地址于是回退到主线程模拟 Worker。在 4.x 之后的版本里fake worker 模式下连基础功能都可能直接白屏而不是像 3.x 一样只是性能差。排查路径我建议按顺序走检查GlobalWorkerOptions.workerSrc是否设置。如果没设置补上new URL(...)那段代码。检查路径字符串是否是pdfjs-dist/build/pdf.worker.min.mjs。有些教程写的是.js在 4.x/5.x 里就不对。在浏览器 Network 面板搜索pdf.worker看请求是否成功、状态码是否为 200。如果 404多半是资源路径没被正确打包检查 Vite 的base配置或文件位置。确认没有其他页面代码覆盖GlobalWorkerOptions.workerSrc。真实项目中我还遇到过一种情况项目里同时引用了老版本pdfjs-dist的某个插件它内部自己又设置了一遍workerSrc把路径覆盖成了错误地址。排查时可以在设置之后立即打印console.log(pdfjsLib.GlobalWorkerOptions.workerSrc)确认无误再继续。5.2 本地 file:// 协议与 CORS 跨域的限制如果你用npm run dev起本地服务通过http://localhost访问页面加载本地 PDF 或同源 PDF 是没问题的。但如果你直接把打包后的dist目录用双击 index.html 的方式打开也就是file://协议PDF.js 的 worker 加载和 PDF 文件读取都会因为跨域策略失败。一条让人崩溃的报错长这样Access to fetch at file:///.../pdf.worker.min.mjs from origin null has been blocked by CORS policy原因很简单file://协议下页面源是null任何同目录文件请求都视为跨域。解决方式也不是去改什么 worker 配置而是正确起一个本地静态服务器npm run previewpreview 模式会按生产构建启动一个本地服务既能验证打包产物又不会踩 file:// 的坑。如果你负责的是一些“发送 HTML 压缩包给别人打开”的内部项目我强烈建议把静态服务器作为标准交付手段而不是发一个双击打开的文件。另一个常见场景是PDF 文件存储在 OSS/CDN 上页面域名和文件域名不同。这时要求 OSS 配置正确的 CORS 规则允许页面源跨域读取。如果对方没有配浏览器会拦截响应。排查跨域问题最快的方式是看 Network 面板里 PDF 文件请求的 response header 有没有Access-Control-Allow-Origin。5.3 快速翻页导致白屏或画面闪烁白屏通常发生在快速连点翻页时根因不是渲染失败而是“渲染任务被 cancel 之后错误没有被正确处理”。前面我说过renderTask.cancel()会让当前渲染的 promise reject如果这个 reject 没有 catch它会作为 unhandled rejection 抛到全局React 或 Vue 的错误边界如果配置不当可能直接导致组件卸载或页面空白。完整处理方式是所有await renderTask.promise的地方都包一层 try/catch并且把 cancel 场景单独放行。另外我还遇到过一个诡异现象页面 A 渲染完成后页面 B 的渲染任务开始前canvas 上显示的是旧内容视觉上出现“上一页残影”。解决办法是在渲染前清空画布ctx.clearRect(0, 0, canvas.width, canvas.height)这样在取消旧任务到新任务完成之间的空档canvas 是干净的视觉上只会闪一个空白不会出现残影叠加。如果业务上不能接受空白闪烁那就再加一个 loading 占位层等renderTask.promise完成后再隐藏。5.4 组件卸载后仍然继续渲染内存泄漏的完整处置这个问题最容易出现在 SPA 里用户从“合同预览”页跳到“订单列表”页组件实例已经卸载但之前发起的 PDF 渲染任务还没有结束。渲染完成后的回调会尝试操作已经卸载的 DOM轻则报错重则内存持续上涨。我做这类组件时onBeforeUnmount里一定按顺序做三件事onBeforeUnmount(() { // 1. 取消尚未完成的渲染任务 if (renderTask) renderTask.cancel() // 2. 释放 pdfDoc 内部资源 if (pdfDoc) pdfDoc.destroy() // 3. 如果有临时 URL需要 revoke if (tempUrl) URL.revokeObjectURL(tempUrl) })pdfDoc.destroy()会关闭 PDF 文档释放内部缓存的字体、图片等资源。这一步不做你连续打开几十个不同 PDF 后内存占用能轻松飙到几百 MB。我遇到过一个真实项目就是漏了 destroy导致后台系统用一两个小时后就卡到无法操作。还有一点容易忽略在组件内部监听window事件比如缩放窗口自适应、键盘翻页后记得在卸载时移除监听。否则用户切换路由后旧组件的监听器还在跑每次都会触发一次渲染白耗性能。处理办法是用onMounted里 addEventListeneronBeforeUnmount里 removeEventListener。6. 性能优化大文件和多页场景下的渲染策略6.1 一次渲染一页还是多页按场景选方案上面的示例组件是“当前页模式”一次只渲染一页翻页时切换 canvas 内容。这种方案对内存最友好实现也简单适合大多数后台系统的单页预览。但如果你的业务要求像浏览器预览那样“滚动长页、连续显示”就得引入多页渲染。多页渲染最简单做法是用一个容器按顺序放多个 canvas渲染当前视口附近的页面而不是把所有页面一次性渲染完。假设一份 PDF 有 80 页如果上来就渲染 80 个 canvas页面直接卡死是必然的。正确的做法是参考虚拟滚动思想只渲染可视区域和预渲染缓冲区的页面滚动时动态挂载和卸载 canvas。我实现过一个简化版维护一个currentRange根据滚动位置计算 当前应该渲染第几页到第几页每次只创建范围内的 canvas。离开范围的 canvas 直接移除并调用pdfDoc.destroyPage或复用page.cleanup()释放内存。这个方案在大文件场景下能保持流畅滚动但代码量明显更大我只建议在真正需要“连续滚动阅读”的项目里做。6.2 页面缓存策略把渲染结果复用到极致如果用户在一页和下一页之间来回切换每次都重新渲染显然很浪费。一个常见的优化是用 Map 缓存已经渲染出的 canvas 位图const pageCanvasCache new Map() async function renderPageWithCache(pageNum) { if (pageCanvasCache.has(pageNum)) { // 直接用缓存的 canvas 替换到容器 return pageCanvasCache.get(pageNum) } // 渲染并存入缓存 }这里要控制缓存上限一般只缓存当前页的前后 2~3 页超过上限就删除最早缓存的页面。因为 PDF 页面位图是很吃内存的A4 页面在高分屏下渲染出一张图动辄几 MB缓存十几张就是几十 MB。用 LRU 思想清理才能保证长时间翻阅不出问题。我自己通常只做前后两页的缓存辅助不做全局缓存。原因很简单现代浏览器保留 canvas 位图的成本并不比重新渲染低太多而且缓存多了翻到后面页面时早期的缓存就成了纯浪费。6.3 大 PDF 文件的加载优化按需加载与进度反馈公司内部系统经常会上传几百 MB 的标书、图纸这种文件用getDocument({ url })直接加载等待时间非常长而且用户没有反馈直观感受就是“白屏了点不动”。处理办法有两个方向。一是给loadingTask加进度回调。getDocument返回的PDFDocumentLoadingTask上有onProgress事件const loadingTask pdfjsLib.getDocument({ url }) loadingTask.onProgress (progressData) { const loaded progressData.loaded const total progressData.total || 0 progressPercent.value total ? Math.round((loaded / total) * 100) : 0 }这样 UI 上可以显示“加载中 xxx%”。实测下来对超大型文件进度条能大幅降低用户的焦虑感。二是考虑使用服务端拆分上传或预压缩但这属于后端配合范畴前端要做的就是在渲染前判断文件页数如果页数太多提示用户“该文件共 N 页可能加载较慢”而不是默默卡着。给用户预期比任何优化都重要。6.4 渲染清晰度与性能的平衡很多开发者在追求“清晰”时会把 scale 调很大比如scale 3。我见过有人为了让 PDF 在高分屏上更清楚直接设 3结果打开一个 50 页的 PDF每页渲染耗时接近 1 秒翻页卡顿明显。实际上屏幕显示只需要达到 devicePixelRatio 对应的物理像素就够了。我的建议是先用scale 1.5起步结合window.devicePixelRatio做适配用户在需要看清细节时再通过缩放按钮主动放大。这样既保证了清晰度又不会让默认渲染变成性能负担。如果确实需要加载后立即展示高质量页面可以在renderPage时先用低 scale比如 0.7快速出图再在后台用高 scale 重新渲染替换。这种“渐进式增强”在移动端比较常见但实现复杂度高一些普通项目不是必须。7. 组件化封装与项目落地建议把上面这些逻辑全部揉进一个.vue文件里也能跑但一旦业务变多代码会很难维护。我会建议按层拆分src/utils/pdf.ts统一导出GlobalWorkerOptions.workerSrc配置、加载 PDF、渲染页面、文本层等纯函数src/components/PdfViewer.vue负责 UI 交互层模板里有 toolbar、canvas、文本层逻辑上调用 utils 里的函数业务页面只负责传pdfUrl和监听页面跳转等业务事件这样的好处是如果以后要做“PDF 批注”“PDF 转图片”等功能可以直接复用 utils 里的底层函数不必改动 UI 组件。我在组件开发里一直坚持“UI 与逻辑分离”在 PDF.js 这种强逻辑场景下尤其值得。状态管理上如果多个业务页面需要共享“当前 PDF 打开的文件、当前进度”可以考虑把pdfDoc放到 Pinia 里。但我要提醒Pinia 的 state 会自动做响应式代理而pdfDoc内部包含大量非可序列化对象和方法放进 store 之后虽然用起来方便但性能和维护性都要打折扣。我的习惯是pdfDoc仍然放在组件内部管理Pinia 只存 URL、页码、页码列表这些纯状态。如果你团队里已经有成熟的组件库比如 Element Plus、Ant Design Vue建议把按钮、进度条、空状态这些 UI 都用组件库的控件不要自己重复造轮子。PDF.js 负责的是“渲染内核”那些外围交互交给现成的 UI 组件开发效率会高很多。最后分享一个部署上的细节打包上线后在 Nginx 静态资源目录下确认assets里确实有pdf.worker.min-xxxx.mjs这个文件。有些 CDN 上传工具会忽略.mjs后缀或者 MIME 类型配置不对导致 worker 加载时报 MIME 错误。最简单的验证方式是用生产地址直接访问这个.mjs文件如果浏览器能正常下载说明资源发布没问题如果返回了 HTML 错误页就说明 CDN 或 Nginx 对.mjs的 Content-Type 配置有误。这类问题在本地一般测不出来上线前一定要检查。我在实际项目里从 3.x 一路升到 5.x每一次升级都会碰到 API 变化带来的问题尤其是 worker 路径和文本层这两个点改过好几次。如果你正卡在某个版本报错上别急着改业务代码先确认版本号再按对应版本来查很多问题其实都是“教程版本”和“实际版本”不匹配造成的。