简介：这份pdf.js使用demo是一份面向Web前端开发者的实践示例，以Mozilla团队开源的PDF.js为核心，演示如何在浏览器中嵌入PDF文档的解析与渲染，解决开发者不熟悉库集成与配置的痛点。压缩包解压后共6个文件：3个HTML示例页面分别演示不同应用场景，2个JavaScript核心文件提供PDF解析与worker线程处理能力，1个PDF文档用于测试渲染效果，整个包仅601KB，轻量易用，部署到IIS或Apache等Web服务器后即可通过HTTP访问。示例代码覆盖了PDF加载、页面缩放、自定义导航等常见操作，并可根据需要调整配置项、监听相关事件。开发者在研究这些代码时，还能了解worker线程机制、UI样式定制以及错误处理和性能优化的实践思路，从而快速搭建属于自己的PDF在线阅读功能。目前已有1791人学习下载，适合希望快速集成PDF阅读能力的前端工程师与学习者，通过对照示例源码，可以大幅缩短从零接入PDF.js的摸索时间。 领导上周丢给我一个需求：网页里要展示一份合同PDF，不能弹新窗口，不能依赖浏览器插件，还要能定制上下页按钮和缩放比例。我第一反应是iframe，但iframe的样式操控能力太弱，PDF插件的外观在Chrome和Edge里完全不受网页控制，移动端更是直接拉起系统预览，体验割裂得很。折腾一圈之后，我还是老老实实回到pdf.js，写了一个demo才把需求收了尾。
这篇内容就围绕这个demo展开。pdf.js是Mozilla开源的JavaScript PDF渲染引擎，核心能力是在浏览器端直接解析PDF文件并绘制到canvas上，前端可以完全接管渲染结果的样式和交互。无论你是要做一个在线预览页面，还是想在自己写的管理后台里内嵌文档展示，甚至做一套完整的在线签名流程，pdf.js都是绕不开的基础库。它适合所有需要前端原生渲染PDF的场景，尤其适合那些对UI有定制需求、不想用开箱即用组件的团队。
1. 为什么PDF预览这事儿前端绕不开
1.1 浏览器自带预览的三大限制
大多数前端遇到PDF预览的第一反应，不是iframe就是embed标签，这俩确实能用，但用起来浑身难受。第一个限制是UI完全不可控，Chrome的PDF阅读器带自己的工具栏，你没法在页面上加一个"确认已阅读"的按钮，也没法把底部的缩放条换成自己的样式。第二个限制是移动端体验分裂，Android上的行为跟随系统浏览器，iOS上则可能直接调用QuickLook，同一个页面在不同设备上长得完全不一样。第三个限制是网络请求和权限体系被架空，你想统计用户在第几页停留了多久，想控制文档只允许预览前三页，这类需求用iframe基本做不了。
iframe唯一的好处是零代码，但一碰到稍微深入一点的需求就立刻触顶。如果你的项目仅仅是把一个PDF挂在页面上，不影响订阅、不统计行为、不做权限控制，那iframe确实合适。但实际情况是，文档类产品一定会往查看、标记、审批的方向演进，早一点迁到可控渲染方案，后面会少走很多弯路。
1.2 pdf.js的定位与边界
pdf.js不是PDF阅读器，它是一个解析器和渲染引擎。它把PDF内部的文字、字体、图片、矢量路径解析成前端可用的对象，再通过canvas把每一页画出来，本质上就是"PDF转canvas"的过程。它不限制你最终的交互形态，你可以拿它做阅读器，也可以做缩略图墙，甚至可以批量提取页面截图。
但它的边界同样要心里有数。它不是一个PDF编辑器，虽然你能在canvas上叠加批注，但那需要自己实现一套坐标换算和绘制层逻辑。它也不是PDF解析库就能搞定一切，遇到带复杂加密、自定义签名算法、内嵌复杂字体的文件，解析失败或者渲染错位的概率真实存在。我见过有人在群里抱怨pdf.js乱码，最后发现是直接把加密过的PDF原文件塞给了前端，这种场景本来就不该让前端硬扛，应当在服务端先解密或转换。
2. 最简demo：一个页面把PDF第一页渲染出来
2.1 引入pdf.js的三种路径选择
用之前先解决引入方式。三种主流路径：CDN、npm、源码构建。CDN的方式最简单，适合快速写demo或者在公司内网直接引用，如下面这句：
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>npm方式适合正经工程化项目，装依赖跑构建一把梭：
npm install pdfjs-dist然后按模块方式导入，现代打包工具都能处理好。
源码构建的方式除非你要深度定制worker逻辑，否则没必要碰，维护成本高，收益不大。我的建议是：demo直接CDN，生产项目直接npm，不要贪图省事在正式项目里挂CDN，因为第三方CDN的稳定性、版本更新、域名封禁风险都不可控，这是上过线的人都会同意的结论。
2.2 完整可跑的demo代码
这个demo的目标很简单：浏览器加载一份PDF文件，把第一页画在canvas上。完整代码如下：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>pdf.js 最简 demo</title> <script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script> <script> pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js'; </script> </head> <body> <canvas id="pdfCanvas" style="width: 100%;"></canvas> <script> const canvas = document.getElementById('pdfCanvas'); const ctx = canvas.getContext('2d'); pdfjsLib.getDocument('sample.pdf').promise .then(pdf => pdf.getPage(1)) .then(page => { const viewport = page.getViewport({ scale: 1.5 }); canvas.width = viewport.width; canvas.height = viewport.height; return page.render({ canvasContext: ctx, viewport }).promise; }) .then(() => { console.log('第一页渲染完成'); }); </script> </body> </html>这段代码的逻辑分三步：加载PDF文档、拿到第一页、用viewport决定画布尺寸，然后调用render绘制。注意getDocument返回的是一个PDFDocumentLoadingTask对象，真正的加载结果要通过.promise获取，这是一开始最容易踩的坑，我在第一次写的时候直接拿getDocument的返回值当pdf对象用，结果报了一堆类型错误。
2.3 渲染流程里最容易忽略的viewport概念
viewport是pdf.js里最容易忽略但极其核心的概念。一个PDF页面有自己的固有尺寸单位，PDF内部单位是point，1 point约等于1/72英寸。浏览器里的CSS像素和真实屏幕像素之间还有devicePixelRatio的差异。viewport就是做这个换算的中间层：你告诉它一个scale比例，它告诉你对应的像素宽高。
代码里canvas.width直接用了viewport.width，这是逻辑像素，如果你的屏幕是2倍屏，物理上会有模糊感。更好的做法是canvas.width设为viewport.width乘以devicePixelRatio，同时用ctx.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0)做坐标系缩放，这样渲染出来的字才锐利。这个细节我在第3节会专门展开，因为它是demo和可用组件之间的一道分水岭。
3. 从demo到可用组件：把翻页和缩放加上
3.1 页面状态与渲染触发
只渲染第一页跟玩具没有区别，要让demo真正可用，至少得把翻页、页数展示、缩放这几个功能补上。这里的关键不是各自怎么实现，而是怎么组织状态。
我用一组变量管理当前状态：
let pdfDoc = null; let currentPage = 1; let totalPages = 0; let currentScale = 1.2;翻页逻辑很好写，页数限制好边界就行：
function goToPage(pageNum) { if (pageNum < 1 || pageNum > totalPages) return; currentPage = pageNum; renderPage(currentPage); document.getElementById('pageInfo').textContent = `${currentPage} / ${totalPages}`; }这个过程中的教训是：渲染完成后更新页数展示，效率很高，但真正的问题是快速点击下一页时会出现渲染错乱。用户连点两次，上一次的渲染任务还没结束，下一次渲染已经开始，canvas最后显示的是哪一页全看谁先执行完，这就是渲染竞态。解决方式我放在3.3节，先不剧透。
3.2 缩放时的清晰度问题：devicePixelRatio
在普通笔记本上不明显，在MacBook的Retina屏幕上，直接用viewport.width作为canvas.width会让文字发虚。原因前面提过，viewport.width是CSS像素，不是物理像素。物理像素需要乘以devicePixelRatio：
function renderPage(pageNum) { return pdfDoc.getPage(pageNum).then(page => { const baseViewport = page.getViewport({ scale: currentScale }); const dpr = window.devicePixelRatio || 1; canvas.width = baseViewport.width * dpr; canvas.height = baseViewport.height * dpr; ctx.setTransform(dpr, 0, 0, dpr, 0, 0); const transform = dpr !== 1 ? [dpr, 0, 0, dpr, 0, 0] : null; return page.render({ canvasContext: ctx, viewport: baseViewport, transform }).promise; }); }这里做了三件事：canvas的像素尺寸按dpr放大；canvas的实际样式尺寸仍然交给CSS控制，保证不撑破布局；渲染时通过transform参数把画布内容放大。这样在高清屏上文字边缘干净，在普通屏上也不会多出额外下载量。
3.3 渲染竞态的坑：用渲染任务编号
渲染竞态是一个非常隐蔽的bug。用户快速点击下一页，或者拖动缩放条连续触发多次渲染，后发起的任务被先发起的任务覆盖，最后屏幕上显示的页面是错的，甚至还会看到一条明显的老页面残留。
我的解决办法是给每次渲染任务分配一个自增编号，渲染开始前先记录编号，渲染完成的回调里只认最新编号的结果：
let renderTaskId = 0; function renderPage(pageNum) { const taskId = ++renderTaskId; return pdfDoc.getPage(pageNum).then(page => { // 设置canvas尺寸... return page.render({ canvasContext: ctx, viewport }).promise; }).then(() => { if (taskId !== renderTaskId) { console.log('丢弃过期渲染结果，当前页已变化'); return; } // 执行UI更新：页码、按钮状态等 }); }这个方案理解成本低，排查还简单。另外如果之前有未完成的RenderTask，可以调用它的cancel方法主动取消掉，比单纯丢弃结果更省资源。不过cancel之后render的promise会走reject，需要单独捕获，别让错误冒泡到全局去。
4. 接真实文件时踩到的坑
4.1 跨域加载与CORS的绕过思路
demo里sample.pdf跟页面同源，一切正常。一旦把PDF换成对象存储的地址，比如阿里云OSS、腾讯云COS或者私有S3，就会遇到跨域问题。浏览器直接加载跨域PDF会报错，报错信息类似"file origin does not match viewer's"。
解决思路有三条。一是通过fetch把PDF文件以ArrayBuffer方式拉回来，再传给getDocument：
fetch(pdfUrl) .then(res => res.arrayBuffer()) .then(buffer => pdfjsLib.getDocument({ data: buffer }).promise)二是在存储服务端配置CORS跨域头，让浏览器允许直接加载。三是绕过浏览器跨域限制，在服务端加一个代理接口，由后端去取文件再转给前端。我实际项目里最常用的是第一条，因为不需要动服务端配置，前端可控性最强。但要警惕，一次大文件全量拉到内存再解析，对内存是双重压力，后面4.3节会说怎么处理大文件。
4.2 中文字体丢失和乱码的处理
pdf.js对标准PDF字体的支持很成熟，但中文PDF经常内嵌私有子集字体，解析后偶发乱码、方块或者某些字符偏移。这个问题在v2时代比较严重，v3之后内置了CMap映射，中文症状减轻不少，但并没有绝迹，尤其是很多国产办公软件导出的PDF，字体表写得不太规范，渲染时会有偏差。
通用处理方法是把缺失字体作为外部字体文件传给render，在page.render的renderContext里设置fontFamily，或者通过pdfjsLib.setFonts配置自定义字体路径。但这需要你知道原始PDF用的是什么字体，实际操作中更常用的下策是转图片：服务端先把PDF转成高清图片，前端直接渲染图片，PDF.js只负责交互框架。这个方法在打印输出、合同归档、签名存证这类要求100%还原的场景里反而更常见，牺牲文本选择的代价换稳定性。
4.3 大PDF的内存与加载卡顿
一份几百页的扫描版PDF，每一页都是一张大图，前端一次性渲染会让浏览器内存直接报警。我踩过最惨的一次，一份300页的财务文档，加载完整个DOM都卡死，鼠标移动都掉帧。
处理大文件的核心思路是懒加载与按需释放。懒加载是指只有页面进入可视区才调用getPage和render；按需释放是指在翻页离开后，清掉整页Canvas画布内容，或者复用一块固定大小的canvas，避免每一页都重新分配canvas对象。同时getDocument时建议开启cMapUrl和cMapPacked，对中文PDF的加载速度和内存占用都有改善：
pdfjsLib.getDocument({ url: pdfUrl, cMapUrl: 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/cmaps/', cMapPacked: true }).promise如果是超大文件，前端方案再优化也有限，应该引入服务端预处理：把PDF按需转成按页切分的图片流，前端走图片懒加载。这套方案在很多电子合同平台是标准做法，原因就是PDF.js在前端处理超大文件的天花板很明显。
5. 把demo收尾前最后再做的几个优化
5.1 预加载相邻页面
翻页体验的卡顿感，很大程度是下一页的渲染工作才开始。做完前面的基础功能后，我做了一个简单的预加载：当前页渲染完成之后，在浏览器空闲时间预取下一页的数据。
if ('requestIdleCallback' in window) { requestIdleCallback(() => { const nextPage = currentPage + 1; if (nextPage <= totalPages) { pdfDoc.getPage(nextPage).catch(() => {}); } }); }注意这里只做getPage的预取，不做render。原因是render会真正占用canvas资源，预渲染下一页可能影响当前页的展示性能，预取到Page对象已经能把后续渲染时间缩短一截，这个性价比最合适。
5.2 worker引入与UI线程解耦
pdf.js默认有一个web worker负责解析PDF数据，但如果你把worker.workerSrc忘了配置，它会在主线程上运行解析逻辑，文件一复杂就会卡住整个页面。不少demo只写了加载pdf.min.js不写worker配置，看起来能跑，其实是降级方案。
显式配置worker是必做项，而且worker的版本必须与主文件一致，两边版本不一致会出现一些莫名其妙的解析错误。打包环境下还要注意路径问题，pdfjs-dist会把worker文件单独输出，用打包工具时要确保worker文件能被正确复制到静态资源目录。
5.3 文本选择与搜索的后续方向
如果文档是可复制文本型PDF，pdf.js还能通过TextLayer把文字按位置叠加到canvas上。TextLayer的原理是获取每个文本片段在页面上的坐标和尺寸，生成对应的div，覆盖在canvas上方，让那些文字真正可以被鼠标选中。
这个功能对很多产品来说是硬需求，做的时候就两个注意点：一是textContent解析需要单独调用page.getTextContent()，二是TextLayer的dom节点定位要和viewport严格对齐，不然文字跟画面错位，用户一选中就暴露。搜索关键词高亮、批注定位、目录跳转，都是在这个textLayer基础上扩展的。换句话说，你把这一步打通，pdf.js的方案才算完整。
我在实际使用中发现，很多团队在pdf.js这个库上的抱怨，追到最后都不是库本身的问题，而是接入姿势问题：要么是版本不匹配，要么是没理解viewport，要么是没考虑大文件。所以回到出发点，这个demo虽然只有几十行，但把viewport、worker、渲染任务这三根支柱立住了，后面加功能、加样式、加性能优化都不会有大返工。顺着这个方向往下做，你会发现pdf.js的前端渲染能力确实被频繁低估。
本文还有配套的精品资源，点击获取
的三维声波方程求解与MATLAB实现)
