简介：这份资源面向需要在H5页面中嵌入PDF预览功能的Web前端开发者，基于Mozilla开源的PDF.js库，解决HTML5原生无法直接展示PDF的痛点，让用户无需安装插件即可在网页内流畅查看PDF内容。压缩包共402个文件，约3.67MB，以168个bcmap字符映射文件、124个properties配置、86个png与9个svg界面素材为主，另含4个js核心脚本、3个map、2个cur光标、1个css样式及1个html示例页，覆盖字体编码、界面资源与渲染逻辑等模块。目前已有1224人学习下载。借助其中的库文件、示例页面与文档，读者可快速掌握PDF加载、解析、Canvas分页渲染及缩放、平移、搜索等交互实现，并了解Web Worker后台解析的优化思路，适合作为H5在线PDF阅读器的集成参考。
1. 移动端直接预览 PDF 的痛点：为什么我最后选了 pdf.js
做过 H5 项目的人大概率都碰过这个需求：后端丢过来一个 PDF 链接，产品要求点开就能看，最好还能翻页、缩放、跳页。第一反应往往是直接<iframe src="xxx.pdf">或者window.open，桌面浏览器上跑得挺欢，一上手机就原形毕露——iOS Safari 要么白屏，要么只渲染第一页，安卓各家 WebView 表现更是玄学，有的直接触发下载，有的把 PDF 丢给系统阅读器跳走了，页面上下文全丢。
这个坑我踩过不止一次。后来固定下来的方案就是 pdf.js，Mozilla 出的纯前端 PDF 渲染库，把 PDF 解析成 Canvas 逐页画出来，不依赖浏览器原生 PDF 插件，行为完全可控。它解决的核心问题就一个：让 PDF 在 H5 里变成你能操控的 DOM 和 Canvas，而不是一个黑匣子。适合谁？做移动端文档预览、合同签署、课件阅读、发票查看这类场景的前端，尤其是需要自定义工具栏、埋点、加水印的团队。
2. pdf.js 的渲染原理与工程化选型：从解析到 Canvas 落屏
pdf.js 不是简单地把 PDF 当图片塞进页面，它内部走了一条完整的链路：读取 PDF 二进制 → 解析对象结构（xref 交叉引用表、对象流、字体、图像）→ 构建页面操作符列表 → 交给 Canvas 2D 上下文逐条绘制。理解这条链路，才能明白后面为什么会有跨域、字体、内存这些坑。
2.1 核心对象与渲染流程
pdf.js 暴露出来的关键对象有几个，用熟了基本就够：
pdfjsLib.getDocument(url)：拿到PDFDocumentProxy，这是整个文档的入口，能读页数、元数据、逐页取PDFPageProxy。page.getViewport({ scale })：算出这一页在给定缩放下的宽高，Canvas 尺寸就靠它。page.render({ canvasContext, viewport })：真正把内容画到 Canvas 上，返回一个RenderTask，可以cancel()。
渲染是异步且分页的，一页一个 Canvas。移动端内存紧张，所以工程上不会一次性把所有页都渲染出来，常见做法是只渲染当前页和前后各一页，滚动时动态替换。这就是为什么很多成熟方案里你会看到「虚拟滚动 + 按需渲染」的组合。
2.2 三种引入方式的取舍
pdf.js 的引入方式直接决定了你后面踩坑的多少，我一般按项目形态选：
| 引入方式 | 适用场景 | 注意点 |
|---|---|---|
| CDN 直接 script 引入 | 快速验证、demo | 版本要锁死，别用 latest |
npm 安装pdfjs-dist | 现代打包项目（Vite/Webpack） | 要处理 worker 路径 |
| 源码构建自定义 | 需要裁剪体积、改默认行为 | 构建成本高，一般用不上 |
绝大多数 H5 项目走第二种。pdfjs-dist是官方发布的 npm 包，版本和 API 对得上，比满世界找 CDN 靠谱。下面这段是 Vite 项目里的标准接法：
// 引入主库和 worker import * as pdfjsLib from 'pdfjs-dist'; // worker 用 ?url 让打包器处理成独立资源，避免路径 404 import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url'; // 关键一步：指定 worker 地址，不指定会退化到主线程，卡到怀疑人生 pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl; // 加载文档 const loadingTask = pdfjsLib.getDocument({ url: '/files/sample.pdf', // 关闭自动取字体，移动端可减少请求 disableFontFace: false, }); const pdf = await loadingTask.promise; console.log('总页数', pdf.numPages);逻辑说明：GlobalWorkerOptions.workerSrc是必须配的，pdf.js 把解析这种重活丢给 Web Worker，主线程只负责绘制，不配的话解析全压在主线程，长文档直接卡死。参数上disableFontFace默认 false，保持字体正常渲染；如果你的 PDF 字体特别多又不在乎显示精度，可以设 true 省点开销。getDocument还接受cMapUrl、cMapPacked用于中文等 CJK 字体的映射，中文 PDF 乱码时基本就是这里没配。
2.3 单页渲染的最小可用代码
拿到pdf对象后，渲染一页的完整流程如下：
async function renderPage(pdf, pageNum, canvas, scale = 1.5) { const page = await pdf.getPage(pageNum); // 根据设备像素比放大，避免高清屏发虚 const dpr = window.devicePixelRatio || 1; const viewport = page.getViewport({ scale: scale * dpr }); const ctx = canvas.getContext('2d'); // Canvas 实际像素尺寸 canvas.width = viewport.width; canvas.height = viewport.height; // CSS 尺寸还原成逻辑尺寸，否则会显示得巨大 canvas.style.width = `${viewport.width / dpr}px`; canvas.style.height = `${viewport.height / dpr}px`; const renderTask = page.render({ canvasContext: ctx, viewport, }); await renderTask.promise; return renderTask; }逻辑说明：这里最容易翻车的是 DPR 处理。Canvas 的width/height是绘制缓冲区尺寸，style.width/height是显示尺寸，两者不分开设，高清屏上要么糊要么大得离谱。scale我一般给 1.5 起步，配合 DPR 后清晰度够用，再大内存吃不消。renderTask要留着，页面切换时调cancel()，不然上一页还在画，新页已经上来，会出现画面错乱。
3. 翻页、缩放与手势：把预览器做成能用的交互
光能渲染一页不算完，用户要的是能翻、能缩、能跳。这一章把交互层补齐，也是 H5 场景下体验差距最大的地方。
3.1 翻页与页码状态管理
翻页本质就是换pageNum重新渲染。但直接换会闪，常见做法是维护一个当前页状态，配合上一页/下一页按钮和滚动监听：
let currentPage = 1; const totalPages = pdf.numPages; async function goToPage(num) { if (num < 1 || num > totalPages) return; // 取消上一页未完成的渲染任务 if (window.__currentTask) { window.__currentTask.cancel(); } currentPage = num; const task = await renderPage(pdf, num, canvasEl, 1.5); window.__currentTask = task; // 更新页码显示 pageIndicator.textContent = `${num} / ${totalPages}`; } prevBtn.onclick = () => goToPage(currentPage - 1); nextBtn.onclick = () => goToPage(currentPage + 1);逻辑说明：cancel()那一步是血泪经验，不取消的话快速连点会同时跑好几个渲染任务，内存飙升，低端机直接崩。页码状态单独存，别从 DOM 里读，读出来的是字符串还得转。totalPages从pdf.numPages拿，别自己数。
3.2 双指缩放与手势冲突处理
移动端缩放有两种思路：改scale重新渲染（清晰但重），或者用 CSStransform缩放 Canvas（快但放大后糊）。我一般折中——双指过程中用 CSS 缩放给即时反馈，手势结束后按最终比例重新渲染一次。
let pinchStartDist = 0; let baseScale = 1.5; canvasEl.addEventListener('touchstart', (e) => { if (e.touches.length === 2) { // 记录双指初始距离 pinchStartDist = Math.hypot( e.touches[0].clientX - e.touches[1].clientX, e.touches[0].clientY - e.touches[1].clientY ); } }); canvasEl.addEventListener('touchmove', (e) => { if (e.touches.length === 2 && pinchStartDist > 0) { const dist = Math.hypot( e.touches[0].clientX - e.touches[1].clientX, e.touches[0].clientY - e.touches[1].clientY ); const ratio = dist / pinchStartDist; // 实时用 CSS 缩放，限制范围防止失控 const visual = Math.min(Math.max(ratio, 0.5), 3); canvasEl.style.transform = `scale(${visual})`; } }); canvasEl.addEventListener('touchend', async () => { // 手势结束，按最终比例重渲染，保证清晰 const match = canvasEl.style.transform.match(/scale\(([\d.]+)\)/); if (match) { baseScale = baseScale * parseFloat(match[1]); canvasEl.style.transform = ''; await renderPage(pdf, currentPage, canvasEl, baseScale); } pinchStartDist = 0; });逻辑说明：touchmove里只改transform不重渲染，是为了跟手，重渲染有延迟会顿。touchend里把视觉缩放折算进baseScale再重画一次，兼顾流畅和清晰。缩放范围限制在 0.5 到 3 倍，超出范围用户会迷失。注意touchmove要配合passive: false和preventDefault才能阻止页面整体滚动，否则缩放手势会带着页面一起动。
3.3 工具栏与常用功能挂载
一个能用的预览器，工具栏至少要有：页码跳转、缩放加减、下载/打印入口。这些不复杂，但要注意别把 pdf.js 的渲染和 UI 状态耦合死。我习惯把pdf、currentPage、scale收在一个模块级对象里，UI 只读不写，改状态统一走goToPage和setScale两个函数。这样后面加埋点、加水印、加批注都有地方插。
4. 避坑与排查：pdf.js 在 H5 上最容易翻车的五件事
这一章全是实打实踩出来的，按「现象 → 原因 → 解决」写，遇到问题对着查。
4.1 中文 PDF 显示成方块或乱码
现象：英文 PDF 正常，中文 PDF 打开后文字全是方块或者干脆不显示。
原因：pdf.js 默认不带 CJK 字体的字符映射表（CMap），遇到用非标准编码的中文 PDF 就认不出来。
解决：在getDocument里显式指定cMapUrl和cMapPacked，把官方提供的 cmaps 目录挂上去：
const pdf = await pdfjsLib.getDocument({ url: '/files/cn.pdf', cMapUrl: '/cmaps/', // 把 pdfjs-dist/cmaps 拷到静态目录 cMapPacked: true, }).promise;cmaps目录在pdfjs-dist包里就有，构建时拷到 public 下即可。这一步不做，中文项目基本必翻车。
4.2 跨域 PDF 加载失败
现象：控制台报Failed to fetch或CORS，本地文件能开，线上链接不行。
原因：pdf.js 用 fetch/XHR 拉 PDF 二进制，跨域资源没带 CORS 头就被浏览器拦。
解决：让后端在 PDF 响应上加Access-Control-Allow-Origin，或者走同源代理转发。别想着前端绕，绕不过去。如果 PDF 是 base64 或 ArrayBuffer，用getDocument({ data })直接传数据，能避开跨域，但要注意大文件转 base64 内存翻倍。
4.3 长文档内存暴涨甚至崩溃
现象：几十页的 PDF 翻到后面越来越卡，最后页面白屏或标签页崩溃。
原因：每页都创建 Canvas 且不释放，加上渲染任务没取消，内存只增不减。
解决：只保留当前页和相邻页的 Canvas，其余页canvas.width = 0; canvas.height = 0主动释放；切换页面前cancel()掉未完成的renderTask；scale别设太大，1.5 到 2 之间够用。低端安卓机尤其要注意，DPR 高的时候缓冲区尺寸是成倍涨的。
4.4 worker 路径 404 导致主线程卡死
现象：页面能渲染但滚动、点击都卡，长文档尤其明显。
原因：workerSrc没配或路径错，pdf.js 静默退化到主线程解析。
解决：确认GlobalWorkerOptions.workerSrc指向真实可访问的 worker 文件。用打包器时通过?url或new URL(...)让构建工具处理路径，别手写相对路径。上线后打开 Network 面板看 worker 文件有没有 200。
4.5 iOS 上 Canvas 尺寸超限白屏
现象：iOS Safari 上大尺寸 PDF 渲染出来一片白，安卓正常。
原因：iOS 对单个 Canvas 的像素面积有上限（约 1670 万像素），超过就不画。
解决：限制scale * dpr的乘积，或者对大页面分块渲染。简单做法是给 viewport 算出来的宽高加个上限判断，超了就降 scale。这个坑很隐蔽，因为不报错，就是白。
5. 进阶技巧：文本层、水印与按需加载的落地细节
基础预览跑通后，真正拉开差距的是这几个进阶点。先说文本层——pdf.js 除了画 Canvas，还能生成一层透明的文本 DOM，叠在 Canvas 上，这样用户就能选中、复制、搜索 PDF 里的文字。做法是page.getTextContent()拿到文本项，再配合pdfjsLib.renderTextLayer渲染。移动端如果不需要选中，可以省掉这层，能省不少 DOM 节点。
水印我一般不用改 PDF 源文件，直接在 Canvas 渲染完成后用ctx.fillText叠一层，或者用一个绝对定位的 DOM 层盖上去。DOM 层的好处是能跟着缩放走，坏处是截图能截到——真要防截图得在服务端做。按需加载则是把「只渲染可视区域」做扎实：监听滚动容器，算出当前视口对应第几页，只渲染那一页和前后各一页，其余页用占位 div 撑高度。这套组合下来，几百页的 PDF 在手机上也能滑得动。
验证方法很简单：拿一份 200 页以上的中文 PDF，在低端安卓机上从头滑到尾，看内存曲线是否平稳、有没有白屏、文字是否正常。我习惯用 Chrome 远程调试连真机，Performance 面板录一段，重点看 JS heap 有没有持续爬升。爬升就是没释放，回去查 Canvas 和 renderTask。
从那以后我每次接 PDF 预览需求，都强制先跑一遍这份检查清单：worker 配没配、cmaps 带没带、DPR 处理对不对、cancel 有没有调、iOS 尺寸限没限。这五条过完，基本就不会在上线后被打回。希望帮到你。
本文还有配套的精品资源，点击获取
