简介这是一份基于PDF.js实现浏览器端在线预览PDF的完整前端资源包面向Web前端开发者和需要快速集成PDF预览功能的技术人员。资源共402个文件压缩包大小仅3.06MB核心由JS、HTML、CSS构成可直接运行的示例页面与工具脚本并配套bcmap、properties等字体映射文件以及PNG、SVG图标素材确保离线环境下也能稳定渲染中文等复杂PDF内容。包体内还包含pdfjs-dist核心库、单页渲染Demo和多页预览相关代码覆盖getDocument加载文档、page.render绘制Canvas、scale参数缩放、progress事件监听进度等关键技术点同时提供文本选择与搜索、Web Worker后台解析等进阶配置的说明性文件。此外代码结构清晰适合初学者与有经验者研读可直接用于快速搭建在线预览系统或作为二次开发基础。目前已有3138人学习下载是理解PDF.js渲染链路、完善预览需求的实用资料。 我们平时做管理系统、门户网站之类的前端项目总会碰到一个绕不开的需求在线查看 PDF 文件。用户那边合同是 PDF、报表是 PDF、说明书也是 PDF你要么让他下载了再看要么直接在页面上打开。下载这种方法体验太差用户一来嫌麻烦二来容易泄露文件路径三来预览需求往往还伴随着“只让看不让下载”“要能把当前页打出来”这类附加条件。所以“JS 在线查看 PDF 文件”虽然是个老话题但真做起来方案选型和踩坑点都比想象中多。这篇文章我把我做过的几种方案、实际用的代码、以及每次都会踩的坑整理出来。无论你是准备从零开始做一个在线文件预览模块还是项目里已经接了某个 PDF 插件但问题不断这篇文章都会给你一个比较完整的参考思路。1. 在线 PDF 查看的整体方案选择1.1 原生浏览器打开为什么不够用最简单的方案其实不需要写任何 JS直接把 PDF 文件地址丢到a标签里或者用window.open(url)打开Chrome、Edge、Firefox 都有内置的 PDF 阅读器能看能翻页能打印。但实际项目里这个方案很快会撞墙样式完全不可控浏览器自带工具栏和你的系统风格完全不搭用户会觉得“跳出去了”。如果 PDF 地址需要权限校验比如带 Token、带签名浏览器地址栏直接访问往往拿不到文件。移动端体验很不稳定iOS 上打开 PDF 的行为和 Android 差异很大部分国产浏览器甚至直接变成下载。你无法统计用户看了第几页、看了多久也没法做水印、禁止下载这类业务控制。所以只要需求稍微复杂一点就必须走前端代码控制路线。1.2 三类实现方案对比我大致把常见方案分成三类选择依据主要是项目技术栈和定制深度。方案优点缺点适用场景iframe / embed / object 直接嵌套零代码改动最小跨域限制多、样式不可控、移动端兼容差内部系统快速预览文件与本系统同源基于 pdf.js 的自定义查看器可控性强、解析 PDF 效果最好、可定制 UI、可做权限控制需要写较多代码处理不当有性能问题绝大多数需要在线预览业务场景服务端转换图片/HTML 后再展示兼容性最好任何终端都能看需要消耗服务器资源转换耗时文字不可选中复杂格式转换、老旧环境如 IE 兼容其中 pdf.js 是最主流的选择。它是 Mozilla 官方维护的 PDF 解析渲染引擎用纯 JS 实现浏览器上能跑Node 上也能跑。你说的 vue-pdf、react-pdf、ng2-pdf-viewer 这些组件底层核心其实都是 pdf.js只是每个框架把它封装了一层。2. PDF.js 是绕不开的核心2.1 PDF.js 到底做了什么PDF.js 的渲染原理一句话总结后端不对 PDF 做任何处理前端拿到的是原始 PDF 字节流由 JS 解析并绘制到 Canvas 上。它内部包含几个核心部分PDFDocumentProxy代表加载完成的 PDF 文档对象可以拿到页数、页面尺寸、书签等元信息。PDFPageProxy代表单页调用page.render()就能把该页绘制到指定 canvas 上。PDFWorker负责在 Web Worker 里跑解析逻辑避免阻塞主线程提升大文件渲染流畅度。文本层TextLayer用于实现文字选中、复制、搜索配合 Canvas 渲染出的图形层一起工作。你不需要记住所有 API 细节但一定要知道这套机制。因为实际开发中会让你卡住的坑基本都藏在“Canvas 绘制”“Worker 加载”“文本层计算”这三个环节里。2.2 导入方式与版本坑pdf.js 在 npm 上的包名是pdfjs-dist版本迭代比较快API 也偶尔有破坏性变更我做过几个项目说几个实际经验。如果你是 Vue 2 项目很多老教程让你用vue-pdf这个包方便但维护已经不太活跃遇到高版本 Chrome 或复杂 PDF 时偶尔会出现渲染异常。如果项目工期紧vue-pdf 能跑就先用如果你要长期维护我建议直接用pdfjs-dist自己封装可控性更强。npm 安装示例npm install pdfjs-dist3.11.174为什么我锁版本因为 4.x 版本之后worker 的引入方式变了CSP内容安全策略环境下的兼容处理也不一样。锁定具体版本至少保证团队内环境一致。核心代码引入方式import * as pdfjsLib from pdfjs-dist; import workerUrl from pdfjs-dist/build/pdf.worker.min.js?url; pdfjsLib.GlobalWorkerOptions.workerSrc workerUrl;关键点在workerSrc。很多人第一次接触 pdf.js 都会忘掉设置 Worker于是 PDF 直接在主线程解析轻则卡顿重则直接报错“Setting up fake worker failed”。如果用的是 Vite用?url的方式去拿 worker 地址最省事如果用 webpack一般要配合file-loader或者直接把 worker 文件放到 public 目录然后写死路径。3. 手写一个可用 PDF 查看器的完整过程3.1 加载文档与渲染首页我带着你从零搭一个极简但能用的查看器先不做花哨 UI把核心逻辑走通。HTML 部分div idpdf-container canvas idpdf-canvas/canvas /div div span第 span idpage-num1/span / span idpage-count-/span 页/span button idprev上一页/button button idnext下一页/button input typerange idscale-range min0.5 max2 step0.1 value1 / button idprint打印/button /div加载 PDF 并渲染第一页let pdfDoc null; let currentPage 1; let currentScale 1.0; async function loadPdf(url) { const loadingTask pdfjsLib.getDocument(url); pdfDoc await loadingTask.promise; document.getElementById(page-count).textContent pdfDoc.numPages; await renderPage(currentPage); } async function renderPage(pageNum) { const page await pdfDoc.getPage(pageNum); const viewport page.getViewport({ scale: currentScale }); const canvas document.getElementById(pdf-canvas); const ctx canvas.getContext(2d); // 关键canvas 的尺寸必须和 viewport 一致 canvas.width viewport.width; canvas.height viewport.height; await page.render({ canvasContext: ctx, viewport }).promise; document.getElementById(page-num).textContent pageNum; } loadPdf(/path/to/your.pdf);这里有个容易出错的地方Canvas 的宽高属性是像素宽度如果不按viewport.width / height赋值而是靠 CSS 拉伸渲染出来的 PDF 文字会模糊得像隔了一层毛玻璃。一定要同时设置 canvas 的 width/height 属性和 CSS 尺寸。3.2 翻页、缩放与页码联动翻页逻辑本身不复杂但要注意边界条件和渲染状态document.getElementById(prev).addEventListener(click, () { if (currentPage 1) return; currentPage--; renderPage(currentPage); }); document.getElementById(next).addEventListener(click, () { if (currentPage pdfDoc.numPages) return; currentPage; renderPage(currentPage); });边界条件要加否则用户一直点下一页页码会越界渲染时会传一个不存在的页号然后报错。缩放这里我多写一句。如果你只改 canvas 的 CSS 尺寸不重新调用 render缩放后页面虽然看起来变大了但清晰度会直线下降。正确的做法是改currentScale后重新走一遍renderPage()让 PDF.js 按新比例重新绘制。再看一下渲染时的细节如果用page.render()后马上翻页上一次渲染还没结束就开启下一次渲染浏览器会强行中断上一次任务并且控制台会抛异常。解决办法是加一个渲染任务标记let renderTask null; async function renderPage(pageNum) { if (renderTask) { renderTask.cancel(); } // ... renderTask page.render({ canvasContext: ctx, viewport }); await renderTask.promise; }renderTask.cancel()是 pdf.js 官方提供的取消渲染方法处理快速翻页场景非常管用。3.3 加一个打印按钮在线查看器十有八九要顺带支持打印甚至只打印当前页。最初我做的时候直接在页面调window.print()结果打印出来的内容要么只有 canvas 第一屏要么布局全乱。后来整理出一套比较稳的做法用隐藏 iframe 承载待打印内容。function printPage() { const iframe document.createElement(iframe); iframe.style.position fixed; iframe.style.right 0; iframe.style.bottom 0; iframe.style.width 0; iframe.style.height 0; iframe.style.border 0; document.body.appendChild(iframe); const iframeDoc iframe.contentWindow.document; iframeDoc.write(htmlheadtitle打印/title/headbody); // 把当前 canvas 转成图片放进 iframe const img iframeDoc.createElement(img); img.src document.getElementById(pdf-canvas).toDataURL(image/png); iframeDoc.body.appendChild(img); iframeDoc.write(/body/html); iframeDoc.close(); iframe.contentWindow.print(); // 打印后回收 iframe iframe.contentWindow.onafterprint () { document.body.removeChild(iframe); }; }要点直接把 canvas 用toDataURL转成图片再打印规避了 canvas 打印时样式丢失的问题。如果你的 PDF 页数很多建议按“当前页”“全部页”两个按钮分开做全部页需要循环遍历渲染再组成图片列表性能开销比较大最好加上进度提示。4. 在线查看常见问题与排查4.1 跨域与文件权限问题pdf.js 通过getDocument(url)拉取文件时受浏览器同源策略限制。如果 PDF 文件在另一个域名或者加了鉴权头简单传 URL 是不行的。实际项目里最常见的是PDF 文件要求登录后才能看直接传 URL 等于没传。解决方案是先用fetch带上 token 拿文件流再转成 ArrayBuffer 交给 pdf.jsasync function loadPdfWithToken(url, token) { const response await fetch(url, { headers: { Authorization: Bearer ${token} } }); if (!response.ok) { throw new Error(PDF 加载失败: response.status); } const buffer await response.arrayBuffer(); const loadingTask pdfjsLib.getDocument({ data: buffer }); pdfDoc await loadingTask.promise; }4.2 字体、乱码与中文显示问题绝大多数“乱码”问题并不是 pdf.js 的锅而是 PDF 文件本身的字体子集化问题。PDF 里内嵌了字体解析时依赖浏览器字体渲染能力正常现代浏览器都能处理。如果碰到中文乱码首先换最新版 Chrome/Edge 试试如果新版没问题说明就是你本地浏览器版本太老。还有一种情况用户的 PDF 是由扫描件组成的本质是图片那需要后端 OCR 才能提取文字前端再怎么做也没有用。这种要先和需求方确认文件来源。4.3 大文件加载慢、Canvas 崩溃上百 MB 的 PDF 在线查看是性能杀手。getDocument()默认是按需加载页面数据的所以打开时只渲染当前页速度还能接受但翻页和大图渲染时依然可能卡顿。几个优化手段我实测下来比较有用懒加载只渲染当前页和相邻页不要一次把所有页都渲染出来。限制同时渲染的 canvas 数量翻页时释放上一页的资源canvas.width 1; canvas.height 1;可以强制释放显存。控制最大缩放比例PDF.js 在 3 倍以上缩放时canvas 尺寸可能超过浏览器最大限制导致白屏。实测如果超过浏览器 canvas 的宽高上限需要把渲染分成多个小 canvas 拼接但工程量大简单粗暴的方式是限制最大比例 2.5 或 3。大文件加载建议加一个 loading 动画const loadingTask pdfjsLib.getDocument(url); loadingTask.onProgress (progress) { if (progress.total 0) { const percent Math.round((progress.loaded / progress.total) * 100); console.log(加载进度${percent}%); } };onProgress可以拿到已加载字节数用来做进度条很合适。5. 再往前一步列表、缩略图与权限控制5.1 缩略图侧边栏其实没你想的那么难很多人看到网上各种 PDF 查看器带缩略图列表以为很复杂。其实 pdf.js 里拿缩略图数据特别直接渲染每一页时把 viewport 的 scale 调小比如 0.2渲染到一个很小的 canvas 上再把 canvas 当成缩略图插入侧边栏。async function renderThumbnail(pageNum, container) { const page await pdfDoc.getPage(pageNum); const viewport page.getViewport({ scale: 0.2 }); const canvas document.createElement(canvas); canvas.width viewport.width; canvas.height viewport.height; await page.render({ canvasContext: canvas.getContext(2d), viewport }).promise; container.appendChild(canvas); }但要注意如果 PDF 有几十上百页一次性渲染全部缩略图会让页面卡死。稳妥做法是滚动到哪个区域再按需渲染那个区域的缩略图这也是浏览器推荐的做法。5.2 权限控制思路PDF 的权限控制要分两层一层是加载权限就是前面说的带 token 请求拿不到文件就什么都看不到。另一层是操作权限比如禁止下载原文件、禁止复制文字。pdf.js 本身不禁止用户保存文件但可以这样缓解前端把源文件 URL 设置为带签名的一次性地址过期失效。禁止右键和拖拽防君子不防小人但能做。在渲染层加水印比如平铺用户 ID 或者邮箱一旦截图泄露能追责。水印实现方式不复杂canvas 渲染完成后在其上方覆盖一层 canvas用globalAlpha降低水印透明度循环绘制字符串。6. 一些个人经验最后分享一点我自己的经验吧。做在线 PDF 预览技术选型不算难真正浪费时间的地方全在边界场景有人传一堆扫描件说是 PDF有人用特别老版本的手机浏览器打开测试页面有人从某个网盘下载的 PDF 本身损坏了但下载后能看你说奇怪不奇怪。所以代码尽量写得防御性强一点getDocument失败一定要 catch并且给用户一个友好的提示而不是白屏。加载大文件时务必做进度反馈不然用户以为系统挂了。用pdfjs-dist时锁死版本升级前先测试几个不同类型的 PDF。一旦项目里用到了 iframe 嵌套打印、canvas 转图片、缩略图批量渲染提前做好内存回收不然长时间翻页后页面会越来越迟钝。我们后来还把部分文件转换成了轻量化 HTML 或者图片格式优先展示PDF 作为一种兜底这样服务器开销和前端渲染压力都小很多。如果你只是需要“能看就行”那上面这套方案完全够用如果需求是“不但能看还要好看、好用、可管理”那就是一个持续迭代的过程了。本文还有配套的精品资源点击获取