简介这份资源面向需要在H5页面中嵌入PDF预览功能的Web前端开发者基于Mozilla开源的PDF.js库解决浏览器原生无法直接展示PDF、必须依赖插件或跳转下载的痛点。压缩包共402个文件约3.67MB以168个bcmap字符映射文件、124个properties语言配置、86个png与9个svg界面素材为主另含4个js核心脚本、3个map、1个css样式表及1个html示例页覆盖字体编码、多语言界面与渲染逻辑等模块结构完整便于直接集成。资源已积累1224人学习下载适合初中级前端快速上手。借助其中的库文件与示例读者可掌握PDF加载、解析、Canvas分页渲染及缩放、平移、搜索等交互实现思路并了解Web Worker后台解析的优化方式为在线文档、合同预览等场景提供可复用的落地方案。1. 移动端 PDF 预览的第三条路为什么我最终选了 pdf.js做过 H5 项目的人大概率都遇到过这个需求后端返回一个 PDF 链接要求用户在手机浏览器里直接看不能下载、不能跳转第三方应用。第一反应通常是iframe srcxxx.pdf或者embed桌面端跑得好好的一到移动端就翻车——iOS Safari 只显示第一页Android 各家浏览器行为不一致微信内置浏览器更是玄学有时候白屏有时候直接触发下载。也试过让后端把 PDF 转成图片返回但文件体积翻倍、文字不能选中、放大就糊产品经理第一个不答应。绕了一圈最后还是回到 pdf.js 这条路上。它把 PDF 解析成 Canvas 渲染浏览器只要能跑 JS 就能用不依赖任何插件移动端兼容性是目前最稳的方案。这篇笔记就把我在几个 H5 项目里用 pdf.js 的完整流程拆开讲——怎么引入、怎么渲染、怎么翻页、怎么避坑以及那些官方文档不会告诉你的参数细节。适合正在做移动端文档预览的前端也适合被 iframe 方案折磨过的同行。2. 引入与初始化从 CDN 到本地构建的选型对比pdf.js 的引入方式直接决定了后续的维护成本和加载性能。我见过不少项目直接一行script srchttps://cdn.../pdf.min.js就上了开发阶段确实省事但上线后一旦 CDN 被墙或者版本更新导致 API 变动排查起来就是黑匣子。所以这一章先把引入方式讲清楚再落到初始化参数。2.1 三种引入方式的取舍目前主流有三种方式CDN 直引、npm 安装、本地构建。我一般会根据项目阶段来选。CDN 直引适合快速验证和 Demo代码量最少!-- 引入 pdf.js 主库和 worker -- script srchttps://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js/script script // 设置 worker 路径否则 pdf.js 会降级到主线程解析大文件直接卡死 pdfjsLib.GlobalWorkerOptions.workerSrc https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js; /script这里有个关键点workerSrc必须设置而且路径要和主库版本严格一致。版本不一致时worker 加载会静默失败pdf.js 回退到主线程解析表现就是页面卡顿几秒然后才渲染出来。这个坑我在一个活动页上踩过当时以为是文件太大查了半天才发现是 worker 没生效。npm 安装适合工程化项目npm install pdfjs-distimport * as pdfjsLib from pdfjs-dist; // 注意Vite/Webpack 下 worker 的引入方式不同 import workerSrc from pdfjs-dist/build/pdf.worker.min.js?url; pdfjsLib.GlobalWorkerOptions.workerSrc workerSrc;本地构建则是把 pdf.js 的源码 clone 下来改配置后打包适合需要深度定制渲染逻辑的场景比如要改文字层的选择行为或者加自定义水印。大多数业务项目用不到这一步。2.2 初始化参数怎么设拿到 PDF 文件后第一步是调用getDocument加载文档const loadingTask pdfjsLib.getDocument({ url: /api/file/xxx.pdf, // PDF 地址支持跨域需服务端配 CORS cMapUrl: /cmaps/, // 中文等 CJK 字符映射表路径 cMapPacked: true, // 使用压缩版 cmap体积更小 httpHeaders: { // 需要鉴权时带上 token Authorization: Bearer token } }); loadingTask.promise.then(function (pdf) { console.log(总页数:, pdf.numPages); }).catch(function (err) { // 这里必须捕获否则加载失败时页面无任何反馈 console.error(PDF 加载失败:, err); });参数逐个说url可以是相对路径、绝对路径或者 ArrayBuffer如果后端返回的是二进制流就传{ data: arrayBuffer }。cMapUrl是中文 PDF 最容易出问题的地方——不配这个中文可能显示成乱码或者空白方块因为 pdf.js 默认不带 CJK 字体映射。cMapPacked设为 true 会加载.bcmap压缩文件比未压缩的小很多。httpHeaders用于需要登录态的接口但注意跨域时自定义 header 会触发预检请求服务端要允许对应的 header。提示getDocument返回的是 loadingTask 而不是 promise必须通过.promise拿结果。直接 await loadingTask 会报错这个 API 设计确实反直觉。3. 渲染与翻页Canvas 绘制、缩放适配与性能控制文档加载进来只是第一步真正决定用户体验的是渲染环节。移动端屏幕小、内存有限如果一上来就把所有页渲染出来低端机直接崩。这一章讲清楚单页渲染的完整流程、缩放适配策略以及怎么做按需渲染。3.1 单页渲染的完整代码先看最基础的单页渲染async function renderPage(pdf, pageNum, canvas, scale) { // 获取指定页 const page await pdf.getPage(pageNum); // 根据缩放比例计算视口尺寸 const viewport page.getViewport({ scale: scale }); // 处理高清屏devicePixelRatio 让 canvas 实际像素翻倍避免模糊 const dpr window.devicePixelRatio || 1; canvas.width viewport.width * dpr; canvas.height viewport.height * dpr; canvas.style.width viewport.width px; canvas.style.height viewport.height px; const context canvas.getContext(2d); // 缩放 context 以匹配 dpr context.scale(dpr, dpr); const renderContext { canvasContext: context, viewport: viewport }; // render 返回 renderTask可用于取消渲染 const renderTask page.render(renderContext); await renderTask.promise; }这段代码有几个容易忽略的点。第一canvas.width和canvas.style.width是两回事前者是画布实际像素后者是 CSS 显示尺寸。移动端 dpr 通常是 2 或 3如果只设 style 不设 width画面会糊如果只设 width 不设 style画面会超出容器。第二context.scale(dpr, dpr)必须在每次重新设置 canvas 尺寸后调用因为改变 canvas 宽高会重置 context 状态。第三renderTask可以调用.cancel()取消这在快速翻页时很有用避免上一页还没渲染完就开始渲染下一页导致画面错乱。3.2 缩放适配fit-width 还是固定比例移动端最常见的需求是「宽度撑满屏幕」。做法是先拿到容器宽度再反推 scalefunction calcScale(page, containerWidth) { // 获取 PDF 原始尺寸scale1 时 const baseViewport page.getViewport({ scale: 1 }); // 用容器宽度除以原始宽度得到适配比例 return containerWidth / baseViewport.width; }但这里有个细节PDF 的原始尺寸单位是 pt1pt 1/72 英寸不同文档的原始宽度可能差很多。A4 纸大概是 595pt 宽但有些扫描件可能是 1000pt 以上。所以不能写死 scale必须动态计算。如果产品要求支持双指缩放那就需要监听 touch 事件动态调整 scale 后重新渲染。但频繁重渲染会卡常见做法是缩放过程中用 CSS transform 做临时缩放手指松开后再按最终 scale 重新渲染一次。这个策略在低端安卓机上能明显减少卡顿。3.3 按需渲染与页面回收一个 50 页的 PDF如果全部渲染内存占用可能超过 500MB移动端直接白屏。我一般用「可视区域 预加载一页」的策略// 用 IntersectionObserver 监听 canvas 是否进入视口 const observer new IntersectionObserver((entries) { entries.forEach(entry { if (entry.isIntersecting) { const pageNum Number(entry.target.dataset.page); renderPage(pdf, pageNum, entry.target, currentScale); } else { // 离开视口超过一定距离清空 canvas 释放内存 const ctx entry.target.getContext(2d); ctx.clearRect(0, 0, entry.target.width, entry.target.height); } }); }, { rootMargin: 200px 0px }); // 上下各预加载 200pxrootMargin设为 200px 意味着提前 200px 开始渲染用户滑动时不会看到空白。离开视口后清空 canvas 是关键否则内存只增不减。这里要注意清空后如果用户滑回来需要重新渲染所以最好用一个 Map 记录每页的渲染状态避免重复渲染。注意IntersectionObserver在部分老版本安卓 WebView 上不支持需要引入 polyfill 或者降级为 scroll 事件监听。降级方案虽然性能差一点但兼容性更稳。4. 避坑与排查中文乱码、跨域、内存泄漏的实战记录pdf.js 用起来不难难的是各种边界情况。这一章记录几个我在真实项目里踩过的坑每条按「现象 → 原因 → 解决」写方便对照排查。4.1 中文显示为方块或乱码现象PDF 里的中文全部显示成空白方块英文和数字正常。原因pdf.js 默认不加载 CJK 字符映射表遇到嵌入字体缺失或者使用标准 CJK 字体的 PDF 就无法正确渲染。解决在getDocument时配置cMapUrl和cMapPacked并把 cmaps 目录放到静态资源服务器上。cmaps 文件在 pdfjs-dist 包的cmaps/目录下直接拷贝到 public 目录即可。配置后中文正常显示。4.2 跨域请求被拦截现象控制台报Access-Control-Allow-Origin错误PDF 加载失败。原因PDF 文件和 H5 页面不在同一个域名下浏览器同源策略拦截。解决服务端配置 CORS 允许对应域名同时注意如果带了httpHeaders预检请求OPTIONS也要返回正确的 header。另一个方案是后端提供接口转发 PDF 流前端用 ArrayBuffer 方式加载这样就不涉及跨域。我一般优先让后端配 CORS实在不行才走转发。4.3 快速翻页导致画面错乱现象连续快速滑动时某一页显示的是上一页的内容或者画面撕裂。原因多个renderTask并发执行后发起的渲染先完成覆盖了前面的结果。解决在渲染新页之前先取消上一页的renderTasklet currentRenderTask null; async function safeRender(pdf, pageNum, canvas, scale) { // 取消上一次未完成的渲染 if (currentRenderTask) { currentRenderTask.cancel(); currentRenderTask null; } const page await pdf.getPage(pageNum); const viewport page.getViewport({ scale }); // ... 设置 canvas 尺寸 currentRenderTask page.render({ canvasContext: ctx, viewport }); try { await currentRenderTask.promise; } catch (e) { // cancel 会抛出 RenderingCancelledException忽略即可 if (e.name ! RenderingCancelledException) throw e; } }4.4 长时间浏览后页面卡顿甚至崩溃现象翻了几十页后滑动明显变卡最后白屏。原因每页的 canvas 都保留在 DOM 里内存持续增长移动端浏览器触发 OOM。解决结合 3.3 的 IntersectionObserver离开视口的 canvas 及时清空并释放引用。另外pdf对象本身也持有资源如果用户退出预览页要调用pdf.destroy()释放。这个在单页应用里尤其重要否则路由切换后内存不会回收。4.5 worker 加载失败导致主线程阻塞现象PDF 能显示但加载过程中页面完全卡死按钮点不动。原因workerSrc路径错误或跨域pdf.js 回退到主线程解析大文件解析时阻塞 UI。解决检查workerSrc是否可访问版本是否与主库一致。如果用了 CDN确认 CDN 支持跨域。本地构建时worker 文件要单独打包并正确配置路径。一个简单的验证方法是在 Network 面板看pdf.worker.min.js是否成功加载状态码 200。5. 进阶技巧文本层叠加、懒加载与移动端手势优化基础功能跑通后如果产品要求「文字可选中复制」或者「支持双指缩放」就需要用到 pdf.js 的文本层和更细的手势控制。这一章讲两个进阶用法都是实际项目里验证过的。5.1 文本层叠加实现可选中pdf.js 渲染的 canvas 本身是图片文字不能选中。要实现选中需要在 canvas 上方叠加一层透明的文本层async function renderTextLayer(page, container, viewport) { // 获取文本内容 const textContent await page.getTextContent(); const textLayerDiv document.createElement(div); textLayerDiv.className textLayer; // 设置文本层尺寸与 canvas 一致 textLayerDiv.style.width viewport.width px; textLayerDiv.style.height viewport.height px; textLayerDiv.style.position absolute; textLayerDiv.style.top 0; textLayerDiv.style.left 0; // 关键文本层本身透明但文字可选中 textLayerDiv.style.opacity 1; textLayerDiv.style.color transparent; container.appendChild(textLayerDiv); // 使用 pdf.js 提供的 renderTextLayer 方法 const textLayer new pdfjsLib.TextLayer({ textContentSource: textContent, container: textLayerDiv, viewport: viewport }); await textLayer.render(); }文本层的原理是把 PDF 里的文字按位置绝对定位到透明 div 上用户选中时看到的是高亮复制出来的是真实文字。这里要注意 CSS 里.textLayer的样式需要配合 pdf.js 的官方样式表否则文字位置会偏移。另外文本层会增加 DOM 节点数量页数多时建议只对当前页渲染文本层。5.2 移动端手势缩放与双击放大双指缩放的核心是监听touchstart、touchmove、touchend计算两指距离变化let initialDistance 0; let initialScale 1; canvas.addEventListener(touchstart, (e) { if (e.touches.length 2) { // 计算两指初始距离 initialDistance Math.hypot( e.touches[0].pageX - e.touches[1].pageX, e.touches[0].pageY - e.touches[1].pageY ); initialScale currentScale; } }); canvas.addEventListener(touchmove, (e) { if (e.touches.length 2) { e.preventDefault(); // 阻止浏览器默认缩放 const distance Math.hypot( e.touches[0].pageX - e.touches[1].pageX, e.touches[0].pageY - e.touches[1].pageY ); // 计算缩放比例限制在 0.5 到 3 倍之间 const newScale Math.min(3, Math.max(0.5, initialScale * (distance / initialDistance))); // 这里只更新 CSS transform不重新渲染 canvas.style.transform scale(${newScale / currentScale}); } }); canvas.addEventListener(touchend, () { // 手指松开后按最终 scale 重新渲染一次保证清晰度 // 具体实现略核心是调用 renderPage 并传入新 scale });这个方案的关键是「缩放过程用 CSS transform松手后再重渲染」。如果每次 touchmove 都重渲染低端机直接卡死。e.preventDefault()必须加否则浏览器会触发页面级别的缩放和 canvas 缩放冲突。提示双击放大可以用dblclick事件但移动端更常见的是监听两次touchend的时间间隔小于 300ms 判定为双击。放大时以点击位置为中心需要计算偏移量否则会跳到左上角。5.3 预加载与缓存策略用户翻到第 5 页时第 6 页应该已经在渲染了。我的做法是维护一个渲染队列当前页渲染完成后立即触发下一页的渲染但优先级低于当前页。同时用一个 Map 缓存已渲染的页面用户往回翻时直接显示缓存不用重新渲染。缓存上限设为 10 页超过后按 LRU 淘汰。这套策略在几个项目里跑下来翻页体验基本和原生应用持平。从那以后我每次接 PDF 预览需求都会先把 worker 路径、cMapUrl、CORS 这三项检查一遍再开始写渲染逻辑。这三个地方不出问题后面基本就顺了。希望帮到你。本文还有配套的精品资源点击获取
