PDF.js做按需分片加载这件事我前后折腾了两周才彻底跑通。当时手里有个文档预览项目PDF文件动辄几十MB起步有的甚至上百MB用传统的整包加载方式用户打开页面转圈转到怀疑人生运维那边带宽成本也吃不消。后来换成了PDF.js 后端Range请求的分片方案首屏加载时间从十几秒压缩到了两秒内内存占用也降了一大截。这篇文章把前后端的完整实现、源码思路、还有我踩过的坑一次性讲清楚适合正在做在线文档预览、大文件处理或者想优化PDF加载性能的同学参考。1. 方案选型与整体架构设计1.1 大PDF加载的痛点在哪先说我为什么一开始会想到用PDF.js做分片加载而不是直接用浏览器自带的PDF插件。浏览器原生PDF插件的问题非常明显它会把整个文件拉下来才开始渲染。我拿一个58MB的PDF内测过Chrome直接内存飙到1.2GB页面卡顿滚动起来能明显感觉到掉帧。更麻烦的是用户如果只看了前面几页后面几十MB的内容其实完全没被用到纯属浪费流量和内存。那PDF.js能不能解决答案是能但前提是你要真正理解它的加载机制。PDF.js默认情况下如果你直接传一个完整URL给getDocument()它会通过HTTP请求去拉取整个PDF文件。但是PDF.js内部其实有一套非常聪明的机制PDF文件本身有一个特殊的线性化结构Linearized PDF文件开头存了页树、对象的偏移表浏览器可以跳过中间的字节直接定位到任意一页的数据。PDF.js支持把这种能力暴露出来让我们可以按需请求数据块。要实现按需求取就必须让PDF.js知道服务器支持Range请求也就是HTTP状态码206 Partial Content那种响应方式。然后通过配置项告诉它别一次性拉完用到哪一页就去请求对应的字节范围。1.2 两种加载方案的对比我在做技术选型的时候把几种主流方案都拉出来对比过一遍这里直接列个表方案加载策略内存表现首屏速度实现成本浏览器原生PDF插件全量下载差大文件直接卡死慢零PDF.js默认加载全量下载 解析中等偏差慢低PDF.js disableAutoFetch按需分片良好快中PDF.js 自定义Transport完全可控分片最优最快高我最后选的是PDF.js disableAutoFetch加后端口Range支持属于性价比最高的路线。自定义Transport方案虽然控制粒度最细但要自己实现PDF数据流解析逻辑开发周期会拉长不少对于大多数业务场景其实没有必要。1.3 前后端整体架构拆分整个系统的架构大体分三层前端展示层基于PDF.js的viewer组件负责渲染PDF页面、处理用户交互、记录阅读进度后端服务层提供两个核心接口——文件元信息接口返回PDF总字节数、页数等和分片读取接口支持HTTP Range存储层PDF文件放OSS或者本地磁盘后端分片接口内部去读对应的字节区间前端和后端之间走的协议就是HTTP Range前端在每次需要渲染新页面的时候向后端发一个带Range头的请求后端返回对应的二进制分片数据。这个设计的好处是不管底层存的是OSS还是NAS只要后端抽象了一层字节读取接口前端完全不关心文件到底存在哪。2. 后端分片读取接口设计与实现2.1 Range请求的核心原理HTTP Range协议是分片加载的地基。简单说客户端发起请求时带上一个Range头格式是Range: bytes0-1023这个请求的意思是我只想要文件从第0个字节到第1023个字节这一段数据共1024字节。服务端如果支持Range就返回206状态码同时带上Content-Range响应头格式是Content-Range: bytes 0-1023/58431255斜杠后面是文件的完整大小。注意这个完整大小非常重要PDF.js要根据这个值来判断文件总长度从而计算每一页在文件里的偏移量。如果服务端不支持Range直接返回200和整个文件那PDF.js也会按全量下载来处理分片加载就直接失效了。所以后端的Range支持是整套方案的前提这一步没做好前端怎么调优都是白搭。2.2 基于Spring Boot实现Range接口我用的是Java技术栈Spring Boot框架。实现Range请求其实不复杂核心就是读取请求头里的Range解析起始和结束字节然后从文件里读取对应部分返回。下面这个是我在后端核心Controller层写的分片接口代码已经简化掉业务无关的部分RestController RequestMapping(/api/pdf) public class PdfFileController { Value(${pdf.storage.path}) private String storagePath; GetMapping(/stream/{fileId}) public ResponseEntityResource streamPdf( PathVariable String fileId, RequestHeader(value Range, required false) String rangeHeader, HttpServletRequest request) throws IOException { // 找到磁盘上对应的文件 File pdfFile new File(storagePath, fileId .pdf); if (!pdfFile.exists()) { return ResponseEntity.notFound().build(); } long fileSize pdfFile.length(); String contentType application/pdf; // 没有Range头返回完整文件兼容不支持Range的客户端 if (rangeHeader null) { return ResponseEntity.ok() .contentType(MediaType.parseMediaType(contentType)) .contentLength(fileSize) .body(new FileSystemResource(pdfFile)); } // 解析Range头格式如: bytes0-1023 RangeRange range parseRange(rangeHeader, fileSize); if (range null) { return ResponseEntity.status(416) .header(Content-Range, bytes */ fileSize) .build(); } long start range.start; long end range.end; long length end - start 1; // 关键随机读取指定字节区间 FileInputStream fis new FileInputStream(pdfFile); fis.skip(start); byte[] data new byte[(int) length]; int read fis.read(data); fis.close(); if (read length) { // 实际读取字节数不足文件可能被截断 byte[] partial Arrays.copyOf(data, read); return ResponseEntity.status(HttpStatus.PARTIAL_CONTENT) .header(Accept-Ranges, bytes) .header(Content-Range, bytes start - (start read - 1) / fileSize) .contentType(MediaType.parseMediaType(contentType)) .body(new ByteArrayResource(partial)); } return ResponseEntity.status(HttpStatus.PARTIAL_CONTENT) .header(Accept-Ranges, bytes) .header(Content-Range, bytes start - end / fileSize) .contentLength(length) .contentType(MediaType.parseMediaType(contentType)) .body(new ByteArrayResource(data)); } private RangeRange parseRange(String rangeHeader, long fileSize) { if (!rangeHeader.startsWith(bytes)) { return null; } String rangeStr rangeHeader.substring(bytes.length()); String[] parts rangeStr.split(-); if (parts.length ! 2) { return null; } long start Long.parseLong(parts[0]); long end parts[1].isEmpty() ? fileSize - 1 : Long.parseLong(parts[1]); // 越界处理 if (start fileSize) { return null; } if (end fileSize) { end fileSize - 1; } if (start end) { return null; } return new RangeRange(start, end); } }这段代码里有几个细节值得注意解析Range头的时候要做越界保护。PDF.js有时候发出来的Range请求会超出文件末尾后端不能直接报错要把end截断到fileSize - 1fis.skip(start)这一步是随机读取的关键文件多大都没关系JVM不需要把整个文件读进内存每次请求都打开一次文件流频繁操作IO性能一般用RandomAccessFile或者先缓存文件句柄性能会更好。我在线上是用了RandomAccessFile优化过后面在问题排查章节会细说2.3 文件元信息接口的设计除了分片读取接口还需要一个返回PDF元信息的接口前端拿到这个才知道文件有多大、需要发多少个分片请求。GetMapping(/meta/{fileId}) public MapString, Object getPdfMeta(PathVariable String fileId) throws IOException { File pdfFile new File(storagePath, fileId .pdf); MapString, Object meta new HashMap(); meta.put(fileSize, pdfFile.length()); meta.put(fileName, pdfFile.getName()); return meta; }这个接口本身不复杂但它解决的痛点很实际前端在初始化PDF.js的时候需要知道文件总字节数如果没有这个接口前端就得先发一个不带Range的请求去探一下文件大小浪费一次全量请求碰到大文件就失去意义了。2.4 CORS跨域配置如果你的前端和后端分离部署域名不一样CORS必须配好。否则浏览器会把后端的206响应直接拦截掉前端看到的报错是“Failed to load resource: net::ERR_FAILED”排查起来非常折磨人。后端需要允许Range头这里直接给个配置类Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(http://localhost:8080) .allowedMethods(GET, POST, OPTIONS) .allowedHeaders(Range, Content-Type, Authorization) .exposedHeaders(Content-Range, Accept-Ranges, Content-Length) .maxAge(3600); } }exposedHeaders这里特别容易漏。默认情况下前端JS只能读取一些基本的响应头Content-Range这种自定义头不在白名单里必须通过exposedHeaders显式暴露出去前端才能读到文件的完整大小信息。3. PDF.js前端接入与按需加载实现3.1 引入PDF.js的正确姿势前端部分我用的是PDF.js官方dist包建议直接用CDN或者npm包不要自己从源码编译省去很多兼容性麻烦。npm安装npm install pdfjs-dist然后重点来了PDF.js 3.x以上版本worker文件的指定方式有变化。我最初没指定版本号默认装了个最新的4.x结果API变了排查了半天才发现问题。我这里用的是3.11.174这个稳定版本引入方式是这样的import * as pdfjsLib from pdfjs-dist; import workerSrc from pdfjs-dist/build/pdf.worker.entry; pdfjsLib.GlobalWorkerOptions.workerSrc workerSrc;注意workerSrc一定要正确设置。PDF.js的主线程和worker线程之间会通过postMessage通信worker负责解析PDF的结构信息如果worker加载失败整个PDF.js就跑不起来控制台会报Setting up fake worker的警告。3.2 按需分片加载的关键配置项核心在于getDocument的配置参数。我直接贴出完整代码每一步的含义在后面详细解释async function loadPdfWithRange(fileId) { // 先获取文件元信息 const metaRes await fetch(/api/pdf/meta/${fileId}); const meta await metaRes.json(); // 加载PDF文档关键配置在下面 const loadingTask pdfjsLib.getDocument({ url: /api/pdf/stream/${fileId}, // 关键配置1: 禁止自动拉取整个文件 disableAutoFetch: true, // 关键配置2: 禁止流式加载 disableStream: false, // 关键配置3: 每个分片请求的字节数 rangeChunkSize: 65536, // 关键配置4: 告诉PDF.js用Range加载 useRange: true, // 关键配置5: 文件总长度 length: meta.fileSize, // 关键配置6: 前端预加载策略 stopAtErrors: true, }); const pdfDoc await loadingTask.promise; console.log(PDF加载完成总页数:, pdfDoc.numPages); return pdfDoc; }这里每个配置都值得展开讲disableAutoFetch: true这是分片加载的总开关。设为true之后PDF.js只在需要渲染某一页的时候才去请求对应的数据不会偷偷把整个文件拉下来。这个配置决定了首屏速度能提升多少。rangeChunkSize: 65536这个值代表PDF.js每次请求的数据块大小单位是字节。我试过不同的值16KB太小会导致请求次数过多浪费握手时间256KB又太大首屏会变慢。64KB是从性能曲线里找到的甜点值。useRange: true显式告诉PDF.js服务器支持Range请求。如果这个值不传PDF.js会先发一个不带Range的请求通过看响应状态码是206还是200来判断服务器是否支持Range相当于白白多一次全量请求。length: meta.fileSize这个值配合useRange用可以让PDF.js跳过探测阶段直接进入分片请求。相当于我们提前拿到了答案不用再试错。配置好之后PDF.js在渲染第二页、第三页的时候会自动发形如Range: bytes32768-98303的请求后端返回对应的数据块整个过程对业务代码完全透明。3.3 页面渲染与懒加载控制PDF.js负责数据加载但页面渲染还需要我们自己去实现。我写了一个简单的渲染函数核心逻辑就是拿到页面对象然后通过canvas把页面画出来class PdfViewer { constructor(container, pdfDoc) { this.container container; this.pdfDoc pdfDoc; this.pageCache new Map(); // 缓存已渲染的canvas this.currentPage 1; this.totalPages pdfDoc.numPages; this.renderQueue []; // 渲染任务队列 this.isRendering false; } async renderPage(pageNum, scale 1.0) { // 检查缓存避免重复渲染 if (this.pageCache.has(pageNum)) { const cached this.pageCache.get(pageNum); this.container.appendChild(cached); return; } const page await this.pdfDoc.getPage(pageNum); const viewport page.getViewport({ scale }); // 动态创建canvas const canvas document.createElement(canvas); canvas.width viewport.width; canvas.height viewport.height; const ctx canvas.getContext(2d); const renderTask page.render({ canvasContext: ctx, viewport }); await renderTask.promise; this.pageCache.set(pageNum, canvas); this.container.appendChild(canvas); } async goToPage(pageNum) { if (pageNum 1 || pageNum this.totalPages) { return; } this.currentPage pageNum; // 只渲染当前页其他页懒加载 await this.renderPage(pageNum); // 预渲染前后各一页提升翻页流畅度 this.preloadPages(pageNum); } preloadPages(currentPage) { const pagesToPreload [currentPage - 1, currentPage 1]; pagesToPreload.forEach(pageNum { if (pageNum 1 pageNum this.totalPages !this.pageCache.has(pageNum)) { // 预渲染优先级低用requestIdleCallback或者setTimeout延迟执行 setTimeout(() this.renderPage(pageNum), 200); } }); } }懒加载的核心逻辑其实就一句话用到的页面才渲染当前页的前后页预加载其他的等用户翻到再说。3.4 Worker线程与主线程通信优化PDF.js的解析工作默认在Worker线程执行不会阻塞UI线程。但如果页面复杂渲染指令传到主线程去画canvas这部分还是会占用主线程。我的经验是渲染好的canvas不要重复销毁直接按页码缓存起来翻页的时候直接显示缓存几乎无感。还有个优化点单页渲染完成后给canvas加了一层transform缩放让它在屏幕内完整显示等用户放大后再重新渲染高分辨率版本。第一版渲染用0.75倍scale放大到100%以上时才走全分辨率渲染这样快速翻页的响应速度会快很多。4. 阅读进度记录与前后端联动4.1 进度记录的整体思路在热词里看到“pdf.js如何把阅读到哪一页记录到数据库里”这个需求我确实做在了同一套系统里。实现方式其实很简单监听用户翻页事件把页码通过接口传给后端后端存到数据库里。但真正做的时候有几个细节要想清楚写入频率不能太频繁否则翻页的时候每翻一页就发一次请求后端压力大用户可能只是随手翻一下不是真正停留阅读所以要做节流和防抖后端保存的应该是用户身份加文件ID加页码这样才能精确记录每个用户在每份文档里的位置4.2 前端JavaScript实现前端在翻页时采集进度这里我用了一个简单的防抖机制class PdfViewer { constructor() { // ...其他初始化 this.progressSaveTimer null; this.lastSavedPage 1; this.userId this.getCurrentUserId(); this.fileId this.getCurrentFileId(); // 页面可见性变化时强制保存避免用户直接关掉浏览器丢失进度 document.addEventListener(visibilitychange, () { if (document.visibilityState hidden) { this.saveProgress(true); } }); } goToPage(pageNum) { // ...前面的渲染逻辑 // 更新进度防抖500ms避免连续翻页时频繁请求 this.debouncedSaveProgress(pageNum); } debouncedSaveProgress(pageNum) { if (this.progressSaveTimer) { clearTimeout(this.progressSaveTimer); } this.progressSaveTimer setTimeout(() { this.saveProgress(pageNum); }, 500); } async saveProgress(pageNum) { try { await fetch(/api/reading/progress, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ userId: this.userId, fileId: this.fileId, pageNum: pageNum, totalPages: this.totalPages, timestamp: Date.now() }) }); this.lastSavedPage pageNum; } catch (e) { console.warn(保存阅读进度失败稍后重试); } } }4.3 后端Spring Boot实现后端接口就简单多了用一个ProgressRecord实体存数据库用MyBatis-Plus或者JPA操作都行RestController RequestMapping(/api/reading) public class ReadingProgressController { Autowired private ReadingProgressService progressService; PostMapping(/progress) public ApiResponse saveProgress(RequestBody ProgressSaveRequest request) { // 校验参数 if (request.getUserId() null || request.getFileId() null) { return ApiResponse.error(用户ID和文件ID不能为空); } progressService.saveOrUpdateProgress( request.getUserId(), request.getFileId(), request.getPageNum(), request.getTotalPages() ); return ApiResponse.success(); } GetMapping(/progress/{userId}/{fileId}) public ApiResponse getProgress(PathVariable Long userId, PathVariable String fileId) { Integer pageNum progressService.getProgress(userId, fileId); return ApiResponse.success(pageNum); } }这里有个陷阱保存进度不能只做insert要考虑重复保存的情况。如果用户之前读过同一份文档现在翻到了新的一页数据库里应该做update而不是insert。我用了联合唯一索引(user_id, file_id)加INSERT ... ON DUPLICATE KEY UPDATE的方式解决天然处理了这个边界。4.4 阅读进度恢复实践用户下次打开文档时前端先调进度查询接口拿到上次读到的页码然后直接跳转到那一页。这一步需要和分片加载协同起来跳转到某个页码时PDF.js会立即请求那一页所需的数据块不会从头加载。代码里的实现也很直接async function initViewer(fileId, userId) { const pdfDoc await loadPdfWithRange(fileId); const viewer new PdfViewer(container, pdfDoc); // 尝试恢复阅读进度 try { const progressRes await fetch(/api/reading/progress/${userId}/${fileId}); const progress await progressRes.json(); const startPage progress.data || 1; await viewer.goToPage(startPage); } catch (e) { // 没有历史进度从第一页开始 await viewer.goToPage(1); } return viewer; }这样整个闭环就通了打开文档自动跳转到上次位置中间的分片加载、懒加载全部生效用户体验接近原生阅读器。5. 常见问题排查与优化实录5.1 常见问题速查表这段内容是我连续调试两周后总结出来的高频问题和对应解法可以直接存下来当排查手册用问题现象根因分析解决方法页面只出第一页翻页时一直转圈disableAutoFetch设为false或后端没返回206检查配置项用curl测试后端Range头控制台报Unexpected server response (200)useRange为true但后端实际不支持Range让后端返回206 Content-Range头或先去掉useRangePDF能加载但内存持续上涨rangeChunkSize设置过大每个分片都很大调小rangeChunkSize比如32KB或64KB跨域部署时PDF白屏CORS没暴露Content-Range响应头后端exposedHeaders加上Content-Range快速翻页时渲染错乱渲染任务并发后面的任务覆盖了前面的加渲染队列串行渲染或按页码优先级排队已渲染的页面重复请求前端没有缓存pageCache用Map缓存页码到canvas的映射进度保存失败防抖时间太短每页都在发请求防抖改为500ms页面隐藏时强制保存PDF.js解析失败Worker文件路径配置错误检查GlobalWorkerOptions.workerSrc指向是否有效5.2 前端调试技巧调试Range请求有个特别实用的技巧打开Chrome DevTools的Network面板筛选类型为Fetch/XHR你会发现原来的一个200响应变成了无数个206响应每个响应的大小都不大大约64KB。正常的情况下你会看到一个清晰的请求序列初次加载时请求文件头部数据翻到某一页时突然冒出一批新的206请求。如果翻页之后没有新的请求出现说明PDF.js没有触发分片加载大概率是disableAutoFetch没有生效。我还习惯用curl直接仿真后端Range接口快速定位是后端还是前端的问题curl -H Range: bytes0-1023 -I http://localhost:8080/api/pdf/stream/test看到返回状态码206、Content-Range头里的总字节数基本就能确认后端没问题。5.3 后端性能优化实录我接口上线之后给自己做了个压测发现高并发下文件流频繁打开关闭文件句柄数飙得很快。后来改成了RandomAccessFile同时把文件句柄做了一层缓存按fileId维度过期清理。另外还有一个坑直接用FileInputStream的问题在于每次都要从磁盘读数据但PDF.js的请求是有明显局部性特征的——某一时间段内请求的字节范围都集中在一个较小区间内一页读完了再跳到很远的偏移量去读下一页。根据这个特征我在后端加了一层简单的LRU缓存把最近读过的几个分片数据缓存到内存中。性能提升很明显磁盘IO减少了差不多一半。注意缓存分片数据时要控制缓存大小不然内存会被撑爆。我的做法是每个文件最多缓存4个分片每个64KB用LinkedHashMap的accessOrder实现LRU策略。5.4 推进过程中容易忽略的隐蔽问题有些问题藏得很深不实际跑场景根本发现不了。这里分享三个我踩过之后才明白的坑。第一个是PDF.js缓存的问题。同一个fileId的PDF如果内容更新了前端浏览器可能会命中缓存的旧文件导致用户看到的还是老版本。需要后端在文件变化时给fileId加一个版本号或时间戳参数例如/api/pdf/stream/123?version20240615强制刷新缓存。第二个是移动端兼容性。手机浏览器对Range的支持比较一致但PDF.js在移动端的canvas渲染要比桌面端慢很多。我针对移动端做了特殊优化默认scale降到0.75关闭预渲染前后页等用户点击放大时才重新渲染高清版本。实测移动端缩放和翻页的流畅度提升明显。第三个是超大PDF文件单文件超过200MB的极端情况。Range分片在这种体积下依然能工作但PDF.js解析页树的时候需要请求文件头部的目录结构这个操作无法避免。如果首屏等待时间还是太长可以考虑把PDF拆分成多个小文件但这就牵扯到语义层面的改动修改前要做好选型准备。5.5 线上稳定经验系统上线稳定运行几个月后我最后补充了一个监控指标正常用户的Range请求与PDF页面的比值。正常情况下用户翻到第N页大概会产生1到N个请求。如果某个用户产生了大量的Range请求但页面只停留在前几页大概率是PDF.js在重复请求同一区块需要排查是前端缓存失效还是后端响应异常。我在后端加了一个简单的日志统计按fileId聚合统计Range请求的字节区间重合度。如果同一区间被请求超过3次打个warning日志出来。上线前半个月确实抓出来两三个fileId有重复请求的问题逐一排查修复后整体分片命中率稳定在98%以上性能数据很好看。这套方案做完之前被吐槽卡顿的文档预览功能彻底翻篇了。后面有类似需求的同学可以直接按这个思路抄作业但记得把里面几个关键配置项根据你的实际文件大小和网络环境重新调一下。搞不定的点比如Range头格式不对、跨域暴露、按需加载没生效都可以在我上面那个排查表里找答案。