简介这是一份基于 Mozilla 开源库 PDF.js 的 H5 在线 PDF 展示资源包面向需要在网页中直接渲染、缩放和浏览 PDF 文档的 Web 前端开发者也适用于移动端 H5 项目集成解决 HTML5 原生不支持解析 PDF 的问题。PDF.js 通过解析器将 PDF 内容转换为可绘图数据再利用 Canvas 画布分页渲染并提供文本选择、缩放、平移、搜索等交互能力无需安装任何浏览器插件。压缩包内含四百零二个文件体积约三点六七兆字节。文件类型以字体映射表、配置属性、位图与矢量图标为主其中一百六十八份字体映射表负责字符定位一百二十四份配置属性用于渲染参数八十六个位图图标与九个矢量图标提供界面支持同时包含脚本、样式、示例页面和 PDF 样例完整覆盖 PDF.js 运行所需资源。已有 1224 人学习/下载。借助该压缩包可快速理解网页渲染 PDF 的完整流程也可直接用作项目基础库按需定制界面主题与功能实现在 H5 页面中流畅地在线阅读 PDF 文档。1. H5 里自动展示 PDF为什么绕不开 pdf.js做 H5 时“自动展示”PDF 是一个很容易被低估的需求。合同、电子发票、产品说明书页面加载完就要整整齐齐出现在用户面前不要用户点击也不要引导下载。最省事的方案是丢一个 iframe 或新开标签页让浏览器自己处理但真放到线上会发现iOS 上还好Android WebView 多数直接变成下载微信内置浏览器还会拦截就算能打开不同内核版本表现也不一样等于把不确定的黑匣子交给用户。pdf.js 能把这种不一致兜住。它负责解析 PDF 并用 canvas 画出来加载进度、缩放、失败兜底全在业务代码掌握里。下面从选型原理讲到最小 Demo再给出移动端参数调优和常见坑适合要把 PDF 自动展示做进 H5、又不想被浏览器内核折腾的开发者。2. pdf.js 选型与渲染原理为何 canvas 渲染比 iframe 可靠2.1 只靠 iframe 或 embed 在移动端为什么容易翻车H5 里想要“自动展示” PDF最容易想到的是嵌套一个 iframe把后端返回的 PDF 地址丢进去或者用 embed、object 标签。在带原生预览能力的桌面浏览器上这通常没问题但移动端是另一个世界。先看 iOSSafari 对 application/pdf 的支持相对好但展示的是系统级预览控件页面里顶着一个陌生工具栏视觉和交互跟你的 H5 完全割裂导航按钮、缩放逻辑都是系统定的。想要“自动展示”并自定义头尾内容几乎做不到。Android 分裂更明显。不同厂商的 WebView 对 PDF 的响应要么交给下载管理器要么套一个简版预览有的内核直接不识别。到了微信内置浏览器和各类 App 的 webviewiframe 嵌套 PDF 大概率会白屏或弹下载框。你无法预知用户会被引导到哪个流程。还有个隐藏问题接口鉴权。很多 PDF 地址需要带自定义请求头或 Cookie 才能访问iframe 加载一个 URL 只能发普通 GET不能设置 Header如果后端要求 token前端只能把 token 拼到 query 里一旦日志泄露PDF 地址也就暴露了。结论很直接浏览器原生行为差异太大想稳定地把 PDF 当内容展示就得自己掌握渲染层。pdf.js 把 PDF 文件解析成页面对象再通过 canvas 绘制展示过程完全受页面代码控制UI 一致进度可做失败可兜底。对 H5 来说它是最常规的落地方案。2.2 引入 pdf.js 的两种常见姿势CDN 与 npm 本地打包pdf.js 的发布产物里有几个文件不能少主库脚本、worker 脚本、可选的中文字体映射目录 cmaps 和标准字体目录 standard_fonts。引入方式直接影响 worker 路径和静态资源部署这里分两种常见姿势。CDN 方式适合快速验证和内网项目HTML 里先引主库再设 worker 路径script srchttps://your-cdn.example.com/pdfjs/pdf.min.js/script script pdfjsLib.GlobalWorkerOptions.workerSrc https://your-cdn.example.com/pdfjs/pdf.worker.min.js; /script注意两点一是 workerSrc 必须指向能访问到的实际文件且域名要与页面同源或已放开 CORS否则 worker 加载失败getDocument 一直转圈或白屏二是 CDN 上通常只放了压缩后的主库和 workercmaps、standard_fonts 是单独目录需要一并上传到静态服务否则遇到特定字体编码的 PDF 照样乱码。npm 方式适合工程化项目主库通过 import 引入。常见做法是把 pdfjs-dist 作为依赖然后在入口设置 workerSrcimport * as pdfjsLib from pdfjs-dist; pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.js, import.meta.url ).toString();这段代码依赖构建工具把 worker 文件当作静态资源拷到输出目录。不同版本构建输出的文件名略有差异有的带 hash有的不带你应当以 node_modules 里实际文件名为准。npm 方式的优点是路径跟着构建走不容易写错配合哈希文件名也能更好地处理缓存。怎么选我的判断标准很简单POC 阶段用 CDN五分钟能跑出效果要上线的项目一律 npm 打包离线场景和内网环境更可控。无论哪种都不要只引主库忘了 worker这是后面白屏高发原因之一。2.3 渲染链路拆解从 getDocument 到 canvas 绘制pdf.js 的渲染链路可以拆成四步解析文档、获取页面、计算视口、绘制画布。先看一段核心代码const loadingTask pdfjsLib.getDocument({ url: pdfUrl }); const pdf await loadingTask.promise; const page await pdf.getPage(1); const viewport page.getViewport({ scale: 1.5 }); const canvas document.getElementById(pdf-canvas); canvas.width viewport.width; canvas.height viewport.height; const context canvas.getContext(2d); const renderTask page.render({ canvasContext: context, viewport }); await renderTask.promise;第一步 getDocument 返回的是一个 loadingTask不只接受 url也接受 dataArrayBuffer 或 Uint8Array、range 等。url 方式最省事但没法自定义请求头鉴权受限制data 方式适合先 fetch 再渲染。loadingTask 上可以挂 onProgress 拿加载进度也可以调用 cancel 中断这一点在展示大文件时很有用。第二步 getPage(n) 的页码从 1 开始不是数组下标初学容易在这里拿到 undefined 或报错。拿到 page 对象后页面宽度、高度、字体信息都已解析完成真正绘制要靠 viewport。第三步 getViewport({ scale }) 是理解 pdf.js 布局的关键。PDF 内部坐标单位是 point1 point 约等于 1/72 英寸。scale1 时一个 595×842 的 A4 页渲染出来就是 595×842 CSS 像素。要占满容器宽度需要按容器宽度反推比例要适配高清屏还要再乘以 devicePixelRatio这部分下一章展开。第四步 page.render 接受 canvasContext 和 viewport返回一个 RenderTask。不要忽略 promise渲染是异步的中途页面切换时最好保存 renderTask 并在下次渲染前 cancel否则可能出现旧页面画完覆盖新页面的诡异现象这也是常见“白屏/错页”的原因之一。理清这四个环节后去看报错会更有头绪文档解析挂掉多半是 worker 或跨域取页报错多半是页码边界画出来模糊多半是 canvas 尺寸与 viewport 不匹配。后面几章会顺着这些线索逐个展开。对比项iframe / embedpdf.js加载逻辑浏览器内核决定页面代码自控自定义 UI基本不可控完全可控带 Header 鉴权不支持通过 fetch data移动端一致性差好实现成本低中等需配置参数3. 用 pdf.js 在 H5 跑通最小 Demo从零到自动展示第一页3.1 基础页面结构与最小渲染代码先做一个能跑的最小页面页面加载完成就自动解析指定 PDF并把第一页画到 canvas 上。下面这段代码可以直接保存成 HTML 文件替换 PDF 地址后打开看效果。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleH5 自动展示 PDF/title style #pdf-container { width: 100%; box-sizing: border-box; padding: 12px; background: #f5f5f5; } #pdf-container canvas { width: 100%; height: auto; background: #fff; box-shadow: 0 2px 8px rgba(0,0,0,0.15); } /style /head body div idpdf-container canvas idpdf-canvas/canvas /div script srchttps://your-cdn.example.com/pdfjs/pdf.min.js/script script pdfjsLib.GlobalWorkerOptions.workerSrc https://your-cdn.example.com/pdfjs/pdf.worker.min.js; const pdfUrl /static/example.pdf; async function renderPdf(url) { try { const loadingTask pdfjsLib.getDocument(url); const pdf await loadingTask.promise; const page await pdf.getPage(1); const viewport page.getViewport({ scale: 1.5 }); const canvas document.getElementById(pdf-canvas); canvas.width viewport.width; canvas.height viewport.height; const context canvas.getContext(2d); await page.render({ canvasContext: context, viewport }).promise; } catch (err) { console.error(PDF 渲染失败, err); } } renderPdf(pdfUrl); /script /body /html逻辑说明renderPdf 在页面加载后立即调用这就是“自动展示”的起点。代码里先创建 loadingTask拿到 pdf 文档对象再取第 1 页。注意 getPage 的入参是页码从 1 开始很多初次接手的开发者在这一步传 0 导致报错。viewport 决定渲染尺寸scale 设成 1.5 是一个临时粗值真正的自适应算法在 3.2 节说明。参数说明GlobalWorkerOptions.workerSrc 是全局配置必须在使用 getDocument 之前赋值。canvas.width 和 canvas.height 是画布物理像素尺寸viewport.width 是 PDF 在当前 scale 下的像素宽度。这里刻意没有设置 style 宽高是为了让 canvas 按实际尺寸撑开容器移动端首次验证最容易跑通的形态就是这种。3.2 让 PDF 自动铺满一屏scale 与容器宽度换算固定 scale 最大的问题是不同手机屏宽不同375px 的 iPhone 和 414px 的安卓机渲染出来可能一屏放不下或者留白太多。要做自动展示第一步就是让 PDF 宽度跟随容器宽度。const container document.getElementById(pdf-container); const canvas document.getElementById(pdf-canvas); const dpr window.devicePixelRatio || 1; async function fillPage(page) { // 先以 scale1 拿到 PDF 原始宽度 const baseViewport page.getViewport({ scale: 1 }); // 为了让 canvas 物理像素足够要乘 dpr const scale (container.clientWidth / baseViewport.width) * dpr; const viewport page.getViewport({ scale }); canvas.width viewport.width; canvas.height viewport.height; // style 宽度保持 CSS 像素避免被容器拉伸 canvas.style.width ${container.clientWidth}px; canvas.style.height ${(viewport.height / viewport.width) * container.clientWidth}px; const context canvas.getContext(2d); await page.render({ canvasContext: context, viewport }).promise; }逻辑说明先取 scale1 的 viewportPDF 宽度除以容器宽度得到一个基础比例再乘 dpr最终渲染出来的 canvas 物理像素够清晰。canvas.style.width 必须用容器宽度不能写成 100%否则某些 WebView 里 canvas 会被 CSS 拉伸视觉比例和实际渲染尺寸脱节。参数说明container.clientWidth 在页面刚加载时可能为 0如果 canvas 渲染发生在图片、字体或异步数据之后要在实际拿到宽度后再调用。另一个细节是 dpr 在部分 Android WebView 上可能被厂商放大导致页面整体模糊此时可以用一个上限保护比如Math.min(dpr, 2.5)避免低端机渲染超大 canvas 直接卡死。3.3 加载进度与失败兜底让用户能看到状态自动展示不代表闷头加载。PDF 文件可能几 MB 甚至几十 MB用户盯着空白页容易流失。体验上至少要有一条进度条和一个失败重试入口。div idprogress-wrap div idprogress-bar/div /div div idfallback styledisplay:none; 加载失败请检查网络后 button idretry-btn重新加载/button /divconst loadingTask pdfjsLib.getDocument({ url: pdfUrl }); loadingTask.onProgress (progress) { if (progress.total 0) { const percent Math.min(100, Math.round((progress.loaded / progress.total) * 100)); progressBar.style.width ${percent}%; } }; try { const pdf await loadingTask.promise; // 拿到 pdf 后再执行 3.2 里的 fillPage await fillPage(await pdf.getPage(1)); } catch (err) { fallback.style.display block; retryBtn.addEventListener(click, () { fallback.style.display none; renderPdf(pdfUrl); }); }逻辑说明loadingTask.onProgress 会在下载过程中多次回调progress.loaded 是已加载字节数progress.total 是总量。total 可能为 0比如服务端没返回 Content-Length所以要加一层判断否则进度条会变成 NaN。失败兜底放到 catch 里用 display 控制显隐点击重试时重新执行整条加载链路。参数说明进度条宽度用百分比更新时注意要给进度条容器设置固定宽度和 overflow hidden否则内层 div 变宽后页面会出现横向滚动条。实际项目中我一般还会加一个超时控制用 Promise.race 包住 loadingTask.promise15 秒没完成就主动 cancel避免用户一直挂在转圈界面。4. 移动端适配与参数调优把 scale、worker、cMap 一次调对4.1 scale 与 devicePixelRatio为什么 canvas 老是发虚移动端 canvas 发虚是最高频的观感问题根源在于 canvas 的物理像素和 CSS 像素不一致。很多实现只写canvas.style.width 100%画布内部实际尺寸可能只有 375px但屏幕物理像素是 750px浏览器放大后文字边缘发虚。正确关系是canvas.width 和 canvas.height 决定绘图缓冲区大小style.width 和 style.height 决定浏览器绘制大小。想要清晰缓冲区至少要等于 CSS 尺寸乘以设备像素比。function buildViewport(page, containerWidth) { const dpr window.devicePixelRatio || 1; const baseViewport page.getViewport({ scale: 1 }); const scale (containerWidth / baseViewport.width) * dpr; const maxScale 4 * dpr; // 防止超大页面把 canvas 面积撑爆 return page.getViewport({ scale: Math.min(scale, maxScale) }); }参数说明maxScale 的取值和生产环境相关4 倍 dpr 大约对应最大 8 倍缩放足够应付绝大多数合同和说明书。scale 过大会让 canvas 面积变成原来的平方倍低端 Android 机渲染一整页 A4 可能要好几秒这就是要限制上限的原因。另一个容易忽略的点是canvas 会受 CSS transform 影响。如果外层容器做了缩放动画canvas 内部尺寸不变但 UI 上看起来会发虚或截断。自动展示场景里尽量减少对 canvas 父容器的 scale 动画用重新计算 scale 代替。4.2 worker、cMap 与标准字体中文 PDF 的隐性依赖worker 是 pdf.js 的解析线程。如果 worker 加载失败解析会退回主线程小文件还能忍受大文件直接卡掉交互。常见的部署错误是主库和 worker 文件放在不同 CDN 域名且未配置 CORS浏览器拦截 worker 脚本后 getDocument 一直 pending。worker 的配置必须在使用 getDocument 前完成pdfjsLib.GlobalWorkerOptions.workerSrc /pdfjs/pdf.worker.min.js;如果页面运行在文件协议下或业务域名和静态资源域名跨域worker 同样可能失败。解决办法是把 worker 文件放到同域或通过 fetch 获取文件内容后用 Blob URL 创建 worker。后者虽然麻烦但内网系统里经常用到。cMap 和 standardFontDataUrl 是更隐蔽的问题。部分 PDF 使用 CID 字体渲染时需要在 cmaps 目录里查字体映射。如果缺失现象不是直接报错而是文字变成方块、乱码或者某些字符空白。const loadingTask pdfjsLib.getDocument({ url: pdfUrl, cMapUrl: /pdfjs/cmaps/, cMapPacked: true, standardFontDataUrl: /pdfjs/standard_fonts/ });参数说明cMapUrl 路径末尾必须带斜杠cMapPacked 对应压缩过的 .bcmap 文件standardFontDataUrl 指向标准字体数据目录。这三者与主库、worker 一样都是构建产物的一部分。我的习惯是无论 PDF 内容是否涉及生僻字体上线时都配齐这些目录否则遇到某类字体就只有后悔药没有后悔机会。4.3 分页加载与渲染任务取消内存与渲染卡顿的平衡一个 PDF 二十页如果全部渲染成 canvas 并保留在 DOM 里内存占用会非常可观。移动端 WebView 的内存上限通常不如桌面端页面一旦被系统杀掉表现为白屏或者直接退出。比较好的策略是只渲染当前可见的一页或两页滚动翻页时先取消旧的渲染任务再渲染新页。这样内存里最多保留几个 canvas。let currentRenderTask null; async function renderPage(pdf, pageNumber, containerWidth) { if (currentRenderTask) { currentRenderTask.cancel(); } const page await pdf.getPage(pageNumber); const viewport buildViewport(page, containerWidth); canvas.width viewport.width; canvas.height viewport.height; canvas.style.width ${containerWidth}px; canvas.style.height ${(viewport.height / viewport.width) * containerWidth}px; currentRenderTask page.render({ canvasContext: canvas.getContext(2d), viewport }); await currentRenderTask.promise; }逻辑说明每次渲染前先 cancel 旧任务避免两次渲染结果错乱。RenderTask.cancel() 之后旧的 promise 会 reject所以调用处要 catch 住这个错误不能在控制台留下红色的 Uncaught Error。页面销毁时调用 pdf.destroy()释放解析后的字体和图片缓存。参数说明如果做缩略图列表不要让每个缩略图都持有独立 canvas。常见做法是复用固定数量的 canvas 节点超出部分直接移除或用离屏 canvas 先绘制再转成图片。缩略图不追求高清scale 可以降到 0.3 左右能大大降低低端机的压力。5. pdf.js 在 H5 里的踩坑与排查清单5.1 白屏不渲染worker 文件没加载到位现象页面打开后容器区域一片空白控制台没有明显的语法错误getDocument 的 promise 一直 pending 或报 “Setting up fake worker failed”。原因GlobalWorkerOptions.workerSrc 配置的路径不对或者 worker 文件与页面跨域且服务端没有放行 CORS。最常见的是 CDN 只放了主库 pdf.min.js忘了上传 pdf.worker.min.js路径 404 后 pdf.js 尝试用主线程 fake worker渲染不稳定。解决先打开网络面板确认 pdf.worker.min.js 的请求状态。404 就把 worker 文件放到同域静态目录路径写成绝对路径如果是跨域让静态服务在响应头加上 Access-Control-Allow-Origin。配置完成后强制刷新页面再试。5.2 中文乱码或空白字形cMap 与 standardFontDataUrl 缺失现象页面能渲染但某些文字变成方框、乱码或者一段文字中部分字符消失。更奇怪的是同一个 PDF 在一台手机上正常在另一台手机上字体错位。原因PDF 里的 CID 字体需要 cMap 数据做字符映射缺少映射文件时 pdf.js 只能猜测字形另一个相关因素是标准字体数据所在目录没有部署导致某些内嵌字体回退失败。解决确认 PDF 文件里字体是嵌入的还是非嵌入的如果非嵌入标准字体必须配置 standardFontDataUrl。按 4.2 节的方式把 cMap 和 standard_fonts 两个目录部署到静态服务并在 getDocument 参数里写明路径。注意路径末尾斜杠不要拼成/cmaps少一个斜杠。5.3 画出来明显发虚canvas 尺寸没跟上物理像素现象文字边缘发虚用手机截图放大后模糊但在 PC 浏览器开发者工具里看很清晰。原因开发者工具默认模拟 dpr1纯 CSS 横向上看不出问题。真机 dpr 是 2 或 3canvas.width 如果只按 CSS 像素设置缓冲区像素不足设备缩放后就虚了。解决统一按下述公式处理scale (容器宽度 / PDF 基础宽度) * dprcanvas.width viewport.widthcanvas.height viewport.height同时 style.width 用容器 CSS 宽度。手机上看不到的 PC 模拟问题建议直接用真机预览或者打开浏览器移动端模拟器并设置 devicePixelRatio 为 3。5.4 大 PDF 内存飞升渲染任务没取消、文档没释放现象连续翻页后页面越来越卡最后 WebView 崩溃。查看任务管理器浏览器进程内存持续上涨不会回落。原因代码里每次翻页都创建新的 RenderTask旧的还没有完成就执行新的渲染多个渲染任务叠加或者每页都创建新 canvas 并追加到 DOM页面切换时没有移除canvas 占用的内存不会自动释放。解决翻页前保存并 cancel 当前 RenderTask已经渲染完成的 canvas 在不可见时移除或复用。整个 PDF 不再需要时调用 pdf.destroy()。这里还有一个小坑renderPage 里await currentRenderTask.promise被 cancel 后会抛错调用处必须加 try/catch否则路由切换后控制台会残留未捕获错误。5.5 带鉴权 PDF 加载 403url 方式带不了自定义 Header现象页面请求 PDF 返回 403but 后端接口用 Postman 或浏览器直接访问是正常的因为登录态在 Cookie 或 Header 里。原因pdf.js 的 getDocument({ url }) 底层是普通 fetch它的请求头由浏览器决定。如果后端要求 Authorization 或其他自定义 headerurl 方式无法传入。解决先自己 fetch 拿到 ArrayBuffer再走 data 模式const response await fetch(pdfUrl, { headers: { Authorization: Bearer ${token} } }); const arrayBuffer await response.arrayBuffer(); const loadingTask pdfjsLib.getDocument({ data: arrayBuffer });注意这种方案会把整个 PDF 先下载到内存大文件建议展示一个加载状态。后端如果支持 Range 请求可以用 pdfjsLib 的 range 模式分片加载但实现成本更高项目早期先整体下载更可靠。6. 进阶玩法按需渲染与上线前的验证清单6.1 用 IntersectionObserver 实现按需渲染多页 PDF 的自动展示不一定要一次把所有页面都画出来。常见做法是每个页面放一个占位节点用 IntersectionObserver 监听是否进入视口进入后再调用渲染逻辑。const observer new IntersectionObserver((entries) { entries.forEach(entry { if (entry.isIntersecting) { const pageNum Number(entry.target.dataset.page); renderPage(pdf, pageNum, containerWidth); observer.unobserve(entry.target); } }); }, { root: scrollContainer, threshold: 0.1 });页面结构里给每个占位 div 加上 style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />