简介：这是一份PDF.js浏览器端渲染库资源包，面向需要在网页中嵌入PDF预览与交互功能的Web前端开发者。PDF.js由Mozilla团队开源维护，可在HTML5浏览器上无需插件直接解析并渲染PDF文档，适用于在线文档系统、电子签章平台及各类内网办公环境。压缩包共收录200个文件，总计45.04MB，核心包含pdf.js、pdf.worker.js等JavaScript库文件，配合viewer.css样式、viewer.js界面逻辑以及大量png/svg图标与光标文件，组成一个可直接运行的PDF阅读器示例；另有105个properties文件，可用于界面多语言与本地化配置。资源附带index.html入口和示例PDF，开发者可通过本地部署快速预览渲染效果。已有2876人学习下载。整体覆盖搜索、书签、缩略图、连续滚动与打印等常用阅读模式，开发者既能借此熟悉API调用与渲染流程，也可依据自身需求替换界面样式、扩展自定义工具栏，从而将PDF展示能力平稳集成到内网或在线Web项目中。
1. 为什么pdf.js会和“文件下载”搅在一起
1.1 先搞清楚pdf.js到底解决什么问题——在线预览的底层逻辑
pdf.js是Mozilla团队维护的一个开源PDF解析与渲染库，核心能力是在浏览器端直接解析PDF二进制内容，并用Canvas把每一页绘制出来。说白了，它就是让网页不用装Adobe插件、不用跳转新窗口，也能在页面上“摊开”一份PDF。
但因为它是纯前端解析，很多开发者想当然地认为“那下载也应该归它管”。这是最大的误解。pdf.js的主要工作是渲染，它只负责“把PDF画出来”，至于“把文件存到用户电脑里”，那是浏览器下载机制的事。网上的代码片段又特别喜欢把这两件事黏在一起写，一会儿拿getData()取原始字节，一会儿拿render()生成Canvas，新手一抄就懵，项目一上线就出幺蛾子。
1.2 真正让开发者头疼的不是预览，而是下载——三个典型场景
把热搜词过一遍，“vue a标签直接下载pdf文件，不预览”、“prototype下载文件”、“net webapi 下载文件”、“vue ipad safari下载的pdf文件会变成预览”——关键词集中在“不预览”、“变成预览”、“保持文件名不变”上。这说明大家在实际开发中卡住的，根本不是怎么把PDF摆到页面上，而是怎么把文件“干净利落地存下来”。
总结下来就三种典型场景：
- 用户点“下载”按钮，期望直接弹下载框，但浏览器偏偏把PDF打开了——换谁都烦。
- 后端返回的是接口流，前端拿不到真正的文件名，或者文件名是中文，下载下来变乱码。
- iPad、iPhone上的Safari压根不认
download属性，不管你怎么设置，它就是要预览。
这三个问题，用pdf.js都能绕过去，但绕法不一样，得先分清楚需求。
1.3 一个容易忽略的关键点：pdf.js本身不管下载
这里先把话说透。pdf.js提供的下载相关能力，严格来讲只有一个——PDFDocumentProxy.getData()，返回Promise，resolve出来的是PDF原始二进制数据的Uint8Array。而它真正的核心是getPage()、render()、getAnnotations()这一整套渲染管线。很多人的困惑来自于把这两个东西混在一起。
如果你需要的是“原样下载服务器上的那份PDF”，用getData()拿到原始字节，再走Blob下载流程就行。如果你需要的是“只下载某一页”，或者“下载带水印、带标注的当前视图”，那必须先render()成Canvas，再转成图片或重新拼装PDF。这是两条完全不同的路线，后面会分别演示。
2. 项目整体设计：从“能预览”到“能下载”的完整思路
2.1 技术选型：Vue 3 + pdf.js v4 的核心方案
先说这套方案的基础栈。我这个项目用的是Vue 3 + Vite，pdf.js走的npm包方式，版本是v4.x。之所以特别强调版本，是因为pdf.js在v4里做了比较大的API整理，很多老教程里import PDFJS from 'pdfjs-dist'的写法已经失效了，改成按需引入，worker的加载方式也变了。
Vite这边有个加分项，pdf.js官方提供了?url后缀导入方式，可以直接拿到worker文件的URL，不用手动复制到public目录。这个在v3/v4里都适用，实测比老式pdfjsLib.GlobalWorkerOptions.workerSrc配绝对路径更省心。
2.2 场景一：用户想下载“原始PDF文件”，怎么绕过浏览器预览
回到最核心的问题：为什么<a href="file.pdf" download>不灵？因为这个download属性只是给浏览器的“建议”，不是“命令”。浏览器在两种情况下会无视它：一是跨域资源（比如文件在OSS上），二是PDF这种浏览器自己能打开的文件类型，Chrome和Edge极大概率直接走预览。
绕过的思路就是“不直接给浏览器看文件”，而是自己把文件取回来，包装成Blob，创建一个临时URL，再触发下载。这样浏览器看到的是一段由前端生成的二进制数据，找不到原始地址，自然没机会预览。
用pdf.js的最大好处是，这个Blob可以直接从getData()里拿，相当于文件已经在内存里被完整解析了一遍，你拿到的就是浏览器认可的、干净的数据。
2.3 场景二：用户只想下载“当前页或当前视图”，canvas转图的思路
还有一类需求是“下载当前这一页”，尤其合同、发票、审批单这类场景特别常见。页面预览完整份PDF后，用户只需要第一页或签字那一页，这时不应该下载整个文件，而是把目标页用render()画到Canvas上，然后canvas.toDataURL('image/png')导出图片。
更进阶一点，还可以用canvas.toBlob()拿到二进制后，配合jsPDF库把多张图片重新拼成一个新的PDF文件。这就是“按需重排”的思路，实际项目里用来做电子签章、水印覆盖、只下载指定页，都很实用。
2.4 需求要分清：下载原始文件 vs 下载渲染图片，决定两条完全不同的技术路线
这一段是写给刚入坑的同学的。很多人看到“pdf.js文件下载”就在网上找一个代码片段抄，结果发现别人的代码下载下来是图片，自己要的却是原PDF，或者反过来。原因就是没搞清楚底层逻辑。
| 需求 | 核心技术 | 产出物 | 适用场景 |
|---|---|---|---|
| 原样下载服务器文件 | PDFDocumentProxy.getData() | 原始PDF的Uint8Array | 合同存档、文件下载按钮 |
| 下载某几页或全部页 | getPage()+render() | Canvas图片 或 重新拼装的PDF | 发票预览、电子签章、带水印导出 |
| 下载当前视图（含注释） | render()+ 注释层手动绘制 | Canvas图片 | 批注截图、客服沟通 |
分清这个，后面写代码就不会乱。
3. 核心细节与实操要点
3.1 引入pdf.js的方式：npm、CDN、离线包分别怎么选
npm方式是最干净、最适合前端工程化项目的。Vite下直接npm install pdfjs-dist，然后按需引入。CDN方式适合纯HTML页面演示或者低代码平台，但要注意跨域和版本锁定，不要用latest这种浮动版本。离线包方式适合内网部署或者对加载性能有极致要求的场景，把整个pdfjs-dist里用到的文件打到本地。
我的建议是：只要项目是Webpack/Vite工程，一律用npm方式。因为tree-shaking和版本管理都方便，v4版本官方已经做了ES Module拆包，按需加载的效果比把CDN脚本塞进index.html要好很多。
3.2 worker配置，不配置必踩坑
worker模块是pdf.js中负责解析PDF二进制、执行渲染指令的“后台线程”。没有它，主线程就会被迫做所有解析工作，页面直接卡死，而且控制台会报“Setting up fake worker failed”之类的错误。
v4版本的配置方式是：
import * as pdfjsLib from 'pdfjs-dist'; import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url'; pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl;这里?url是Vite提供的导入方式，Webpack则可以用new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url)。注意，老版本用的pdf.worker.js在v4里改名成了pdf.worker.min.mjs，网上很多教程还是老的，抄的时候看清楚版本号。
3.3 下载文件名乱码问题：Content-Disposition与encodeURIComponent
文件名乱码是高频问题。一种情况是后端接口返回的响应头里带Content-Disposition: attachment; filename="xxx.pdf"，但前端直接用response.headers['content-disposition']去解析，遇到中文会被编码成filename*=UTF-8''%E4%BC%9A%E8%AE%AE.pdf这种格式，不处理就是乱码。
另一种情况是前端自己拼文件名，比如从URL里截取，遇到中文字符没有转义，或者下划线、空格没处理。这里建议统一用decodeURIComponent和encodeURIComponent组合处理，实际项目中我习惯做一个小工具函数，把filename和filename*两个字段都解析出来，优先取filename*的UTF-8解码值。
3.4 iOS Safari下载PDF变预览的坑
这是移动端最坑的问题，热搜词里“vue ipad safari下载的pdf文件会变成预览”指的就是它。苹果的Safari在iOS 13之后对download属性做了一定支持，但对PDF这种MIME类型仍然有“特殊感情”，即使你在<a>标签上写了download，它也会优先调用内置PDF查看器。
破解思路是用Blob把文件“洗一遍”。因为Blob URL是blob:https://...这种形式，不是原始文件地址，Safari失去对“源文件”的追踪，才会老实走下载逻辑。实测在iOS Safari上，a.download配合blob:前缀的URL，对非PDF文件基本有效；对PDF文件，iOS 14以上版本在部分设备上仍然预览，但如果加上target="_blank"和rel="noopener"的组合，出现预览的概率会显著降低。
4. 完整实操代码与逐步讲解
4.1 环境准备
先列一下我这边的环境版本，方便对照：
- Node.js 18+
- Vite 5.x
- vue 3.4.x
- pdfjs-dist 4.3.x
安装命令：
npm install pdfjs-dist不需要额外装别的。注意不要在index.html里手动引CDN，不然和npm包会重复加载，容易出现版本冲突。
4.2 初始化pdf.js（含版本差异说明）
创建一个pdfUtils.js文件，统一管理初始化逻辑：
import * as pdfjsLib from 'pdfjs-dist'; import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url'; pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl; export default pdfjsLib;这里有两个细节值得说。第一，pdfjs-dist在v4里同时提供legacy构建，如果你的项目需要兼容旧浏览器（比如没启用ES2020特性的场景），要把引入路径改成pdfjs-dist/legacy/build/pdf.mjs。第二，?url导入在Vite里会返回构建后的资源路径，开发环境和生产环境都能正确解析，不需要额外配置public目录。
4.3 实现“不预览直接下载原始PDF”
这是核心功能，完整逻辑放在downloadOriginalPdf函数里：
import pdfjsLib from './pdfUtils'; export async function downloadOriginalPdf(pdfUrl, fileName = 'download.pdf') { // 第一步：把远程PDF加载成pdfjs文档对象 const loadingTask = pdfjsLib.getDocument(pdfUrl); const pdfDoc = await loadingTask.promise; // 第二步：从文档对象里拿原始二进制数据 const data = await pdfDoc.getData(); // 第三步：包装成Blob（注意MIME类型必须是application/pdf） const blob = new Blob([data], { type: 'application/pdf' }); // 第四步：创建blob URL并触发下载 const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = fileName; document.body.appendChild(link); link.click(); document.body.removeChild(link); // 第五步：释放内存 URL.revokeObjectURL(url); }第五步的revokeObjectURL很重要，很多人漏掉，下载一多页面就卡。建议在click()之后用setTimeout延迟释放，防止某些浏览器还没读完全部字节就失效。
如果是跨域文件，getDocument()可能会被CORS拦截。解决方法是让后端给响应头加Access-Control-Allow-Origin，或者走代理。前端层面没有好的绕过方案，别在这上面浪费时间。
4.4 实现“canvas转图片下载”与分页处理
这个稍微复杂一点，但思路清晰：
export async function downloadPageAsImage(pdfUrl, pageNum, fileName = 'page.png') { const pdfDoc = await pdfjsLib.getDocument(pdfUrl).promise; const page = await pdfDoc.getPage(pageNum); // 设置视口（scale按需调整，2倍图更清晰） const viewport = page.getViewport({ scale: 2 }); const canvas = document.createElement('canvas'); canvas.width = viewport.width; canvas.height = viewport.height; const context = canvas.getContext('2d'); // 渲染到canvas await page.render({ canvasContext: context, viewport }).promise; // canvas转Blob再下载 const blob = await new Promise((resolve) => { canvas.toBlob(resolve, 'image/png'); }); const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = fileName; document.body.appendChild(link); link.click(); document.body.removeChild(link); URL.revokeObjectURL(url); }这个函数的实用点在于可以循环调用，拼出“下载全部页码为图片”的功能。但要注意，一次循环把所有页都渲染出来很占内存，我建议用“渲染一页→下载一页→释放一页”的流式思路，否则100页的PDF分分钟让用户手机崩掉。
4.5 实际测试情况记录
我在本地分别测了三种场景：
- 部署在Nginx上的同源PDF，用
downloadOriginalPdf下载，Chrome和Edge直接弹下载框，没有预览。 - 部署在OSS上的跨域PDF，接口加了CORS后，
getDocument()成功，getData()拿到数据正常。 - iPad Safari（iOS 16.5）点下载按钮，原PDF文件通过Blob方案可以下到“文件”App；但部分iOS版本如果画面上先预览了PDF再点下载，偶尔还是会被内置阅读器截胡，处理办法是把下载按钮和预览区域分开渲染，不要放在同一个View层级里。
我在实际项目里还发现，如果PDF文件特别大（50MB以上），getDocument()的加载进度会很明显，用户看不到反馈会以为卡死了。建议自己包一层加载百分比UI，监听loadingTask.onProgress。
5. 常见问题与排查技巧实录
5.1 worker加载404或跨域
现象：控制台报Failed to fetch dynamic import或Setting up fake worker failed。
原因：worker URL解析不对，或CDN路径跨域。
排查步骤：先打印GlobalWorkerOptions.workerSrc确认URL对不对；再在浏览器直接访问这个URL，看能不能取到文件；最后检查Vite/Webpack配置有没有拦截.mjs文件的请求。最常见的原因是版本升级后没改路径，v4的worker文件是.mjs不是.js。
5.2 大文件渲染卡顿与内存泄漏
现象：页面越来越卡，切页时掉帧，最后浏览器标签页崩溃。
原因：Canvas没有复用，每次渲染都新建一个；或者渲染旧页面时新页面就开始渲染，两批渲染任务抢占CPU。
解决：复用同一个Canvas实例，切换页面时先调用renderTask.cancel()取消当前渲染任务，再执行新的渲染。渲染完的Canvas如果不用了，主动把width和height归零释放GPU内存。
5.3 Safari下载PDF变成预览
现象：iPhone/iPad上点下载没反应，或者跳出了PDF阅读器。
分析：前面说过，这是Safari对application/pdf的强制行为。Blob方案能解决大部分情况，但不能100%保证所有iOS版本一致。
兜底方案：让用户长按图片或Canvas渲染结果，手动存储图像；或者提供“复制下载链接”功能，让用户可以去Safari地址栏手动操作。不优雅，但在某些老设备上是唯一的办法。
5.4 文件名中文乱码
现象：下载下来的文件名变成一堆%E4%BC%9A%E8%AE%AE.pdf，或者干脆是“download.pdf”。
原因：响应头里filename*没解析，或者前端传文件名时没编码。
推荐处理：写一个函数，优先匹配filename*=UTF-8''...并解码；没有的话再取filename；两者都没有才用前端默认文件名。这个函数建议提成公共方法，因为前后端联调时，谁也不能保证后端的响应头一定规范。
5.5 下载按钮点击无反应或弹窗被拦截
现象：用户反映“点了没反应”，但控制台没有报错。
原因：要么是下载URL创建失败，要么是浏览器的弹窗拦截机制把link.click()当成了非用户操作。
解决：确保link.click()发生在用户点击事件的同步调用栈里，不要放在Promise的深层回调中，更不要放在setTimeout里。如果必须要异步获取数据，就先用一个遮罩层让用户再点一次“确认下载”，这既能体面地绕过拦截，又能告诉用户“下载已开始”。
最后再说一个我个人的习惯。写pdf.js下载功能的时候，把“预览”和“下载”这两条链路彻底拆开，各自维护一个工具函数文件，不要混在一起写。预览用render()，下载用getData()或者toBlob()，中间不穿插怪异逻辑，排查问题的时候能省一半时间。这个项目后续如果要扩展，比如加“下载全部页为图片”或“生成带水印的PDF”，也只需要在对应的工具函数里做增量开发，不会牵扯到预览代码。
本文还有配套的精品资源，点击获取
