简介：pdfjs-2.2.228-dist.rar 是 Mozilla 团队开源的 PDF.js 库 2.2.228 构建分发包，专为 Web 前端工程师和需要在线预览 PDF 的开发者准备，目标是提供无需浏览器插件的高质量、跨平台阅读体验，同时解决原生 PDF 支持差异与界面定制困难的问题。压缩包共包含 402 个文件，整体大小约 3.73MB，文件类型涵盖 bcmap、properties、js、map、css、png、svg、license、html 等；其中 build 目录下的 pdf.js 与 pdf.worker.js 是核心运行脚本，web 目录包含默认 UI 的样式和模板，bcmap 与 properties 则用于 CJK 等字符映射，保障中文内容正确显示。此资源已有 1285 人学习下载，适合用于内容管理系统、文档中心、电子合同或在线教育平台。解压后可直接引入核心脚本，在 canvas 中渲染 PDF，并支持分块加载、文本搜索、书签、表单、注释等互动特性；同时项目采用 MPL 许可，开发者可灵活定制工具条、全屏模式和多语言界面，快速构建跨浏览器、跨平台的高质量阅读体验。 前阵子接了个老项目改造任务，里面有个功能是PDF合同在线预览。技术栈还停留在Vue2 + webpack3，后端直接给文件流。我先去GitHub官方仓库找pdf.js，发现release包有一堆版本，选了半天，最后下载了一个网盘里流传的pdfjs-2.2.228-dist.rar，解压完直接扔进项目，居然一次就跑通了。既然这包网上还有不少人在找，我就把自己集成时的完整过程和踩过的坑写出来，希望能帮到正在被PDF预览折磨的兄弟。文章里的方案主要围绕2.2.228这个版本，它属于2.x时代比较稳定的一个迭代，兼容性不错，API调用方式和现在主流的3.x/4.x差别也不大，很多老项目用它很合适。
1. 先搞清楚这个压缩包是什么
1.1 PDF.js 的核心价值与 dist 目录结构
PDF.js是Mozilla团队维护的一个开源项目，核心就是用JavaScript解析PDF文件，然后通过Canvas把每一页渲染出来。也就是说，不需要浏览器原生插件，也不需要后端先转图片，只要一个前端页面就能实现PDF的查看、缩放、翻页、文本选择等功能。pdfjs-2.2.228-dist.rar这个压缩包，拆开看其实就是一个发行版（distribution），里面包含了经过打包压缩后的运行文件，一般会有这几个部分：
pdf.min.js：主库文件，封装了加载、渲染PDF的全部API。pdf.worker.min.js：后台线程文件，负责解析PDF数据，避免阻塞主线程。web/目录：官方内置的一个完整PDF阅读器，里面有viewer.html、viewer.js、viewer.css等，打开viewer.html就是一套现成的PDF预览界面。cmaps/目录：字符映射表，处理某些PDF的中文、日文、韩文编码时要用。license、README等说明文件。
一开始我不太理解为什么要有pdf.worker.min.js这个独立文件，后来查资料才知道，PDF文件解析是重计算任务，如果放在主线程里做，页面会直接卡死。PDF.js把解析工作放到了Web Worker里，主线程只负责接收渲染指令和绘制Canvas，这样界面交互才能保持流畅。使用的时候必须告诉库去哪里找Worker文件，这就是后面讲到的workerSrc配置。
1.2 为什么选择 2.2.228 而不是最新版
现在PDF.js已经到4.x甚至5.x了，为什么还要用2.2.228？因为老项目最怕升级带来的兼容性灾难。我那个项目用的Vue2 + webpack3，直接上最新版pdfjs-dist，经常遇到ES6语法被编译得乱七八糟、模块加载方式不匹配的问题。2.2.228是2019年前后发布的版本，API稳定，体积也相对小，在低版本浏览器上表现友好，所以网上很多老系统的教程都认准这个版本。
另外，release包虽然能在GitHub官方仓库找到，但很多同事习惯直接下载别人整理好的rar。比如pdfjs-2.2.228-dist.rar这类资源，一般都是把官方build目录和web目录整合过一遍，去掉了源码和示例，装起来更快。不过从非官方渠道下载存在一定风险，解压后最好先杀毒，同时核对一下文件完整性——可以看压缩包里的README.md或者mainfest信息，或者解压后检查pdf.min.js大小是否在1MB左右。网上有些流传版本会被人改过，混进广告脚本，这一点务必小心。
2. 部署方案：从解压到页面预览
2.1 放置静态资源并调整路径
拿到pdfjs-2.2.228-dist.rar之后，第一步是解压。如果Windows环境用WinRAR或7-Zip，解压密码通常会在下载页的说明里，别信那些“rar password cracker”之类的东西——暴力破解工具没几个干净的，中过招的人很多。正确操作是：把解压出来的文件夹改个名，比如pdfjs，然后整个丢到项目的静态资源目录。传统项目就放根目录或者/static下，Vue项目放public下，uni-app项目放static下。
放好之后，路径引用要小心。比如在普通HTML页面里这样引用：
<script src="/pdfjs/pdf.min.js"></script> <script src="/pdfjs/pdf.worker.min.js"></script>如果页面上访问路径时出现404，先看资源是不是真的放到了服务器可访问的目录，再看项目是不是配置了baseUrl。我遇到过因为Tomcat部署目录层级多了一层，导致/pdfjs变成了/项目名/pdfjs，所有引用全部失效，这种问题检查一下网络请求里资源的完整地址就能发现。
2.2 用自带的 viewer.html 实现完整预览
如果不需要自己写UI，直接用官方自带的viewer是最省事的方式。把web/viewer.html部署到服务器后，通过URL参数传入PDF文件地址即可：
http://localhost:8080/pdfjs/web/viewer.html?file=/pdfs/contract.pdf这里注意几点：file参数里的地址必须编码，尤其是文件名带中文或空格时，要调用encodeURIComponent处理。比如：
var pdfUrl = '/pdfs/' + encodeURIComponent('劳动合同.pdf'); var viewerUrl = '/pdfjs/web/viewer.html?file=' + encodeURIComponent(pdfUrl); window.open(viewerUrl);另外，用viewer.html预览时会受同源策略限制。如果PDF文件在另一个域名，需要后端在响应头里配置跨域许可，或者自己先通过本地接口把PDF下载成Blob，再用URL.createObjectURL生成临时地址传给viewer。我常用的做法是：
fetch(pdfUrl) .then(res => res.blob()) .then(blob => { const url = URL.createObjectURL(blob); const viewerUrl = '/pdfjs/web/viewer.html?file=' + encodeURIComponent(url); window.open(viewerUrl); });这种方法还能顺便带上请求头，适合需要Token认证的下载接口。
2.3 自己写一个精简的 PDF 渲染页面
如果不想引入整个viewer，只想在页面里渲染第一页作为缩略图，或者定制特制的预览效果，可以自己写。依赖两个JS文件，核心代码如下：
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>PDF.js 2.2.228 渲染示例</title> </head> <body> <canvas id="pdfCanvas"></canvas> <script src="/pdfjs/pdf.min.js"></script> <script> var url = '/pdfs/sample.pdf'; // 关键：告诉PDF.js worker文件的位置 pdfjsLib.GlobalWorkerOptions.workerSrc = '/pdfjs/pdf.worker.min.js'; pdfjsLib.getDocument(url).promise.then(function(pdf) { return pdf.getPage(1); }).then(function(page) { var scale = 1.5; var viewport = page.getViewport({ scale: scale }); var canvas = document.getElementById('pdfCanvas'); var ctx = canvas.getContext('2d'); canvas.width = viewport.width; canvas.height = viewport.height; return page.render({ canvasContext: ctx, viewport: viewport }).promise; }); </script> </body> </html>在2.2.228版本中，getViewport要传对象形式，不能像老版本那样直接传数字page.getViewport(scale)，不然会报参数类型错误。还有，渲染出来的Canvas有时看起来模糊，可以把scale设置成window.devicePixelRatio的倍数：
var scale = 1.5 * (window.devicePixelRatio || 1);这样在高DPI屏幕下会更清晰。如果是做多页预览，建议一个页面一个Canvas，不要把所有页画在同一个Canvas里反复清空重绘，性能反而不如直接堆节点。
3. 在 Vue/uni-app 项目里集成
3.1 Vue2 项目引入 pdfjs-dist
Vue项目更常见的做法是直接用npm包。安装指定版本：
npm install pdfjs-dist@2.2.228然后在组件里引入：
import pdfjsLib from 'pdfjs-dist'; import workerSrc from 'pdfjs-dist/build/pdf.worker.min.js'; pdfjsLib.GlobalWorkerOptions.workerSrc = workerSrc;但这里有个坑：webpack3处理pdfjs-dist的ES模块时容易报错，尤其是Cannot read property 'compile' of undefined之类的问题。解决办法是在webpack.base.conf.js里把pdfjs-dist加入externals，然后通过script标签直接引用pdf.min.js，让全局变量pdfjsLib来接管：
<!-- 在 index.html 中直接引入本地文件，而不是npm打包 --> <script src="/static/pdfjs/pdf.min.js"></script>然后在组件中用window.pdfjsLib。这种方式对我来说最稳，可以避开webpack所有的兼容性坑。如果你不想用全局变量，也可以试试import * as pdfjsLib from 'pdfjs-dist'，但在老工程里成功概率不高。
3.2 uni-app 中使用 web-view 加载 viewer
uni-app里没法直接跑复杂的Canvas渲染，最靠谱的方式是使用web-view组件，把官方viewer当成一个网页嵌入。操作步骤如下：
- 把
pdfjs-2.2.228-dist整个文件夹放到static/pdfjs目录下。 - 在页面中写：
<web-view :src="viewerUrl"></web-view>- 在script里拼接地址：
export default { data() { return { viewerUrl: '' } }, onLoad(params) { let file = encodeURIComponent('/static/pdfs/' + params.fileName + '.pdf'); // 注意：这个地址是相对于App的本地地址，不同平台解析规则不一样 this.viewerUrl = '/static/pdfjs/web/viewer.html?file=' + file; } }这里最容易翻车的是路径。在App开发环境下，web-view访问的本地路径可能和页面相对路径不一致，有时候需要写绝对路径，有时候又需要前面加baseUrl。我的经验是：先在H5端把完整路径跑通，再打包到App里进行真机调试，用plus.io或者uni.getEnv去动态获取根路径会稳妥些。另外，如果PDF是网络地址，一定要确认网络地址能被App访问到，同时后端允许跨域，否则viewer会一直白屏。
3.3 动态传入PDF地址的注意事项
不管是Vue还是uni-app，通过URL参数传PDF地址都有长度限制，如果PDF地址很长，或者本身又要带Token、签名等查询参数，很容易超出浏览器URL上限。更稳妥的做法是后端给一个短码，前端拿到短码后再调接口获取真正的下载地址。或者直接用postMessage把地址消息传给viewer内部，在viewer里监听消息然后加载。不过这样要改viewer源码，维护成本高，我个人更推荐用file参数传一个后端生成的一次性地址，简单可靠。
4. 常见问题排查与避坑清单
4.1 Worker相关报错
很多朋友刚接触PDF.js时会遇到：
Failed to fetch dynamically imported module: ... pdf.worker.min.js或者控制台提示“The API version X does not match the Worker version Y”。这通常是因为主文件和worker文件版本不一致。比如主文件是2.2.228，worker却是另一个版本的。解决办法：确保pdf.min.js和pdf.worker.min.js来自同一个版本目录，并且GlobalWorkerOptions.workerSrc路径正确。如果用了pdfjs-dist的npm包，还可以这样加载：
import pdfjsLib from 'pdfjs-dist'; pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.2.228/pdf.worker.min.js';但我不太建议生产环境用公共CDN，万一CDN挂了，预览功能就废了。应该把worker文件放到自己的静态目录，再通过相对路径引用。如果是Vue项目，放在public目录下，直接/pdf.worker.min.js即可。
4.2 文件路径、跨域与中文乱码
PDF.js本身对跨域要求比较严。用file://协议直接打开本地HTML时，经常报file origin does not match viewer's，这时候必须起一个本地服务器，比如npx serve，或者python -m http.server 8080。跨域请求PDF文件时，如果后端没开Access-Control-Allow-Origin，可以通过代理转发。比如开发环境下用webpack的proxy，把/pdf-api请求代理到PDF实际所在的服务器。
中文内容显示成乱码或者方块，一般是缺了cMaps。2.2.228版本的自带包里有cmaps目录，初始化时要指定：
var loadingTask = pdfjsLib.getDocument({ url: url, cMapUrl: '/pdfjs/cmaps/', cMapPacked: true });这样中文字体才能正确映射。我踩过一次坑是路径忘加了末尾的斜杠，结果请求地址变成了/cmapsxxx.bcmap，一直404。
4.3 npm/Webpack环境兼容性错误
集成过程中如果执行npm install或启动开发环境，容易遇到两个经典报错。
第一个是：
could not retrieve https://nodejs.org/dist/latest/shasums256.txt: get "https://nodejs.org/dist/latest/shasums256.txt": ...这多半是网络问题，尤其是某些代理环境或公司内网访问不了nodejs.org。解决方法是切换npm镜像源，比如使用国内镜像：
npm config set registry https://registry.npmmirror.com再重新安装依赖。如果项目里有依赖需要下载node头文件（比如node-sass），还可以设置node_mirror：
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass/第二个报错是：
npm run start Cannot find module 'ajv/dist/compile/codegen'这是因为项目里某些依赖（如webpack、sass-loader）对ajv版本有要求，而node_modules里的ajv版本不兼容。一般把node_modules和package-lock.json删掉，重新npm install可以解决。如果重装后还报，就手动安装指定版本的ajv：
npm install ajv@6.12.6 --save-dev老项目很多依赖停留在旧版本，ajv@6比较稳妥。这种环境兼容性问题，说实话和PDF.js本身没关系，但如果在集成时正好碰到，很容易误以为是PDF.js的问题，所以一并列出来。
4.4 RAR包解压与完整性校验
最后再聊聊这个资源包本身。下载pdfjs-2.2.228-dist.rar后，如果解压失败，可能是压缩包下载不完整。rar和zip不同，rar损坏后很难部分解压出来，建议下载完先比对文件大小。如果来源是一个带密码的压缩包，别去试所谓“rar password cracker”破解，风险太高，老老实实找原作者要密码。解压后最好检查一下目录里有没有可疑的.exe或者.bat文件，正常dist包只会有js、css、html、mcmap等资源，出现其他东西要立刻删除。
还有一种情况，解压出来的文件名带中文或者特殊空格，放到服务器上导致URL访问不到。我一般会把整个目录重命名为纯英文，比如pdfjs，避免后面各种编码问题。
5. 几点实战心得
在我自己动手用过2.2.228之后，最大的感受是这个版本对“老项目”非常友好。它不像新版那样强制要求现代浏览器和模块语法，只要能撑起一个<canvas>和Web Worker就能跑。如果你的项目还在用jQuery、原生JS，或者Vue2旧版本构建链，这个版本基本可以无缝接入。
如果你问我现在新项目该不该用这个版本，我建议：新项目还是去GitHub上看看最新Release版，因为新版在渲染性能、PDF规范支持上改进很大。但如果你手头是维护了三四年的老系统，网上又恰好能找到pdfjs-2.2.228-dist.rar这种现成包，那就先用它把功能顶起来，后面要升级再单独做技术方案。
最后再分享一个小技巧：PDF.js渲染大文件时，尤其上百页的文档，不要一上来就渲染所有页，可以先用pdf.getPage(1)渲染封面，等用户点击下一页时再渲染对应页。同时用PDFPageProxy.cleanup()及时释放VRAM资源，不然长时间翻页后内存占用会一直往上涨，移动端尤其明显。这个细节就是纯经验了，官方文档里提得很少，但实战里特别管用。
本文还有配套的精品资源，点击获取
