简介PDF.js 开源库的完整项目包面向需要在浏览器中实现 PDF 文档免插件渲染的网页前端开发者解决嵌入 PDF 阅读功能的集成与部署问题。资源包含 200 个文件涵盖核心脚本、样式文件、配置属性与大量图标资源压缩包约 45MB可支撑核心库、工作线程、查看器逻辑等模块协同工作覆盖从基础渲染到高级交互的完整链路。已有 2876 人学习下载适合具备一定脚本语言基础、希望深入理解 PDF.js 接口与渲染原理的开发者无论是基础入门还是二次开发都能从中获得有效参考。包内提供可直接运行的示例页面与配套图标便于本地运行调试可对照学习 PDF 加载、绘制、事件监听及自定义工具栏。同时支持搜索、缩略图、连续阅读等高级功能为在现有项目中二次开发提供清晰可扩展的代码基础便于按需调整界面与交互逻辑。 如果只是把PDF当做一个静态资源丢给用户下载那确实不需要费劲研究什么。但实际项目里需求往往是在网页里先预览PDF再提供一个下载按钮或者后端接口返回的是文件流浏览器却直接给渲染成预览页了再或者用户点了下载iPad上的Safari非要把PDF打开成预览就是不弹下载。这些场景凑到一起就会变成一个绕不开的技术点如何用pdf.js这个库把PDF文件从能看变成能下、下得对、下得稳。这篇东西就是围绕pdf.js文件下载这个主题写的内容包含pdf.js的基本引入方式、利用它获取文件数据、再配合Blob机制实现可控下载的核心代码以及我在实际项目中踩过的那些下载变预览下载文件名乱码iOS Safari不弹下载之类的坑还有对应的排查思路和解决方案。适合正在做Web端PDF模块、尤其是用Vue或原生JS开发并遇到下载问题的前端同学参考。1. 为什么下载PDF在网页里会翻车浏览器默认行为的三个陷阱先聊一个反直觉的事实在网页里把PDF下载这件事做好比很多人想象中要麻烦得多。表面上看一个a hrefxxx.pdf download标签就能搞定但浏览器对PDF的处理有一套自己的逻辑这套逻辑经常和业务需求对着干。第一个陷阱是浏览器的内置PDF预览器。桌面端Chrome、Edge、Firefox都把PDF直接渲染在了标签页里用户点开链接看到的是预览不是下载。如果产品经理想要的是用户一点按钮就直接弹出保存窗口那默认行为就完全不满足需求。你需要在代码层面强制浏览器走下载而不是预览。第二个陷阱是download属性并不总是生效。download属性看起来是标准方案但它有一个关键限制跨域资源下浏览器会忽略这个属性。现在很多项目的PDF文件都存在OSS、CDN或独立文件服务器上由前端直接拼URL访问这种情况下你写一百遍download也没用浏览器照样给你打开预览。第三个陷阱是移动端Safari尤其是iPad。iOS Safari对download属性、对Blob URL的支持都有自己的一套行为逻辑经常出现安卓上能正常下载iPhone一打开就变预览的诡异现象。如果项目有一定规模的移动端用户这个坑基本绕不开。所以结论很明确要靠a标签加一个URL搞定PDF下载只适用于文件同源且浏览器行为恰好符合预期的理想场景。一旦遇到跨域、移动端、需要自定义文件名、需要统计下载进度这些真实需求就必须把PDF文件的数据拿回到前端手里自己去控制下载流程——而拿数据、解析数据这件事正是pdf.js的看家本领。2. pdf.js的两种加载方式和Worker配置下载功能的地基pdf.js是Mozilla家出的开源PDF解析引擎底层用Web Worker解析PDF二进制数据再通过Canvas把每一页渲染出来。很多人对它的印象是一个PDF预览组件实际上它拆开来看是两层能力第一层是把PDF文件数据拉回来并解析成文档对象第二层才是把页面渲染成Canvas。下载功能真正依赖的是第一层能力。2.1 引入pdf.js的正确姿势如果是传统页面直接用CDN引入是最快的script srchttps://unpkg.com/pdfjs-dist3.11.174/build/pdf.min.js/script如果项目是Vue或React这类工程化项目建议走npm安装npm install pdfjs-dist3.11.174这里有第一个需要注意的细节pdf.js的版本差异比较大2.x和3.x在API上有明显的区别网上很多教程用的是老版本API直接抄到新版项目里会报错。我用的版本是3.x下面所有代码也都按3.x写。还需要重点提一下Worker的配置。pdf.js的解析工作默认在Worker线程里跑不配置Worker的话库会退化到主线程执行解析同时会在控制台打出一行警告大概意思就是你忘了配worker了大文件预览时页面会明显卡顿。下载场景虽然主要是拿数据但如果你的功能是先预览再下载那Worker配置就是一个必须做的优化。CDN方式下这样配pdfjsLib.GlobalWorkerOptions.workerSrc https://unpkg.com/pdfjs-dist3.11.174/build/pdf.worker.min.js;如果是Webpack或Vite工程可以这样import * as pdfjsLib from pdfjs-dist; pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.js, import.meta.url ).toString();2.2 getDocument的两种传参方式pdf.js加载PDF的核心方法是getDocument它能接受一个URL字符串也能直接接受二进制数据。这两种方式对应着下载功能的两条实现路径。// 方式一直接传URL适合同源或后端允许跨域的PDF地址 const loadingTask pdfjsLib.getDocument(pdfUrl); // 方式二传ArrayBuffer适合已经有文件数据的场景 const loadingTask pdfjsLib.getDocument({ data: arrayBuffer });第一种方式最省事但受跨域限制第二种方式更灵活只要你能用fetch把文件流拿到手后面想怎么处理都行。这个区分很重要后面讲下载实现方案时会反复用到。3. 核心方案拆解用pdf.js和Blob实现可控的PDF下载现在进入正题。先明确一下我最终采用的下载方案它不是单纯靠pdf.js的某一个API而是把pdf.js的数据能力、fetch的流获取能力、Blob的对象URL机制组合起来形成一条可控的下载链路。3.1 整体思路预览与下载分离我的做法是预览走pdf.js渲染下载走fetch取流。两个功能看着都是围绕同一个PDF但数据链路分开职责清晰出了问题也好排查。下载的完整链路是这样的根据PDF的地址或者后端接口返回的文件流使用fetch请求文件数据将返回的Response转换为Blob对象通过URL.createObjectURL(blob)生成一个临时的对象URL创建a标签设置href为对象URLdownload属性为自定义文件名触发点击完成下载下载后立即释放对象URL避免内存泄漏这里把pdf.js放进来原因是很多业务场景中PDF地址不是简单的前端写死URL而是需要带上token认证、或者需要从pdf.js已加载的文档中获取元数据来决定文件名、又或者后端返回的是加密的二进制流需要先让pdf.js能解析成功才说明数据没问题。这种情况下直接给a标签喂URL是走不通的你得先把数据拿回来、确认能解析、再生成下载。3.2 核心代码示例下面这段代码是我在Vue项目里实际用过的精简版本核心逻辑可以平移到任何框架async function downloadPdf(pdfUrl, fileName) { // 第一步把PDF文件流拉回来 const response await fetch(pdfUrl); if (!response.ok) { throw new Error(PDF文件请求失败HTTP状态码 response.status); } // 第二步转成Blob对象 const blob await response.blob(); // 第三步生成临时对象URL const blobUrl URL.createObjectURL(blob); // 第四步创建a标签并模拟点击 const link document.createElement(a); link.href blobUrl; link.download fileName || document.pdf; document.body.appendChild(link); link.click(); document.body.removeChild(link); // 第五步释放对象URL URL.revokeObjectURL(blobUrl); }这段代码看起来简单但里面有三个细节容易被忽略。第一个细节link必须添加到body里再触发点击不添加直接click()在某些浏览器版本里不生效这是有实际教训的。第二个细节URL.revokeObjectURL(blobUrl)要放在click()之后但最好不要在同步代码里立刻执行。有些浏览器在点击后还没来得及读取Blob数据就撤销了URL会导致下载失败。稳妥的做法是加一个setTimeout延迟释放setTimeout(() { URL.revokeObjectURL(blobUrl); }, 1000);第三个细节从后端接口获取文件时如果项目里封装了axios注意设置responseType: blob。用axios默认的JSON类型去接收二进制流数据会被转成奇怪的字符串下载下来的文件打不开。这是一个非常高频的翻车点。3.3 如果一定要用pdf.js加载后的数据来下载有些场景下文件地址不能直接fetch比如做了权限控制、只能通过pdf.js已经建立的会话来获取数据这种场景不多但确实存在。这时可以利用pdf.js的getDocument拿到文档后通过loadingTask的原始数据属性来拿数据不过说实话这个操作在3.x版本里比较绕我的建议是直接从网络层解决要么后端加一个下载接口要么在fetch请求里带上同样的认证头。硬要从pdf.js内部取数据代码会变得不直观维护成本也高没必要。4. 踩坑实录从下载变预览到iOS Safari不下载的完整排查链这个章节我想用问题现象 排查过程 根因 解决的方式来写因为下载PDF的坑基本套路都差不多但你得知道怎么一步步定位。4.1 问题一点击下载按钮浏览器直接打开了PDF预览现象按钮、a标签、URL全部正常点击后桌面Chrome直接开了一个新标签页把PDF渲染出来下载根本没触发。排查过程先检查href指向的PDF地址和当前页面是不是同源。如果是同源且写法是a hreffile.pdf downloadxxx.pdf理论上Chrome应该直接下载。试了以后发现依然预览于是打开控制台看网络面板发现请求的响应头里有一个关键字段Content-Disposition: inline; filenamefile.pdf。当后端或静态服务器返回inline时浏览器就会认为这个资源应该被内联展示download属性也会被它压制。解决前端做不了什么来改变响应头里的Content-Disposition所以走fetch拿Blob的时候其实是在绕过这个响应头对浏览器行为的控制——因为fetch拿到的只是数据展示或下载的决策权完全在前端手里。4.2 问题二下载文件名变成一串乱码或者直接被忽略现象文件成功下载了但保存下来的文件名不是预期的中文名而是一串URL编码或者直接被浏览器命名成了下载。排查过程用fetch拿Blob再download指定文件名时一般不会出现这个问题因为这个方案的download属性是标准生效的。但如果代码里漏了download属性浏览器就会根据响应头里的Content-Disposition去取名后端如果没设置filename*中文名大概率乱码。另一种情况是后端虽然返回了Content-Disposition: attachment但用的文件名编码格式不对没处理filename*UTF-8这种形式。解决前端方案里强制给a标签设置download属性文件名自己拼。注意文件名如果包含中文不用手动做URL编码直接赋值就可以。如果要做得更严谨可以先从响应头里解析Content-Disposition拿到后端推荐的filename*解析不出来再用自己自定义的名字。4.3 问题三iPad/iPhone上的Safari打开下载按钮后还是预览现象同样的代码安卓手机和桌面浏览器都正常iPhone和iPad点下载按钮后PDF直接在Safari里打开成预览页顶部没有下载选项或者说藏得很深用户根本找不到保存入口。排查过程这是移动端Safari的经典行为差异。iOS Safari对a标签的download属性支持一直不完整Blob URL的下载行为在iOS 13以前基本是废弃状态iOS 13以后虽然部分支持但在iPad上仍然不稳定尤其是PDF这种Safari有能力原生预览的文件类型系统就是优先做预览。解决我在实际项目中最终采用的是两步兼容方案。第一步页面里同时放一个提示如无法下载请长按链接选择下载链接文件。第二步对iOS设备做UA判断降级使用window.open打开Blob URL让Safari自己处理预览用户通过系统分享按钮保存文件。虽然体验不如一键下载那么顺畅但至少用户有路可走。这里贴一下兼容逻辑的核心片段const isIOS /iPad|iPhone|iPod/.test(navigator.userAgent) || (navigator.platform MacIntel navigator.maxTouchPoints 1); if (isIOS) { // iOS Safari降级方案打开预览让用户通过系统分享保存 window.open(blobUrl, _blank); } else { // 正常下载逻辑 const link document.createElement(a); link.href blobUrl; link.download fileName; document.body.appendChild(link); link.click(); document.body.removeChild(link); }4.4 问题四大文件下载把浏览器内存吃爆了现象一个几十MB甚至上百MB的PDF点下载后页面卡死或者下载下来的文件损坏无法打开。排查过程response.blob()会把整个文件加载进内存加上pdf.js预览时也要占用一份内存两者叠加后大文件场景下必然吃紧。如果文件有几百MB前端做全量下载本来就不合理。解决两个方向。一是大文件不建议前端走blob链路让后端直接返回一个带Content-Disposition: attachment的文件地址用最朴素的方式下载二是如果一定要前端处理至少加一个文件大小判断超过某个阈值比如100MB就提示用户走后端直链下载。另外下载完成后务必释放Blob URL这个前面已经强调过了。5. 从能下载到下载体验好进度提示、多文件下载和状态联动下载功能做到能跑只是第一步实际集成时还有不少体验层面的细节。这里整理几个我做过且值得做的增强点。5.1 下载进度提示fetch返回的Response对象带有一个body它是一个ReadableStream可以监听数据接收的进度。把Blob的组装过程改成流式读取就能算百分比async function downloadPdfWithProgress(pdfUrl, fileName, onProgress) { const response await fetch(pdfUrl); const contentLength response.headers.get(Content-Length) || 0; const reader response.body.getReader(); let receivedLength 0; const chunks []; while (true) { const { done, value } await reader.read(); if (done) break; chunks.push(value); receivedLength value.length; if (contentLength onProgress) { onProgress(Math.round((receivedLength / contentLength) * 100)); } } const blob new Blob(chunks); // 后续的下载逻辑同上 }需要注意这个方案需要后端接口返回Content-Length响应头如果后端是分块传输chunked拿不到总长度进度条就只能显示下载中这种状态了。5.2 多文件批量下载如果业务是勾选多个PDF一键打包下载前端方案一般是用JSZip把多个Blob打包成一个zip再下载import JSZip from jszip; async function downloadMultiplePdfs(fileList) { const zip new JSZip(); for (let i 0; i fileList.length; i) { const response await fetch(fileList[i].url); const blob await response.blob(); zip.file(fileList[i].fileName, blob); } const zipBlob await zip.generateAsync({ type: blob }); // 再走a标签下载zipBlob }这个方案适合文件数量不多、单个文件不算大的场景。文件数量超过20个或者总体积特别大时还是建议后端打包前端直接下载zip文件处理速度和稳定性都更好。5.3 下载按钮与pdf.js加载状态的联动常见的问题是用户刚进页面就点下载此时pdf.js还在加载文件下载按钮也同时发起请求造成双重请求白白浪费带宽甚至触发后端的频率限制。我的做法是在pdf.js的loadingTask.promise里控制下载按钮的disabled状态。只有预览文档加载完成后下载按钮才可点击。这样既避免了重复请求又保证了用户看到过PDF内容再决定下载符合先预览后下载的产品逻辑。5.4 下载后的资源清理这个是最容易忽略但最重要的细节。每次用URL.createObjectURL生成的对象URL都会占用内存如果不手动释放不断下载多个文件后页面内存占用会持续上涨最终导致卡顿。释放的时机有两个选择一是在click()之后立刻释放某些浏览器有概率出问题二是把Blob URL存到一个数组中在页面卸载或者组件销毁时统一释放。我的经验是单文件下载用setTimeout延迟1秒释放即可多文件连续下载则用统一释放策略更稳妥。6. 给PDF下载方案做的最后一点总结性建议我在实际项目中处理pdf.js文件下载这件事前后迭代了三版方案最终沉淀下来的是这套组合逻辑pdf.js负责预览和解析fetch负责拉数据Blob加URL.createObjectURL负责生成可下载的临时地址再配合a标签的download属性和iOS兼容降级。这套链路能覆盖桌面端、安卓端、iOS端的大部分场景代码量不长维护成本也低。最后说一个容易被忽略的关键点前端的下载方案无论怎么折腾边界都很明显——它受浏览器策略、文件大小、跨域配置这几方面约束。一旦遇到文件特别大后端不愿意配合加下载接口跨域又拿不到CORS头这类情况最省事的路径反而是让后端给一个直链前端就负责跳转和提示。技术方案没有银弹结合自家项目的后端能力和文件存储方式选型比强行套一个最优方案更现实。本文还有配套的精品资源点击获取 pdf.js实现PDF文件下载：原理、代码与浏览器兼容性避坑指南
简介PDF.js 开源库的完整项目包面向需要在浏览器中实现 PDF 文档免插件渲染的网页前端开发者解决嵌入 PDF 阅读功能的集成与部署问题。资源包含 200 个文件涵盖核心脚本、样式文件、配置属性与大量图标资源压缩包约 45MB可支撑核心库、工作线程、查看器逻辑等模块协同工作覆盖从基础渲染到高级交互的完整链路。已有 2876 人学习下载适合具备一定脚本语言基础、希望深入理解 PDF.js 接口与渲染原理的开发者无论是基础入门还是二次开发都能从中获得有效参考。包内提供可直接运行的示例页面与配套图标便于本地运行调试可对照学习 PDF 加载、绘制、事件监听及自定义工具栏。同时支持搜索、缩略图、连续阅读等高级功能为在现有项目中二次开发提供清晰可扩展的代码基础便于按需调整界面与交互逻辑。 如果只是把PDF当做一个静态资源丢给用户下载那确实不需要费劲研究什么。但实际项目里需求往往是在网页里先预览PDF再提供一个下载按钮或者后端接口返回的是文件流浏览器却直接给渲染成预览页了再或者用户点了下载iPad上的Safari非要把PDF打开成预览就是不弹下载。这些场景凑到一起就会变成一个绕不开的技术点如何用pdf.js这个库把PDF文件从能看变成能下、下得对、下得稳。这篇东西就是围绕pdf.js文件下载这个主题写的内容包含pdf.js的基本引入方式、利用它获取文件数据、再配合Blob机制实现可控下载的核心代码以及我在实际项目中踩过的那些下载变预览下载文件名乱码iOS Safari不弹下载之类的坑还有对应的排查思路和解决方案。适合正在做Web端PDF模块、尤其是用Vue或原生JS开发并遇到下载问题的前端同学参考。1. 为什么下载PDF在网页里会翻车浏览器默认行为的三个陷阱先聊一个反直觉的事实在网页里把PDF下载这件事做好比很多人想象中要麻烦得多。表面上看一个a hrefxxx.pdf download标签就能搞定但浏览器对PDF的处理有一套自己的逻辑这套逻辑经常和业务需求对着干。第一个陷阱是浏览器的内置PDF预览器。桌面端Chrome、Edge、Firefox都把PDF直接渲染在了标签页里用户点开链接看到的是预览不是下载。如果产品经理想要的是用户一点按钮就直接弹出保存窗口那默认行为就完全不满足需求。你需要在代码层面强制浏览器走下载而不是预览。第二个陷阱是download属性并不总是生效。download属性看起来是标准方案但它有一个关键限制跨域资源下浏览器会忽略这个属性。现在很多项目的PDF文件都存在OSS、CDN或独立文件服务器上由前端直接拼URL访问这种情况下你写一百遍download也没用浏览器照样给你打开预览。第三个陷阱是移动端Safari尤其是iPad。iOS Safari对download属性、对Blob URL的支持都有自己的一套行为逻辑经常出现安卓上能正常下载iPhone一打开就变预览的诡异现象。如果项目有一定规模的移动端用户这个坑基本绕不开。所以结论很明确要靠a标签加一个URL搞定PDF下载只适用于文件同源且浏览器行为恰好符合预期的理想场景。一旦遇到跨域、移动端、需要自定义文件名、需要统计下载进度这些真实需求就必须把PDF文件的数据拿回到前端手里自己去控制下载流程——而拿数据、解析数据这件事正是pdf.js的看家本领。2. pdf.js的两种加载方式和Worker配置下载功能的地基pdf.js是Mozilla家出的开源PDF解析引擎底层用Web Worker解析PDF二进制数据再通过Canvas把每一页渲染出来。很多人对它的印象是一个PDF预览组件实际上它拆开来看是两层能力第一层是把PDF文件数据拉回来并解析成文档对象第二层才是把页面渲染成Canvas。下载功能真正依赖的是第一层能力。2.1 引入pdf.js的正确姿势如果是传统页面直接用CDN引入是最快的script srchttps://unpkg.com/pdfjs-dist3.11.174/build/pdf.min.js/script如果项目是Vue或React这类工程化项目建议走npm安装npm install pdfjs-dist3.11.174这里有第一个需要注意的细节pdf.js的版本差异比较大2.x和3.x在API上有明显的区别网上很多教程用的是老版本API直接抄到新版项目里会报错。我用的版本是3.x下面所有代码也都按3.x写。还需要重点提一下Worker的配置。pdf.js的解析工作默认在Worker线程里跑不配置Worker的话库会退化到主线程执行解析同时会在控制台打出一行警告大概意思就是你忘了配worker了大文件预览时页面会明显卡顿。下载场景虽然主要是拿数据但如果你的功能是先预览再下载那Worker配置就是一个必须做的优化。CDN方式下这样配pdfjsLib.GlobalWorkerOptions.workerSrc https://unpkg.com/pdfjs-dist3.11.174/build/pdf.worker.min.js;如果是Webpack或Vite工程可以这样import * as pdfjsLib from pdfjs-dist; pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.js, import.meta.url ).toString();2.2 getDocument的两种传参方式pdf.js加载PDF的核心方法是getDocument它能接受一个URL字符串也能直接接受二进制数据。这两种方式对应着下载功能的两条实现路径。// 方式一直接传URL适合同源或后端允许跨域的PDF地址 const loadingTask pdfjsLib.getDocument(pdfUrl); // 方式二传ArrayBuffer适合已经有文件数据的场景 const loadingTask pdfjsLib.getDocument({ data: arrayBuffer });第一种方式最省事但受跨域限制第二种方式更灵活只要你能用fetch把文件流拿到手后面想怎么处理都行。这个区分很重要后面讲下载实现方案时会反复用到。3. 核心方案拆解用pdf.js和Blob实现可控的PDF下载现在进入正题。先明确一下我最终采用的下载方案它不是单纯靠pdf.js的某一个API而是把pdf.js的数据能力、fetch的流获取能力、Blob的对象URL机制组合起来形成一条可控的下载链路。3.1 整体思路预览与下载分离我的做法是预览走pdf.js渲染下载走fetch取流。两个功能看着都是围绕同一个PDF但数据链路分开职责清晰出了问题也好排查。下载的完整链路是这样的根据PDF的地址或者后端接口返回的文件流使用fetch请求文件数据将返回的Response转换为Blob对象通过URL.createObjectURL(blob)生成一个临时的对象URL创建a标签设置href为对象URLdownload属性为自定义文件名触发点击完成下载下载后立即释放对象URL避免内存泄漏这里把pdf.js放进来原因是很多业务场景中PDF地址不是简单的前端写死URL而是需要带上token认证、或者需要从pdf.js已加载的文档中获取元数据来决定文件名、又或者后端返回的是加密的二进制流需要先让pdf.js能解析成功才说明数据没问题。这种情况下直接给a标签喂URL是走不通的你得先把数据拿回来、确认能解析、再生成下载。3.2 核心代码示例下面这段代码是我在Vue项目里实际用过的精简版本核心逻辑可以平移到任何框架async function downloadPdf(pdfUrl, fileName) { // 第一步把PDF文件流拉回来 const response await fetch(pdfUrl); if (!response.ok) { throw new Error(PDF文件请求失败HTTP状态码 response.status); } // 第二步转成Blob对象 const blob await response.blob(); // 第三步生成临时对象URL const blobUrl URL.createObjectURL(blob); // 第四步创建a标签并模拟点击 const link document.createElement(a); link.href blobUrl; link.download fileName || document.pdf; document.body.appendChild(link); link.click(); document.body.removeChild(link); // 第五步释放对象URL URL.revokeObjectURL(blobUrl); }这段代码看起来简单但里面有三个细节容易被忽略。第一个细节link必须添加到body里再触发点击不添加直接click()在某些浏览器版本里不生效这是有实际教训的。第二个细节URL.revokeObjectURL(blobUrl)要放在click()之后但最好不要在同步代码里立刻执行。有些浏览器在点击后还没来得及读取Blob数据就撤销了URL会导致下载失败。稳妥的做法是加一个setTimeout延迟释放setTimeout(() { URL.revokeObjectURL(blobUrl); }, 1000);第三个细节从后端接口获取文件时如果项目里封装了axios注意设置responseType: blob。用axios默认的JSON类型去接收二进制流数据会被转成奇怪的字符串下载下来的文件打不开。这是一个非常高频的翻车点。3.3 如果一定要用pdf.js加载后的数据来下载有些场景下文件地址不能直接fetch比如做了权限控制、只能通过pdf.js已经建立的会话来获取数据这种场景不多但确实存在。这时可以利用pdf.js的getDocument拿到文档后通过loadingTask的原始数据属性来拿数据不过说实话这个操作在3.x版本里比较绕我的建议是直接从网络层解决要么后端加一个下载接口要么在fetch请求里带上同样的认证头。硬要从pdf.js内部取数据代码会变得不直观维护成本也高没必要。4. 踩坑实录从下载变预览到iOS Safari不下载的完整排查链这个章节我想用问题现象 排查过程 根因 解决的方式来写因为下载PDF的坑基本套路都差不多但你得知道怎么一步步定位。4.1 问题一点击下载按钮浏览器直接打开了PDF预览现象按钮、a标签、URL全部正常点击后桌面Chrome直接开了一个新标签页把PDF渲染出来下载根本没触发。排查过程先检查href指向的PDF地址和当前页面是不是同源。如果是同源且写法是a hreffile.pdf downloadxxx.pdf理论上Chrome应该直接下载。试了以后发现依然预览于是打开控制台看网络面板发现请求的响应头里有一个关键字段Content-Disposition: inline; filenamefile.pdf。当后端或静态服务器返回inline时浏览器就会认为这个资源应该被内联展示download属性也会被它压制。解决前端做不了什么来改变响应头里的Content-Disposition所以走fetch拿Blob的时候其实是在绕过这个响应头对浏览器行为的控制——因为fetch拿到的只是数据展示或下载的决策权完全在前端手里。4.2 问题二下载文件名变成一串乱码或者直接被忽略现象文件成功下载了但保存下来的文件名不是预期的中文名而是一串URL编码或者直接被浏览器命名成了下载。排查过程用fetch拿Blob再download指定文件名时一般不会出现这个问题因为这个方案的download属性是标准生效的。但如果代码里漏了download属性浏览器就会根据响应头里的Content-Disposition去取名后端如果没设置filename*中文名大概率乱码。另一种情况是后端虽然返回了Content-Disposition: attachment但用的文件名编码格式不对没处理filename*UTF-8这种形式。解决前端方案里强制给a标签设置download属性文件名自己拼。注意文件名如果包含中文不用手动做URL编码直接赋值就可以。如果要做得更严谨可以先从响应头里解析Content-Disposition拿到后端推荐的filename*解析不出来再用自己自定义的名字。4.3 问题三iPad/iPhone上的Safari打开下载按钮后还是预览现象同样的代码安卓手机和桌面浏览器都正常iPhone和iPad点下载按钮后PDF直接在Safari里打开成预览页顶部没有下载选项或者说藏得很深用户根本找不到保存入口。排查过程这是移动端Safari的经典行为差异。iOS Safari对a标签的download属性支持一直不完整Blob URL的下载行为在iOS 13以前基本是废弃状态iOS 13以后虽然部分支持但在iPad上仍然不稳定尤其是PDF这种Safari有能力原生预览的文件类型系统就是优先做预览。解决我在实际项目中最终采用的是两步兼容方案。第一步页面里同时放一个提示如无法下载请长按链接选择下载链接文件。第二步对iOS设备做UA判断降级使用window.open打开Blob URL让Safari自己处理预览用户通过系统分享按钮保存文件。虽然体验不如一键下载那么顺畅但至少用户有路可走。这里贴一下兼容逻辑的核心片段const isIOS /iPad|iPhone|iPod/.test(navigator.userAgent) || (navigator.platform MacIntel navigator.maxTouchPoints 1); if (isIOS) { // iOS Safari降级方案打开预览让用户通过系统分享保存 window.open(blobUrl, _blank); } else { // 正常下载逻辑 const link document.createElement(a); link.href blobUrl; link.download fileName; document.body.appendChild(link); link.click(); document.body.removeChild(link); }4.4 问题四大文件下载把浏览器内存吃爆了现象一个几十MB甚至上百MB的PDF点下载后页面卡死或者下载下来的文件损坏无法打开。排查过程response.blob()会把整个文件加载进内存加上pdf.js预览时也要占用一份内存两者叠加后大文件场景下必然吃紧。如果文件有几百MB前端做全量下载本来就不合理。解决两个方向。一是大文件不建议前端走blob链路让后端直接返回一个带Content-Disposition: attachment的文件地址用最朴素的方式下载二是如果一定要前端处理至少加一个文件大小判断超过某个阈值比如100MB就提示用户走后端直链下载。另外下载完成后务必释放Blob URL这个前面已经强调过了。5. 从能下载到下载体验好进度提示、多文件下载和状态联动下载功能做到能跑只是第一步实际集成时还有不少体验层面的细节。这里整理几个我做过且值得做的增强点。5.1 下载进度提示fetch返回的Response对象带有一个body它是一个ReadableStream可以监听数据接收的进度。把Blob的组装过程改成流式读取就能算百分比async function downloadPdfWithProgress(pdfUrl, fileName, onProgress) { const response await fetch(pdfUrl); const contentLength response.headers.get(Content-Length) || 0; const reader response.body.getReader(); let receivedLength 0; const chunks []; while (true) { const { done, value } await reader.read(); if (done) break; chunks.push(value); receivedLength value.length; if (contentLength onProgress) { onProgress(Math.round((receivedLength / contentLength) * 100)); } } const blob new Blob(chunks); // 后续的下载逻辑同上 }需要注意这个方案需要后端接口返回Content-Length响应头如果后端是分块传输chunked拿不到总长度进度条就只能显示下载中这种状态了。5.2 多文件批量下载如果业务是勾选多个PDF一键打包下载前端方案一般是用JSZip把多个Blob打包成一个zip再下载import JSZip from jszip; async function downloadMultiplePdfs(fileList) { const zip new JSZip(); for (let i 0; i fileList.length; i) { const response await fetch(fileList[i].url); const blob await response.blob(); zip.file(fileList[i].fileName, blob); } const zipBlob await zip.generateAsync({ type: blob }); // 再走a标签下载zipBlob }这个方案适合文件数量不多、单个文件不算大的场景。文件数量超过20个或者总体积特别大时还是建议后端打包前端直接下载zip文件处理速度和稳定性都更好。5.3 下载按钮与pdf.js加载状态的联动常见的问题是用户刚进页面就点下载此时pdf.js还在加载文件下载按钮也同时发起请求造成双重请求白白浪费带宽甚至触发后端的频率限制。我的做法是在pdf.js的loadingTask.promise里控制下载按钮的disabled状态。只有预览文档加载完成后下载按钮才可点击。这样既避免了重复请求又保证了用户看到过PDF内容再决定下载符合先预览后下载的产品逻辑。5.4 下载后的资源清理这个是最容易忽略但最重要的细节。每次用URL.createObjectURL生成的对象URL都会占用内存如果不手动释放不断下载多个文件后页面内存占用会持续上涨最终导致卡顿。释放的时机有两个选择一是在click()之后立刻释放某些浏览器有概率出问题二是把Blob URL存到一个数组中在页面卸载或者组件销毁时统一释放。我的经验是单文件下载用setTimeout延迟1秒释放即可多文件连续下载则用统一释放策略更稳妥。6. 给PDF下载方案做的最后一点总结性建议我在实际项目中处理pdf.js文件下载这件事前后迭代了三版方案最终沉淀下来的是这套组合逻辑pdf.js负责预览和解析fetch负责拉数据Blob加URL.createObjectURL负责生成可下载的临时地址再配合a标签的download属性和iOS兼容降级。这套链路能覆盖桌面端、安卓端、iOS端的大部分场景代码量不长维护成本也低。最后说一个容易被忽略的关键点前端的下载方案无论怎么折腾边界都很明显——它受浏览器策略、文件大小、跨域配置这几方面约束。一旦遇到文件特别大后端不愿意配合加下载接口跨域又拿不到CORS头这类情况最省事的路径反而是让后端给一个直链前端就负责跳转和提示。技术方案没有银弹结合自家项目的后端能力和文件存储方式选型比强行套一个最优方案更现实。本文还有配套的精品资源点击获取