简介：面向Web前端开发者的PDF.js完整资源包，用于在浏览器中无需下载即可实现PDF文档在线预览、翻页与渲染。资源围绕Mozilla开源的PDF.js库整理，包含核心JavaScript库、HTML示例页面、CSS样式、示例PDF及配套字体映射文件（bcmap），并提供大量png/svg图标与界面素材。全包共402个文件、压缩后约3.06MB，其中168个bcmap文件覆盖UniGB、UniJIS等字符集，另有4个js、3个map及1个css用于调试与样式控制，目录结构完整，可直接部署或二次开发。目前已有3142人学习下载，适合需要快速集成PDF预览功能、研究Canvas渲染原理或构建在线文档系统的中高级前端开发者。通过示例可掌握PDF.js的引入、文档加载、多页渲染、进度监听、缩放操作及Web Worker后台解析等关键用法，并参考license文件了解商用注意事项。
1. 用 JavaScript 在线查看 PDF：先想清楚方案再写代码
要在网页里直接查看 PDF，很多人的第一反应是扔一个 iframe 完事。实际接需求时你会发现，客户要的是类似阅读器的体验：能翻页、能缩放、能知道加载到第几页，甚至要记住上次看到的位置。这个用纯 JavaScript 解析渲染 PDF 的需求，核心解法是围绕一个开源解析库（pdf.js）做封装：它把 PDF 文件解码成页面对象，再通过 canvas 把每一页画出来。下面这套方案从原理到踩坑拆开讲，适合前端工程师、以及要给系统做文件预览功能的开发者。你会发现，真正决定效果的往往不是渲染函数，而是缓存、尺度处理和资源释放。
2. 深入 pdf.js 的渲染管线：从 URL 到 canvas 的每一步
2.1 加载与解析：从 URL 到 PDFDocumentProxy
先用 script 标签引入解析库的时候，全局会挂一个pdfjsLib对象。初始化 worker 和加载文档的代码通常长这样：
<script src="/vendor/pdf.min.js"></script>const pdfjsLib = window.pdfjsLib; pdfjsLib.GlobalWorkerOptions.workerSrc = '/vendor/pdf.worker.js'; const loadingTask = pdfjsLib.getDocument({ url: '/files/contract.pdf', withCredentials: false, onProgress: (data) => { if (data.total > 0) { const percent = Math.round((data.loaded / data.total) * 100); console.log(`下载进度 ${percent}%`); } } }); loadingTask.promise.then((pdf) => { console.log('总页数:', pdf.numPages); }).catch((err) => { console.error('解析失败:', err); });逻辑说明：getDocument返回的是一个加载任务 loadingTask，它内部会在独立 worker 线程里完成 PDF 的下载和解析，包括交叉引用表、对象树和页面树。前端拿到的pdf其实是一个代理对象 PDFDocumentProxy，它并不直接持有像素数据，而是提供操作句柄。这个阶段最容易被误解的是：promise resolve 之后，PDF 内容并没有渲染出来，还需要通过getPage一页一页取。onProgress回调里的loaded / total是字节下载进度，不是解析进度，如果服务器响应头没有Content-Length，total会是 0，页面上的进度条要做兜底，不能直接算百分比显示成 NaN。
参数说明：url可以是相对路径或绝对路径，跨域地址需要服务端正确返回 CORS 响应头。withCredentials表示跨域请求是否需要携带 Cookie，只有 PDF 接口依赖登录态时才开true，否则开着会增加一次 OPTIONS 预检，小文件不明显，大文件慢个一两百毫秒都能感觉到。GlobalWorkerOptions.workerSrc是必配项，主文件负责 API，真正的二进制解析在 worker 里做，路径指向pdf.worker.js，版本要与主文件一致，否则后面会报版本不匹配。
2.2 计算 viewport：scale 与 devicePixelRatio 的关系
渲染单页的核心是拿到 PDFPageProxy，然后通过getViewport计算绘制窗口。这里有个高清屏的细节，很多人第一次写都会踩：
async function renderPage(pdf, pageNumber, canvas, scale = 1) { const page = await pdf.getPage(pageNumber); const baseViewport = page.getViewport({ scale: 1 }); const dpr = window.devicePixelRatio || 1; const viewport = page.getViewport({ scale: scale * dpr }); canvas.width = viewport.width; canvas.height = viewport.height; canvas.style.width = `${baseViewport.width * scale}px`; canvas.style.height = `${baseViewport.height * scale}px`; const context = canvas.getContext('2d'); try { await page.render({ canvasContext: context, viewport, background: '#ffffff' }).promise; } catch (err) { if (err.name === 'RenderingCancelledException') return; throw err; } finally { page.cleanup(); } }逻辑说明：PDF 内部坐标单位是磅，getViewport({ scale: 1 })是把一磅换算成一个 CSS 像素，得到原始尺寸。scale参数控制缩放倍率，dpr是屏幕物理像素与逻辑像素的比值。canvas.width和canvas.height是位图缓冲区的像素尺寸，应该用物理像素值，也就是scale * dpr；而canvas.style.width/height是 CSS 显示尺寸，应该用逻辑像素值。这两个分清楚，高分屏上文字边缘才不会发虚。我一般习惯把background: '#ffffff'固定加上，因为部分 PDF 页面没有底色，透明背景叠加在深色页面上会显得很脏。
参数说明：page.cleanup()在渲染结束后调用，它会释放当前页面不再使用的图像和字体缓存，但不会销毁整个 PDF 文档。翻页场景下这个调用不能省，否则几百页翻过去，内存里会堆满各种没用的字体子集和图片对象，最终导致卡顿。
2.3 渲染任务取消：快速翻页的保命操作
连续快速翻页时，上一页的渲染可能还没结束，新一页的渲染就开始排队，用户会明显感到翻页越来越慢。正确做法是取消掉上一个 RenderTask：
let currentRenderTask = null; async function renderPageWithCancel(page, canvas, viewport) { if (currentRenderTask) { currentRenderTask.cancel(); } const renderTask = page.render({ canvasContext: canvas.getContext('2d'), viewport }); currentRenderTask = renderTask; try { await renderTask.promise; } catch (err) { if (err.name === 'RenderingCancelledException') return; throw err; } finally { page.cleanup(); } }逻辑说明：renderTask.cancel()是异步的，被取消的渲染任务最终会以RenderingCancelledException结束，必须捕获并忽略这个错误，否则控制台会多一条 unhandledrejection。发起新渲染前，建议把旧的 canvas 宽高先改掉，因为 canvas 的 width/height 重新赋值会清空画布，这和取消任务是两个独立步骤。如果连续取消三四次，旧的 promise 全部 reject，catch 里只判断异常名，不要顺手把page对象销毁，下一页还需要复用同一个页面结构。
3. 三种接入方式对比：iframe、embed 与自定义渲染
3.1 iframe 与 embed：零代码实现的边界在哪
用原生方式嵌入 PDF，往往就是一行标签的事：
<iframe src="/docs/report.pdf#page=3&toolbar=0" width="100%" height="600px" ></iframe>逻辑说明：iframe 和 embed 本质上是把 PDF 交给浏览器内置的 PDF 查看器去渲染。加载、缩放、翻页都由浏览器接管，网站代码拿不到任何事件和进度。#page=3这类锚点参数不是标准，Chrome 支持得很不错，但 Firefox 对toolbar=0经常无视，移动端 Safari 根本不渲染内嵌 PDF，直接变成下载行为。更隐蔽的是，响应头里如果带了Content-Disposition: attachment，即使 iframe 写得好好的，浏览器也会强制触发下载而不是预览。
embed 和 iframe 的差别只在于少了一层嵌套文档，控制能力同样弱。要做阅读统计、关键词搜索、自定义水印、记住上次阅读位置，原生插件方案全都做不到。所以 iframe 只适合内部管理系统这类环境固定、用户不挑体验的场景。
3.2 自定义渲染：把控制权拿回自己手里
自定义渲染方案以 pdf.js 的解析能力为核心。HTML 只需要一个容器，剩下的都是 JavaScript 在操作 canvas：
<div id="pdfContainer"></div> <script src="/vendor/pdf.min.js"></script> <script> pdfjsLib.GlobalWorkerOptions.workerSrc = '/vendor/pdf.worker.js'; </script>let pdf = null; const container = document.getElementById('pdfContainer'); pdfjsLib.getDocument('/files/report.pdf').promise.then(async (doc) => { pdf = doc; const page = await doc.getPage(1); const viewport = page.getViewport({ scale: 1.2 }); const canvas = document.createElement('canvas'); canvas.width = viewport.width; canvas.height = viewport.height; container.appendChild(canvas); await page.render({ canvasContext: canvas.getContext('2d'), viewport }).promise; page.cleanup(); });逻辑说明：渲染结果完全由自己的 canvas 元素承载，DOM 结构、尺寸、位置可以随意控制。500 页的 PDF 首屏只画一页，用户几乎感觉不到大文件的存在。代价是需要自己维护的细节变多了：worker 版本、跨域响应头、canvas 位图尺寸、页面资源回收、渲染取消、加载进度。这些坑不是必然出现，但出现一个就能让你排查半天。
3.3 选型矩阵与参数边界
| 维度 | iframe / embed | pdf.js 自定义渲染 |
|---|---|---|
| 开发量 | 零代码 | 需要维护渲染流程 |
| 交互控制 | 弱，完全依赖浏览器 | 逐页、缩放、进度全自主 |
| 移动端表现 | iOS Safari 经常白屏 | 全平台行为一致 |
| 加载进度 | 无 | 可以拿到字节进度 |
| 跨域限制 | 受浏览器插件策略限制 | 服务端配置 CORS 即可 |
| 内存管理 | 浏览器负责 | 必须手动 cleanup 和淘汰缓存 |
| 文本搜索 | 依赖浏览器原生 | 通过 getTextContent 自行实现 |
选型建议：只是后台管理端自己看一眼，iframe 是够用的；要做面向用户的合同预览、电子书、简历展示，就选自定义渲染。项目里已经有完整前端框架时，也别把 iframe 当组件复用，后期想加搜索、记住阅读位置，你会为当时图省事付出代价。
4. 完整实现：带进度、缩放、取消渲染的在线 PDF 查看器
4.1 初始化解析库与加载进度
先搭一个最简单的工具栏和容器：
<div class="viewer-toolbar"> <button id="prevBtn">上一页</button> <span id="pageIndicator">- / -</span> <button id="nextBtn">下一页</button> <select id="zoomList"> <option value="0.5">50%</option> <option value="0.75">75%</option> <option value="1" selected>100%</option> <option value="1.5">150%</option> </select> <span id="progressText"></span> </div> <div id="canvasHost"></div>const pdfjsLib = window.pdfjsLib; pdfjsLib.GlobalWorkerOptions.workerSrc = '/vendor/pdf.worker.js'; const state = { pdfDocument: null, pageNumber: 1, scale: 1, renderTask: null }; async function loadPdf(url) { const task = pdfjsLib.getDocument({ url, onProgress: (data) => { const total = data.total || 0; if (total > 0) { const pct = Math.round((data.loaded / total) * 100); document.getElementById('progressText').textContent = `加载 ${pct}%`; } else { document.getElementById('progressText').textContent = '加载中…'; } } }); state.pdfDocument = await task.promise; document.getElementById('pageIndicator').textContent = `${state.pageNumber} / ${state.pdfDocument.numPages}`; document.getElementById('progressText').textContent = ''; await renderCurrentPage(); }逻辑说明：onProgress在下载阶段反复触发，适合给用户一个"文件正在进来"的反馈。如果文件已经命中了浏览器缓存，loaded可能直接等于total，也可能两个都是 0，所以代码里要先把total || 0兜住。下载进度和解析进度是两回事，解析期间这条回调不会再触发，你可以在promise前后手动切换 loading 文案。
4.2 渲染当前页并维护 canvas
async function renderCurrentPage() { const doc = state.pdfDocument; if (!doc) return; if (state.renderTask) { state.renderTask.cancel(); } const page = await doc.getPage(state.pageNumber); const baseViewport = page.getViewport({ scale: 1 }); const viewport = page.getViewport({ scale: state.scale * (window.devicePixelRatio || 1) }); let canvas = document.querySelector('#canvasHost canvas'); if (!canvas) { canvas = document.createElement('canvas'); document.getElementById('canvasHost').appendChild(canvas); } canvas.width = viewport.width; canvas.height = viewport.height; canvas.style.width = `${baseViewport.width * state.scale}px`; canvas.style.height = `${baseViewport.height * state.scale}px`; const renderTask = page.render({ canvasContext: canvas.getContext('2d'), viewport, background: '#ffffff' }); state.renderTask = renderTask; try { await renderTask.promise; } catch (err) { if (err.name === 'RenderingCancelledException') return; throw err; } finally { page.cleanup(); } document.getElementById('pageIndicator').textContent = `${state.pageNumber} / ${doc.numPages}`; }逻辑说明：每次渲染前取消上一个renderTask，是为了避免旧任务还在往同一个 canvas 画像素，改完宽高后正好把画布清空，两个动作叠加容易造成画面闪烁。取消不是立即结束，所以 await 之后还在 try/catch 里兜住RenderingCancelledException。canvas.width和canvas.style.width分开设置，保证高分屏清晰度的同时，让 CSS 布局按逻辑尺寸走。page.cleanup()放在 finally 里，无论渲染成功还是被取消，都及时释放当前页的字体和图片缓存。
参数说明：state.scale是逻辑缩放比例，我平时从 0.5 到 1.5 提供几个档位。工程图纸类的宽幅 PDF，建议把最低档设成 0.2，否则首屏渲染几百兆像素会直接卡死。容器高度建议固定，不要跟随 PDF 高度变化，否则每次翻页上下跳动很影响体验。
4.3 翻页与缩放联动
document.getElementById('prevBtn').addEventListener('click', () => { if (state.pageNumber > 1) { state.pageNumber--; renderCurrentPage(); } }); document.getElementById('nextBtn').addEventListener('click', () => { if (state.pageNumber < state.pdfDocument.numPages) { state.pageNumber++; renderCurrentPage(); } }); document.getElementById('zoomList').addEventListener('change', (e) => { state.scale = parseFloat(e.target.value); renderCurrentPage(); });逻辑说明：翻页只是修改state.pageNumber再整体重走渲染流程，没有其他魔法。缩放也不涉及重新解析 PDF，只是换了一个 viewport 重新绘制，所以响应很快。这里要注意，缩放之后 canvas 的位图和 CSS 尺寸都会变化，如果外层容器的高度没跟着调整，页面里会出现滚动条跳动；要么固定容器高度，要么缩放后手动把容器高度设置成viewport.height * scale。
4.4 本地文件与 Blob URL 的加载差异
用户上传 PDF 时，最常见的错误是：
const file = input.files[0]; pdfjsLib.getDocument({ url: URL.createObjectURL(file) }).promise.then(...);这样也能跑，但 Blob URL 会占用一条内存引用，使用完要及时 revoke。更稳妥的是直接转成 ArrayBuffer 走内存数据：
const file = input.files[0]; const data = await file.arrayBuffer(); const task = pdfjsLib.getDocument({ data }); state.pdfDocument = await task.promise;逻辑说明：data参数直接接收二进制数据，解析过程发生在 worker 内存里，没有网络请求，不存在跨域问题。大文件时要注意，几十 MB 的 PDF 全部读进内存，移动端可能吃力，这种情况更适合后端转图片或返回流式 URL 让 pdf.js 自己拉取。
5. 避坑与排查：五个能让你在线上翻车的 PDF 预览坑
5.1 跨域问题导致加载任务直接失败
现象：网络面板里 PDF 请求 200，但页面报Failed to fetch或Access to fetch at ... has been blocked by CORS policy，整片内容一直空白。
原因：pdf.js 内部用 fetch/XHR 去请求 PDF 文件，浏览器同源策略拦截了没有 CORS 响应头的跨域响应。地址栏直接打开 PDF 触发的是导航请求，不受 CORS 限制，所以你会觉得"文件明明能打开啊"。
解决：如果 PDF 由自己的后端提供，给响应加Access-Control-Allow-Origin，并且正确处理跨域请求的 OPTIONS 预检。如果 PDF 来自第三方存储，你改不了响应头，就在自己后端做一层代理，由服务端去拉取再转发给前端。代理时要保持流式读写，不要response.text()完之后再返回，大 PDF 会把代理服务内存吃爆。
5.2 worker 文件 404 或版本不匹配
现象：控制台出现Failed to load pdf.worker.js，或者The API version ... does not match the Worker version ...，再或者一条Setting up fake worker的警告。
原因：workerSrc路径写错，或者主文件跟 worker 文件来自不同构建版本。用 CDN 直引时最容易出这个问题，一个地址是 3.x 版，另一个是 2.x 版，浏览器加载后才比对出来。
解决：固定同一版本、同一目录。我用 script 标签时，会把pdf.min.js和对应的pdf.worker.js一起拷到静态目录，版本靠文件名锁定。用 npm 打包时，记得把pdfjs-dist/build/pdf.worker.mjs作为静态资源输出，构建工具不同配置也不同，别只导入 API 包而忘了 worker。
5.3 canvas 渲染成功但显示空白
现象：page.render的 promise 正常 resolve，控制台没有任何报错，canvas 元素在页面上也有尺寸，但内容全白或者只显示一个角落。
原因：最常见的是 canvas 的 CSS 尺寸和位图尺寸对不上。比如容器宽度是 0，viewport.width算出来是 0，渲染全画到零宽位图上；或者 CSS 写了width: 100%; height: 300px，但 canvas 位图只有默认的 300x150，绘制结果被压缩或裁剪。
解决：渲染前用getBoundingClientRect()确认容器宽度大于 0，再给canvas.width赋具体数值，不要依赖默认值。调试时可以给 canvas 加一个style="background: red"，如果红色能显示但 PDF 内容没有，问题就在绘制坐标或位图尺寸。另一个隐蔽原因是渲染刚结束就把 canvas 从 DOM 移走了，这属于异步时序问题，渲染 promise 没有 resolve 之前，不要做任何 DOM 清理。
5.4 长文档翻页卡顿，内存只增不降
现象：几十页的 PDF 一直流畅，翻到两百多页后，每翻一页都有明显延迟，任务管理器里浏览器内存稳步上涨，最后直接白屏或闪退。
原因：每一页getPage后，页面的字体、图片和资源都挂在文档对象上，没有调用cleanup()。同时渲染过的 canvas 如果一直留在 DOM 里，位图内存也不会释放。两者叠加，越翻越卡。
解决：渲染当前页后立即page.cleanup()，并且维护一个 LRU 缓存，只保留当前页和前后一两页的 canvas。淘汰页面时把canvas.width = 0，这一步可以立刻释放位图内存；再把 canvas 元素直接从 DOM 移除。如果是单页应用，组件卸载时要调用pdfDocument.destroy()，否则整个文档对象仍然持有大量内部资源。
5.5 移动端 iframe 方案直接失效
现象：iOS Safari 和微信内置浏览器里，iframe 打开 PDF 显示灰色或空白，有些版本直接唤起下载。Android 各厂商 WebView 行为也不一致，有的能显示有的直接跳到外部应用。
原因：iOS Safari 不支持在 iframe 内嵌渲染 PDF，它把 PDF 资源当作文档导航处理，但内置渲染器没有真正覆盖这个场景。加上服务端Content-Disposition或 MIME 类型不标准，浏览器就会选择下载而不是预览。
解决：移动端不要再用 iframe/embed，统一走 pdf.js 自定义渲染。如果项目实在不想引入这个库，另一个稳健方案是服务端把 PDF 转成图片列表，前端用图片轮播的方式预览，虽然丢掉了文字搜索和选中复制，但兼容性最好、开发量最小，适合扫描件和合同快照。
6. 进阶技巧：预渲染与缓存管理，把阅读体验拉满
6.1 用去抖预渲染下一页
用户停留在当前页超过 300ms 后，可以预先渲染下一页，让翻页看起来零等待：
let preloadTimer = null; function schedulePreload() { clearTimeout(preloadTimer); preloadTimer = setTimeout(() => { const nextPage = state.pageNumber + 1; if (nextPage <= state.pdfDocument.numPages && !pageCache.has(nextPage)) { renderToCache(nextPage, state.scale); } }, 300); }逻辑说明：去抖的意义在于用户快速连翻三页时，中间页根本没有必要预渲染，等他停下来，再按当前所处位置预读下一页。预渲染的 canvas 放在离屏容器里，用户翻过去时直接替换 DOM，省掉一次空白等待。移动端内存紧，我会直接关掉这个功能。
6.2 用 Map 实现简单的 LRU 页面缓存
const MAX_CACHE = 3; const pageCache = new Map(); function setPageCache(num, canvas) { if (pageCache.has(num)) { pageCache.delete(num); } else if (pageCache.size >= MAX_CACHE) { const oldestKey = pageCache.keys().next().value; const oldCanvas = pageCache.get(oldestKey); oldCanvas.width = 0; oldCanvas.remove(); pageCache.delete(oldestKey); } pageCache.set(num, canvas); }逻辑说明：Map 的 key 按插入顺序排列，每次命中时先delete再set就能把最近使用的项移到末尾。淘汰时从开头拿最久没用的项，width = 0让浏览器立即释放位图，remove()从 DOM 移走。缓存上限我一般设 3，当前页加前后各一页，再多就失去"按需渲染"的意义了。
6.3 全文检索与高亮定位
pdf.js 提供getTextContent()能拿到页面文本项和位置信息：
const textContent = await page.getTextContent(); const fullText = textContent.items .map((item) => item.str) .join(' '); const found = fullText.includes(keyword);逻辑说明：文本搜索用于判断"哪几页包含关键词"很方便，但要实现高亮定位，还需要把文本项的坐标映射到 canvas 的显示坐标，然后在 canvas 上层覆盖一个半透明高亮层。文本层和 canvas 必须使用相同的scale，位置才能对齐。扫描件没有文本层，items会是空数组，这种情况只能靠 OCR 服务转换后再检索。
有一回我接到一个特别大的 PDF 预览需求，连续快速翻页把整个页面卡到无响应。后来我把预渲染改成"翻页停下来 300ms 才触发"，并把页面缓存上限压到 3 张，内存曲线立刻平稳了下来。从那以后我每次做在线 PDF 预览，都会强制走一遍这套检查：CORS 头、worker 版本、canvas 尺寸、页面 cleanup、缓存上限，五步全过才敢说这个功能能上线。希望这些细节能帮到你。
本文还有配套的精品资源，点击获取
