简介这是一份基于PDF.js的纯JavaScript PDF在线预览与打印Demo适合Web前端开发者快速上手PDF渲染场景。压缩包共376个文件约2.49MB包含168个bcmap字符映射文件、105个properties描述文件以及js、html、css、png等资源覆盖PDF.js核心库、worker脚本和示例页面。Demo实现了通过API加载PDF、按页渲染到Canvas/SVG、动态调节缩放比例并借助File API打开本地PDF配合window.print()触发打印。项目目录结构清晰源码与静态资源分离便于开发者对照学习或直接嵌入现有系统。该资源已有9926人学习下载适合需要实现文档在线预览、打印功能或研究PDF.js底层渲染逻辑的前端工程师。1. 用pdf.js做纯JS在线预览与打印先把需求边界划清楚如果你的项目里出现了一个必须在线预览PDF、还得支持一键打印的需求最省事的方案不是把PDF转成图片再抛给前端而是直接用pdf.js以纯JavaScript的方式把PDF渲染到浏览器里。这套方案不需要后端转码预览和打印共用同一套渲染管线页面体验也更贴近桌面阅读器交互完全由前端掌控。我第一次正面遇到这个需求是在一个内部单据管理系统里用户上传合同后要能直接看、直接打印。当时第一反应是让后端去转图片结果上传后等十几秒才能看到翻一页还要重新请求。后来换到pdf.js预览变快了不说打印也直接走canvas管道不用再单独处理图片清晰度的问题。这篇笔记适合被产品提了“PDF在线预览加打印”需求的Web前端也适合做技术选型时判断“值不值得引入pdf.js”的负责人。接下来的内容我会把渲染原理、最小可运行Demo、翻页缩放打印的实现细节以及高频踩坑都拆开讲。2. pdf.js的渲染管线与方案取舍它到底做了什么pdf.js看起来像一个“把PDF画到canvas上的库”但它内部做的事情远不止一句“canvas渲染”这么简单。理解它的内部链路能帮你判断它适不适合你的项目也能帮你在排查问题时找到该往哪个方向查。2.1 从PDF字节流到canvas像素渲染链路到底怎么走一个PDF文件不是一张大图片它是按对象组织的页面对象、字体对象、图像对象、内容流。每个页面的内容流里存着绘制指令比如“在这个坐标画一条线”“用这个字体在某个位置写一段文本”“把这张图片贴到某个区域”。pdf.js要做的事就是把这份二进制结构解析出来再把指令逐条翻译成canvas绘图动作。我一般把整条渲染链路分成三段理解。第一段是文档解析pdf.js调用getDocument把PDF文件读进来在Web Worker里完成词法分析和对象解析最终得到一个pdfDoc对象你可以从上面拿到总页数、元信息、以及每页的引用。第二段是页面准备调用pdfDoc.getPage(n)拿到Page对象再通过page.getViewport({scale})计算这一页在当前缩放比例下的宽高同时拿到渲染所需的transform。第三段才是真正绘制page.render把页面内容流里的绘图指令逐条执行到canvas上这个过程是异步的返回一个Promise。用代码看会更直观这是能跑通的最小渲染片段// 引入pdf.js以下两种方式二选一 // 1) script标签全局引入window[pdfjs-dist/build/pdf] // 2) npm安装后以ES Module方式引入。这里以全局变量方式演示 const pdfjsLib window[pdfjs-dist/build/pdf]; // 关键配置workerSrc必须指向pdf.worker.min.js的实际路径 // 路径错了会直接白屏这是新手最容易踩的坑之一 pdfjsLib.GlobalWorkerOptions.workerSrc /static/pdf.worker.min.js; // 创建加载任务url可以是相对路径、绝对路径或Blob URL const loadingTask pdfjsLib.getDocument({ url: /static/contract.pdf }); try { // loadingTask.promise在文档解析完成后resolve const pdfDoc await loadingTask.promise; console.log(总页数, pdfDoc.numPages); // 取第1页注意pageNum从1开始不是从0开始 const page await pdfDoc.getPage(1); // 按1.5倍缩放计算viewport决定canvas的尺寸和内容缩放 const scale 1.5; const viewport page.getViewport({ scale }); // 把canvas尺寸设置为viewport宽高 const canvas document.getElementById(pdfCanvas); const ctx canvas.getContext(2d); canvas.width viewport.width; canvas.height viewport.height; // 执行渲染await确保绘制完成后再继续 await page.render({ canvasContext: ctx, viewport, }).promise; // 渲染完成后canvas里就是这一页的位图 console.log(第1页渲染完成尺寸, viewport.width, viewport.height); } catch (err) { console.error(PDF加载或渲染失败, err); }几个需要留意的参数url字段除了传字符串路径也可以传{url: ...}或{data: Uint8Array}。如果传二进制数据就不再依赖网络路径顺带绕开了跨域问题后面排查章节会细说。scale的取值直接决定渲染清晰度预览时一般在1到2之间够用打印或需要高清截图时可以按需调高。另外需要强调一点getDocument返回的不是Promise本身而是一个loadingTask对象真正的Promise在loadingTask.promise上。如果你直接await getDocument(...)拿到的不会是你想用的pdfDoc这是很多表面“没报错但拿不到数据”的隐藏原因。2.2 三种在线预览方案对比为什么pdf.js比转图片更可控在决定用pdf.js之前我实际评估过另外两种常见做法。把它们放在一起对比能更清楚地看到pdf.js在这个需求里的位置。第一种是后端转图片。服务器用渲染引擎把PDF每一页导出成PNG前端用img标签展示。它的优点是实现简单前端几乎不用写逻辑缺点也很明显每次翻页都要重新请求一次图片网络差时体验很糟。页面数量多时后端要提前把所有页都转完用户等待时间长转出来的图片分辨率是固定的高清屏上文字会发虚放大看更模糊。最尴尬的是打印——如果客户想直接打印PDF原件你只能打印图片清晰度和PDF原文件不是一个级别。第二种是直接让浏览器打开PDF。比如iframe的src直接指向PDF文件或者用embed标签。这个方案的优点是零开发成本但代价是交互和样式完全不可控。不同浏览器对PDF内嵌插件的表现不一致有的浏览器会直接下载而不是预览。你还拿不到“当前页是第几页”这样的状态想加自定义按钮操作PDF内容基本不可能。第三种就是pdf.js。它的优势集中在三点第一解析和渲染全部在前端完成不依赖后端服务第二渲染用的是canvas前端可以在渲染前干预scale、rotation渲染后还能拿到像素数据做二次处理第三预览和打印用的是同一套渲染管线打印结果和屏幕看到的一致不会出现“预览挺清晰打印出来糊了”的分裂。我遇到的一个典型场景是用户上传合同后先预览确认内容再直接打印归档。用pdf.js之后“确认”和“打印”用的是同一份canvas数据产品再也没抱怨过“打印的怎么和预览不一样”。2.3 引入pdf.js本地静态文件与打包集成两种方式pdf.js的引入方式直接决定了你项目的构建复杂度。这里说两种最常见的做法。一种是最省事的静态引入。去官方发布渠道下载pdf.js的发行包把pdf.min.js和pdf.worker.min.js拷到项目的静态资源目录用script标签引入然后设置workerSrc指向worker文件的URL。这种方式的优点是零构建配置写个HTML加两个script就能跑缺点是全局变量挂在window下在模块化项目里用起来不太顺手后期要按需引入还得改造。!-- 静态引入方式两个script标签一个核心库一个入口 -- script src/static/pdf.min.js/script script // 设置worker路径路径是相对当前页面而言的 pdfjsLib.GlobalWorkerOptions.workerSrc /static/pdf.worker.min.js; // 后续调用pdfjsLib.getDocument即可 /script另一种是npm方式集成到构建工具里。现在的项目基本都是Vite、Webpack这类构建体系更习惯用npm包。安装后在代码里直接import使用worker文件通过构建工具以静态资源方式处理。这样做的好处是路径由构建工具统一管理不用手工维护版本。// 以ES Module方式在构建工具中使用 import * as pdfjsLib from pdfjs-dist; // 在Vite中通常这样设置workerSrc import workerUrl from pdfjs-dist/build/pdf.worker.min.js?url; pdfjsLib.GlobalWorkerOptions.workerSrc workerUrl; // 后续使用方式与静态引入一致 const loadingTask pdfjsLib.getDocument({ url: /contract.pdf });这里有一个容易被忽略的细节workerSrc设置的worker脚本路径其版本必须和核心库匹配。如果你的核心库是一个版本worker文件却是另一个版本的运行时会报API版本不匹配的错误。遇到这种问题先查两个文件的版本号是否一致往往比翻文档更快。3. 纯JS实现PDF在线预览翻页、缩放与连续滚动这一章我们把Demo升级成一个可用的阅读器。目标很明确能翻页、能缩放、能切单页和连续滚动模式。每个功能点我都会给核心代码和参数说明。3.1 做一个可复用的PdfViewer类从渲染到翻页的最小封装如果你只是临时在某个页面用一次直接写脚本没问题。如果这个功能要在多个页面复用我建议一开始就封装成一个类。这不是过度设计因为PDF预览几乎必然要接翻页、缩放、旋转这几个操作都围绕同一个canvas和同一个pdfDoc不封装的话重复代码会堆得很难看。class PdfViewer { constructor(canvas, options {}) { this.canvas canvas; this.ctx canvas.getContext(2d); this.pdfDoc null; this.pageNum options.startPage || 1; // 当前页从1开始 this.scale options.scale || 1.5; // 初始缩放比 this.rotation options.rotation || 0; // 旋转角度0/90/180/270 } // 加载PDF文档并渲染当前页 async load(url) { const loadingTask pdfjsLib.getDocument({ url }); this.pdfDoc await loadingTask.promise; return this.render(); } // 渲染当前页 async render() { if (!this.pdfDoc) return; const page await this.pdfDoc.getPage(this.pageNum); const viewport page.getViewport({ scale: this.scale, rotation: this.rotation, }); // 先设置canvas内部像素尺寸再用CSS控制显示尺寸 this.canvas.width viewport.width; this.canvas.height viewport.height; await page.render({ canvasContext: this.ctx, viewport, }).promise; // 渲染完成后回调页码信息方便更新UI if (this.onPageChange) { this.onPageChange(this.pageNum, this.pdfDoc.numPages); } } // 上一页 prev() { if (this.pageNum 1) return; this.pageNum--; this.render(); } // 下一页 next() { if (this.pageNum this.pdfDoc.numPages) return; this.pageNum; this.render(); } // 跳转到指定页 jumpTo(pageNum) { if (pageNum 1 || pageNum this.pdfDoc.numPages) return; this.pageNum pageNum; this.render(); } // 设置缩放缩放后重新渲染当前页 setScale(scale) { this.scale scale; this.render(); } // 设置旋转角度角度必须是90的整数倍 setRotation(rotation) { this.rotation ((rotation % 360) 360) % 360; this.render(); } }封装完之后页面里的使用方式非常清爽const viewer new PdfViewer(document.getElementById(pdfCanvas), { scale: 1.5, startPage: 1, }); viewer.onPageChange (current, total) { document.getElementById(pageInfo).textContent ${current} / ${total}; }; // 绑定按钮事件 document.getElementById(prevBtn).addEventListener(click, () viewer.prev()); document.getElementById(nextBtn).addEventListener(click, () viewer.next()); // 初始化加载 viewer.load(/contract.pdf);这段代码有三个细节值得展开。第一canvas.width和canvas.height必须在每次渲染前重新赋值因为切换页面或缩放后viewport宽高会变canvas内部像素尺寸不跟着变就会出现内容变形或渲染区域被裁剪。第二prev和next里要判断边界页码不能小于1也不能大于总页数。第三rotation传90的倍数时viewport宽高会自动交换不需要手动处理横竖屏。3.2 翻页、缩放与旋转viewport参数的三个关键计算viewport是pdf.js渲染时最核心的几何概念。它的作用是把PDF页面内部使用的坐标系统转换成屏幕像素坐标系统。你几乎不需要手动算坐标变换但必须知道viewport的生成规则否则scale和rotation会在代码写完之后反咬你一口。第一次踩坑是这样的我把scale设为1.5渲染完后发现文字边缘发虚。原因不是scale不够大而是canvas元素在CSS里被拉伸了。canvas的实际像素尺寸是viewport.width乘以devicePixelRatio才够清晰。也就是说在高分屏上想让canvas不模糊不能只调scale还要把canvas.width设为viewport.width和DPR的乘积同时在CSS里把显示宽度设回viewport.width。这个细节在打印场景尤其明显。下面这张表是我调试时常用的参数关系方便对照参数作用常见取值注意点scale页面内容的缩放比例预览1~2打印按需求调整scale是整体缩放不是单独放大文字rotation页面旋转角度0/90/180/27090和270时viewport宽高互换canvas.width/heightcanvas内部像素尺寸设为viewport宽高不设置会导致内容被裁剪或模糊CSS宽高canvas在页面上的显示尺寸与canvas像素尺寸一致用CSS拉伸会模糊旋转这里有个具体的坑当从0度切换到90度时viewport.width和viewport.height会互换。如果你在代码里缓存了旧宽度并直接复用旋转后页面会被截断。我的处理方式是每次render都重新从page.getViewport拿最新viewport不手工缓存宽高。提示旋转角度传90的倍数内部会把角度归一化但你还是应该自己处理负角度比如-90会被归一成270。我统一用(rotation % 360 360) % 360来规避。// 旋转90度后viewport的宽高自动交换 const viewportNormal page.getViewport({ scale: 1.5, rotation: 0 }); const viewportRotated page.getViewport({ scale: 1.5, rotation: 90 }); console.log(viewportNormal.width viewportRotated.height); // true console.log(viewportNormal.height viewportRotated.width); // true缩放操作比较常见的误区是用CSS的transform: scale去放大canvas。这种做法看着页面放大了但canvas内部像素没有变化放大后文字会糊成一团。正确的做法永远是重新调用getViewport按新的viewport尺寸重新渲染canvas。3.3 连续滚动模式把PDF变成像网页一样往下刷很多场景下用户不喜欢一页一页翻更希望像浏览网页一样连续往下滚。这个需求在pdf.js里没有内置的“滚动渲染器”需要自己组合渲染结果来实现。我用的做法是把PDF每一页渲染成一个独立canvas按顺序摆在一个可滚动的div里然后监听滚动事件按需渲染进入视口的页面。其中关键的一条优化是“按需渲染”不要一开始把100页全部渲染完。100页意味着100个canvas内存很容易爆掉初始等待时间也会很长。async function renderAllPages() { const container document.getElementById(pdfContainer); const pdfDoc await pdfjsLib.getDocument({ url: /multi-page.pdf }).promise; for (let i 1; i pdfDoc.numPages; i) { // 为每一页创建一个div占位后续按需填充canvas内容 const wrapper document.createElement(div); wrapper.className pdf-page; wrapper.dataset.pageNum i; // 先给一个最小高度占位避免滚动高度计算错误 wrapper.style.height 800px; container.appendChild(wrapper); } // 初次渲染只渲染前3页后续通过滚动事件补充 const endPage Math.min(3, pdfDoc.numPages); for (let i 1; i endPage; i) { await renderPageInto(container, pdfDoc, i); } }滚动事件里的核心判断是“当前这个页面的canvas是否已经渲染过”。如果渲染过就跳过没有渲染且进入视口范围才执行。参数上常用一个“提前量”比如页面进入视口前200像素就开始渲染这样用户滚过去时页面已经准备好了不会看到空白闪一下。// 滚动时按需渲染进入视口的页面 container.addEventListener(scroll, () { const scrollTop container.scrollTop; const viewportHeight container.clientHeight; const pages container.querySelectorAll(.pdf-page); pages.forEach((page) { // 如果已经渲染过canvas直接跳过 if (page.querySelector(canvas)) return; const rect page.getBoundingClientRect(); // 加上200像素的提前量保证滚动到位前已经渲染好 if (rect.top viewportHeight 200 rect.bottom -200) { const pageNum parseInt(page.dataset.pageNum); renderPageInto(container, pdfDoc, pageNum); } }); });renderPageInto的实现和前面单页渲染类似取page对象创建canvas按viewport设置尺寸调用page.render然后把canvas放进占位div。区别是目标容器变了预览场景的scale可以适当降低比如设为1.2因为滚动预览不需要和打印一样的像素密度。这个方案在30页以内的文档上跑起来非常流畅。超过50页建议再加一层“离屏回收”把距离当前视口太远且已经渲染的canvas从DOM里移除只保留最近几页。这个优化会在第6章展开。先提醒一句不要贪多按需渲染是连续滚动模式的底线。4. PDF打印功能从canvas到纸张输出的完整链路预览渲染出来了打印是重头戏。很多团队在这里翻车原因是把“打印”理解成CtrlP。实际上当你要从Web页面打印一份“看起来像PDF原文件”的文档时要处理的是打印窗口、打印样式、canvas清晰度三件事。4.1 打印方案选型window.print与隐藏iframe最常见的两种打印做法是直接调用window.print和构建隐藏iframe再调用iframe.contentWindow.print。直接调用window.print简单但它打印的是当前页面全部内容如果你的页面上还有工具栏、导航栏、其他卡片就得靠CSS media print把它们隐藏掉。这个方案适合页面结构简单、打印内容基本等于页面内容的场景。隐藏iframe方案更适合“打印的内容和当前页面UI不一样”的场景。比如我做的那个单据系统预览页面上有左侧目录、顶部工具条但打印的时候只想要PDF内容本身。用iframe方案就能完全隔离打印内容把canvas放进去再调用iframe的打印方法。// 创建隐藏iframe并写入要打印的PDF内容 function printPdfCanvas(sourceCanvas) { // 创建一个不显示的iframe const iframe document.createElement(iframe); iframe.style.position fixed; iframe.style.right 0; iframe.style.bottom 0; iframe.style.width 0; iframe.style.height 0; iframe.style.border 0; document.body.appendChild(iframe); // 写入打印页面的HTML结构 const doc iframe.contentWindow.document; doc.open(); doc.write( html head style page { margin: 10mm; } body { margin: 0; } .pdf-page { width: 100%; margin-bottom: 10px; } .pdf-page canvas { width: 100%; } /style /head body div classpdf-page canvas idprintCanvas/canvas /div /body /html ); doc.close(); // 把源canvas的图像复制到iframe里的canvas上 // 用drawImage拷贝像素避免跨iframe的样式污染 const iframeCanvas doc.getElementById(printCanvas); const ctx iframeCanvas.getContext(2d); iframeCanvas.width sourceCanvas.width; iframeCanvas.height sourceCanvas.height; ctx.drawImage(sourceCanvas, 0, 0); // 等iframe里的canvas绘制完成后触发打印 iframe.onload () { iframe.contentWindow.focus(); iframe.contentWindow.print(); // 打印结束后记得移除iframe避免残留无用DOM setTimeout(() { document.body.removeChild(iframe); }, 500); }; }提示iframe的onload事件在doc.write之后触发但canvas的绘制有时是异步的如果点完打印按钮没反应多半是iframe内容还没就绪。我习惯在onload之后再用requestAnimationFrame等一帧双保险。这个方案的优点是把打印内容与主页面完全隔离。预览页面再复杂也不会被打进去。缺点是要多写一点iframe的HTML拼接代码以及注意iframe加载时机。如果打印按钮点击后没反应多半是iframe还没加载完就调用了print这是我实际踩过的坑。4.2 打印样式A4匹配、边距与分页控制打印样式和屏幕样式完全不同因为纸张的物理尺寸是固定的。A4纸是210mm×297mm打印机的非打印区会额外吃掉一部分边距。你需要让canvas按A4比例缩放否则打印出来要么内容被截断要么页面之间空出很多白边。我的做法是先按A4比例算出目标打印宽度再把PDF页面渲染到匹配尺寸的canvas里。这里要注意DPI。屏幕预览可能为了清晰度引入了devicePixelRatio但打印场景的canvas实际像素尺寸应该由打印机的DPI要求决定。一般打印需求下canvas宽度按A4宽度乘以一个合适的DPI值来算即可。function getPrintScale(pdfPage) { // A4纸宽度210mm约8.27英寸 // 打印DPI按150dpi计算这是清晰度与文件体积的折中 const printDpi 150; const targetWidthInch 8.27; const targetPixelWidth Math.round(targetWidthInch * printDpi); // 获取页面原始尺寸下的viewport const baseViewport pdfPage.getViewport({ scale: 1 }); // 返回需要的缩放比例 return targetPixelWidth / baseViewport.width; }有了scale之后渲染打印canvas时使用它async function renderPageForPrint(pdfPage) { const printScale getPrintScale(pdfPage); const viewport pdfPage.getViewport({ scale: printScale }); const canvas document.createElement(canvas); canvas.width viewport.width; canvas.height viewport.height; const ctx canvas.getContext(2d); await pdfPage.render({ canvasContext: ctx, viewport, }).promise; return canvas; }打印样式上还有几个容易被忽略的点。第一body的margin在打印时最好设为0边距交给page控制否则会出现双层边距。第二多页PDF打印时每个页面应该是独立块避免两页内容挤在同一张纸上。第三如果canvas尺寸大于纸张可打印区域浏览器会自动缩小缩小后清晰度会下降。所以宁可把canvas做得稍微小一点也不要让浏览器做二次缩放。/* 打印样式放在iframe的style标签里 */ media print { body { margin: 0; } .pdf-page { page-break-after: always; /* 每个pdf页独占一张纸 */ } .pdf-page:last-child { page-break-after: auto; /* 最后一页后面不需要再分页 */ } }另外一个我踩过的细节打印多页PDF时如果某一页canvas的高度超过了纸张可用高度浏览器会自动压缩到一页里导致页面内容看起来很小。解决思路不是缩小canvas而是按纸张高度重新计算渲染区域把一页PDF按比例拆分成多段输出。不过大部分业务场景的单页PDF高度都在A4范围内遇到超高的页面再单独处理即可。4.3 打印质量canvas清晰度与图片格式选择打印质量是“预览时看不出来、打出来才后悔”的问题。屏幕上看canvas 100%没问题打印出来文字发虚几乎都是因为canvas的像素密度不够。解决办法分两步理解。第一步按打印DPI计算目标像素尺寸而不是沿用屏幕预览的scale。第二步如果你需要在打印前把canvas转为图片放入iframe转换时使用的图片格式不能进一步压缩画质。通常PNG比JPEG更适合打印PNG是无损压缩尤其是文字、边线这类高对比内容JPEG压一遍边缘就会出现明显的锯齿和噪声。// 把canvas转成PNG dataURL再放入iframe function canvasToPrintImage(sourceCanvas) { // toDataURL的第二个参数是JPEG压缩质量但对PNG无效 // 打印场景用PNG避免边缘发糊 return sourceCanvas.toDataURL(image/png); }这里要特别提醒一个坑toDataURL(image/jpeg, 0.9)看起来质量很高但实际上JPEG再怎么调质量档位对细线条和文字的处理都不如PNG干净。我在一个合同打印需求里亲眼见过同样一张canvasJPEG转出来的打印件合同条款里的逗号和句号边缘有轻微噪点PNG出来的完全没有。改用PNG是零成本的质量提升。如果你的输出通道是iframe里直接放canvas就不需要转图片canvas本身渲染清晰就行。转图片的必要性在于有些打印场景需要在iframe里做额外排版比如加页眉页脚、公司抬头、页码。canvas直接进iframe比较灵活但要织入更多HTML元素时转成img会更方便。5. pdf.js踩坑与常见问题排查五个高频场景的解决方案这一章是实战里反复会撞上的坑。每条都按“现象→原因→解决”来写方便照排查。5.1 跨域加载PDF被浏览器拦截现象本地打开HTML一切正常部署到测试环境后pdf.js报错“Unexpected server response”或NetworkError控制台里能看到PDF请求被CORS拦截。原因pdf.js的getDocument对url发起的是fetch请求跨域时受同源策略限制。如果PDF存放在另一个域名或端口下服务端没有返回允许跨域的响应头请求就会被拦下来。解决一是让后端在PDF接口的响应头里加上Access-Control-Allow-Origin允许前端域名访问。二是如果需要从接口拉取PDF二进制前端先用fetch取回ArrayBuffer再通过data字段传给getDocument。第二种方式能彻底绕开跨域因为PDF内容已经变成内存里的二进制数据不再是跨域请求。// 方案A直接传url要求服务端配置CORS const loadingTask pdfjsLib.getDocument({ url: https://oss.example.com/files/a.pdf }); // 方案B先fetch为ArrayBuffer再传给data const res await fetch(/api/pdf/123, { credentials: include }); if (!res.ok) { throw new Error(PDF接口请求失败状态码 res.status); } const buffer await res.arrayBuffer(); const loadingTask pdfjsLib.getDocument({ data: buffer });方案B的另一个好处是能携带自定义请求头比如token认证。用url方式时pdf.js内部发起的fetch不方便加头需要额外配置httpHeaders参数。如果你既要跨域又要带token直接在外部fetch然后传data是最省心的。5.2 中文PDF渲染成方块或乱码现象PDF能打开英文和数字显示正常但中文全部显示成方块甚至直接乱码。原因PDF里的中文字体通常不是嵌入的完整字体而是引用了系统字体。pdf.js解析这类字体时需要额外的CMap数据来映射字符编码到字形这些映射文件默认不会随核心库一起打包。CMap路径没配置或配置错误中文就显示不出来。解决在getDocument的参数里指定cMapUrl和cMapPacked。cMapUrl指向存放CMap文件的目录cMapPacked设为true表示使用压缩格式。// 配置CMap路径解决中文等非拉丁字体的渲染问题 const loadingTask pdfjsLib.getDocument({ url: /contract.pdf, // cmaps目录里放pdf.js发布的cmap文件 cMapUrl: /static/cmaps/, // 使用压缩格式文件更小加载更快 cMapPacked: true, });这个配置看起来只有两行但很多人在集成时根本没注意到容易在正式环境被中文文档打脸。cMap文件体积不小生产环境建议放到CDN并单独做缓存。5.3 worker加载失败导致白屏或API版本不匹配现象页面打开后一片空白控制台报错“Failed to load worker”或“API version mismatch”。原因GlobalWorkerOptions.workerSrc指向的worker文件路径不对浏览器加载不到。或者pdf.js核心库和worker文件版本不一致一个项目里同时混用了不同版本的pdf.js。解决第一把workerSrc打印出来确认路径能通过浏览器地址栏直接访问。第二检查页面上是否加载了多个pdf.js副本比如既通过npm引入又通过script引入两边版本不一致就会冲突。我常用的排查方式是直接在Network面板里看worker.min.js请求的响应状态和实际内容404就改路径返回的是HTML而不是JS脚本说明server把.js请求重定向到了入口页。// 打印当前worker路径确认是否可访问 console.log(pdfjsLib.GlobalWorkerOptions.workerSrc); // 也可以临时禁用worker强制在主线程渲染便于定位问题 // 注意这会在渲染大文件时卡住主线程仅用于排查 pdfjsLib.GlobalWorkerOptions.workerPort null;禁用worker只是排查手段不能作为生产方案。大PDF在无worker模式下会长时间阻塞主线程页面动不了体验很差。5.4 大文件渲染卡顿与内存暴涨现象一个几百页的PDF加载后页面滚动越来越卡甚至标签页直接崩溃内存占用持续攀升。原因每页渲染生成一个canvascanvas的像素数据是巨大的内存消耗。一张A4大小、150dpi的画布单页就占几MB内存如果连续渲染几十页且都保留在DOM里内存就是线性增长的。解决坚持按需渲染只渲染用户当前看到的页面和前后一两页。对连续滚动模式维护一个“已渲染页面集合”页面滚远后把canvas从DOM移除并释放。如果只是单页预览模式在切换页码时用renderTask.cancel()取消还在进行中的渲染任务避免上一页没渲染完又渲染下一页白耗性能。// 在PdfViewer里加入取消逻辑 class PdfViewer { constructor(canvas) { this.renderTask null; } async render() { // 如果上一轮渲染还没完成先取消掉 if (this.renderTask) { this.renderTask.cancel(); } const page await this.pdfDoc.getPage(this.pageNum); const viewport page.getViewport({ scale: this.scale }); this.canvas.width viewport.width; this.canvas.height viewport.height; // 保存renderTask下次渲染时可以取消 this.renderTask page.render({ canvasContext: this.ctx, viewport, }); await this.renderTask.promise; this.renderTask null; } }关于内存还有一个容易被忽略的点pdfDoc本身也占用内存。如果用户打开多份PDF然后切换最好在切换时调用pdfDoc.destroy()释放文档对象否则每一份打开的PDF都会一直占着内存。5.5 打印结果模糊或尺寸不对现象点击打印后打印预览里PDF内容模糊或者纸张方向上内容被截断多页PDF全部挤在一张纸上。原因模糊是因为渲染canvas时用的scale不足以支撑打印DPI尺寸不对或分页错误是因为iframe里的打印样式没有正确设置page边距和page-break。解决打印专用渲染时按A4尺寸计算目标scale而不是直接复用屏幕预览的scale。多页打印时每一页用块容器包裹设置page-break-after: always最后一页去掉这个属性。如果用的是iframe方案记得在打印前把iframe的document.title设置好否则部分浏览器打印出来的文档标题是about:blank。// 打印前设置文档标题影响打印页眉的显示 iframe.contentDocument.title 合同预览打印; // 打印样式里处理分页 doc.write( style page { size: A4; margin: 10mm; } .pdf-page { break-after: page; page-break-after: always; /* 兼容旧浏览器 */ } .pdf-page:last-child { page-break-after: auto; break-after: auto; } /style );尺寸问题的另一个来源是CSS缩放。打印时浏览器发现canvas像素尺寸大于纸张可用区域会自动按比例缩小这通常导致内容变小、留白变大。解决思路是按A4可用区域宽度确定渲染scale宁可多留一点边距也不要让浏览器做二次缩放。6. 进阶生产环境下的pdf.js性能优化与落地技巧到这里核心的预览、打印、排查都齐了。这一章补两个在生产环境里最能拉开体验差距的策略以及一个我自己坚持的习惯。6.1 页面缓存与离屏回收按需渲染解决了初始慢的问题但没有解决“往回翻页又重新渲染”的问题。用户从第1页翻到第10页再翻回第3页第3页可能已经被移除了又得重新渲染一遍这个等待在本地环境不明显在真正低配的办公电脑上非常明显。我的做法是做一个分级缓存最近访问的8页渲染结果保留在内存里用Map存储key是页码value是渲染好的canvas引用。超过这个数量时优先移除距离当前页最远的canvas。这样既避免重复渲染又不至于让内存无限增长。class PageCache { constructor(maxSize 8) { this.map new Map(); this.maxSize maxSize; } get(pageNum) { const item this.map.get(pageNum); if (item) { // 每次访问都移动到最新位置实现LRU this.map.delete(pageNum); this.map.set(pageNum, item); } return item; } set(pageNum, canvas) { if (this.map.has(pageNum)) { this.map.delete(pageNum); } this.map.set(pageNum, canvas); // 超出上限时删除最久没访问的条目 // Map的迭代顺序是插入顺序所以第一个key是最早的 if (this.map.size this.maxSize) { const oldestKey this.map.keys().next().value; this.map.delete(oldestKey); } } }这个东西看起来简单但它把“回翻页卡顿”这个体验问题彻底解决了。6.2 用URL.createObjectURL替代base64传输PDF数据如果是从后端接口拿到的二进制很多人会习惯转成base64再传给getDocument。base64会让二进制体积膨胀约33%而且decode成Uint8Array需要额外一次拷贝。直接new Blob然后createObjectURL对浏览器来说就是一个本地URL解析速度更快内存也更节约。async function loadPdfFromApi(pdfId) { const res await fetch(/api/pdf/${pdfId}); if (!res.ok) { throw new Error(PDF接口请求失败); } const blob await res.blob(); // 生成一个blob: URL让pdf.js像加载普通URL一样加载 const objectUrl URL.createObjectURL(blob); const loadingTask pdfjsLib.getDocument({ url: objectUrl }); const pdfDoc await loadingTask.promise; // 用完后记得释放 URL.revokeObjectURL(objectUrl); return pdfDoc; }这里有个小提醒objectUrl在使用期间不能提前revoke否则pdf.js后续的页面读取会失败。我一般在pdfDoc.destroy()之后才调用revokeObjectURL。这个顺序用错的话会出现“第一页能渲染翻页开始报错”的诡异现象。6.3 一个我坚持的习惯我每次在项目里集成pdf.js都会把worker路径、cMap路径、版本号集中放在一个配置文件里并在代码里显式打印一次。这个习惯救过我很多次——线上出了问题远程排查时只要让同事把这三行打印发过来问题原因基本就定位了一半。pdf.js最大的坑从来不在于API有多难而在于静态资源的路径和版本在部署环节悄悄出错。先检查资源再怀疑代码这个排查顺序能帮你少走很多弯路。希望这个方向对你有用也祝你少踩几个我踩过的坑。本文还有配套的精品资源点击获取