pdf.js 1.9.426旧后台PDF预览接入与避坑指南

简介pdf.js 1.9.426 是一套基于纯 JavaScript 实现的免费开源 PDF 阅读组件面向需要在网页中嵌入文档预览能力的开发者与项目团队可解决浏览器端免插件查看 PDF、缩放、打印和文本查找等常见需求。压缩包共 372 个文件约 5.54MB包含 4 个核心 js 脚本、168 个 bcmap 字符映射文件、105 个 properties 多语言资源以及 png/svg 图标、示例 pdf 和许可说明等其中 bcmap 主要支撑中日韩等字符集的编码映射properties 用于界面文案本地化图标与 html/css 则便于直接搭建演示页面。该版本兼容火狐、谷歌及 IE9 以上浏览器但受 H5 技术限制IE8 及以下无法使用同时包体偏大可能影响首屏加载速度。当前已有 993 人学习下载适合用来快速验证网页 PDF 预览方案、了解 pdf.js 的目录组织与多语言字体映射机制并作为集成排错和二次开发的参考底包。1. 旧版 pdf.js1.9.426 压缩包哪些旧后台还值得用它pdf.js1.9.426 这个压缩包不是给新项目追新用的它更像旧后台的后悔药。前阵子帮人维护一套年久失修的文档预览页后端只肯吐 PDF 流前端连构建链都没有新版库塞进去反而要补一堆兼容层。这个包解压后就是一套可直接挂静态目录的查看器加一组 build 产物核心能力是 canvas 渲染、文本层、搜索、缩放和分页。适合维护旧系统、内网静态页、不能大改前端栈、只需要稳定看 PDF 的小团队不适合需要最新渲染特性、要长期跟安全修补的新项目。先明确边界再动手后面才不会把旧包当新库硬套。2. 解压后先看三块目录build、web、cmaps 的接入分工拿到压缩包后最忌讳直接双击viewer.html就开始改样式。pdf.js 的资源分三块build放主库和 workerweb放查看器页面、语言包、图片和文本层样式cmaps放中文、日文等字符映射。三块路径一旦拆散后面会出现页面能开但中文空白、worker 404、文本层错位这类问题。我一般先把目录跑一遍确认文件齐全后再选接入方式。2.1 解压后先核对 build、web、cmaps 三块先看顶层结构不要急着改viewer.js。下面这段命令只做一件事把可能影响加载的目录和关键文件列出来避免拿到残缺包就开跑。# 进入解压后的目录实际名称按压缩包解压结果调整 cd pdfjs-1.9.426 # 看顶层目录确认 build、web 是否存在 ls -la # 只列两层目录重点看 cmaps 是否在 web 下或独立存在 find . -maxdepth 2 -type d | sort # 核对三个关键文件缺一个都别往下走 ls -l build/pdf.js build/pdf.worker.js web/viewer.html这段命令的逻辑是先确认目录边界再确认关键文件。build/pdf.js是主库build/pdf.worker.js是解析 workerweb/viewer.html是现成查看器。参数上唯一要改的是cd后的目录名有些压缩包会多一层同名目录进错层会导致后面所有相对路径都偏。find的-maxdepth 2是防止目录太深刷屏真遇到cmaps不在web下就在下一步把cMapUrl指到实际位置。常见文件分工可以按下面这张表核对不需要背解压后对着看就行。路径作用缺失后的典型表现build/pdf.js主库提供getDocument等 API页面报pdfjsLib is not definedbuild/pdf.worker.js解析 worker负责耗时解析控制台 worker 加载失败页面长时间空白web/viewer.html现成查看器入口无法用静态页方案快速嵌入web/viewer.js查看器交互逻辑工具栏、搜索、缩放按钮失效web/cmaps/字符映射中文 PDF 常依赖中文空白、方框或乱码web/locale/界面语言包查看器按钮显示英文或键名提示目录核对阶段不要改任何源码先把原始包完整跑通一次后面出问题才能判断是资源缺失还是接入方式错了。2.2 静态页方案用 viewer.html 快速嵌入旧后台如果旧后台只是缺一个预览窗口最省事的做法是把整个web目录挂到静态服务下用iframe指过去。这样不用自己写工具栏搜索、翻页、缩放都是现成的。下面是最小页面重点是file参数必须编码否则带空格或中文的 PDF 路径会截断。!-- viewer-static.html静态页嵌入示例file 指向同源 PDF 地址 -- iframe src/pdfjs/web/viewer.html?file%2Ffiles%2Fdemo.pdf width100% height720 styleborder:0 titlePDF 预览 /iframe这段 HTML 的逻辑是把查看器当独立页面加载file参数告诉查看器要打开哪个 PDF。%2Ffiles%2Fdemo.pdf是/files/demo.pdf编码后的结果实际项目里用encodeURIComponent生成不要手拼。width和height按容器调整旧后台弹窗里常见高度是 600 到 800。这个方案适合后台管理系统、内网文档页、只需要看和搜的场景缺点是样式难改工具栏按钮和你现有页面风格很难统一复杂交互也受限。静态页方案还有一个容易忽略的点viewer.html里的相对路径是按它自己的位置算的所以不要把viewer.html单独拷到别的目录除非你把web下的资源一起搬。常见做法是整个web目录原样部署前端只负责拼file参数。这样升级或回退时只动一个目录不会把业务代码搅进去。2.3 API 方案自己接管渲染适合自定义工具栏当旧后台需要自定义工具栏、只要单页预览、或者移动端要控制渲染节奏就不要用viewer.html直接引build/pdf.js自己渲染。下面这段只做引入和 worker 路径设置真正的渲染放在下一章。!-- viewer-api.html自己接管渲染时的最小引入 -- script src/pdfjs/build/pdf.js/script script // 先设 worker 路径不设时旧版会按当前页面相对路径找容易 404 pdfjsLib.GlobalWorkerOptions.workerSrc /pdfjs/build/pdf.worker.js; /script这段代码的关键参数只有workerSrc它必须是浏览器能直接访问到的路径。用根相对路径/pdfjs/build/pdf.worker.js比./build/pdf.worker.js稳因为业务页面可能挂在多层路由下。引入顺序也不能反先加载pdf.js再设GlobalWorkerOptions否则pdfjsLib还不存在。API 方案的自由度更高但文本层、搜索高亮、分页按钮都要自己补适合对交互有明确要求的项目不适合只想快速塞一个预览框的后台。选型上我一般按一个标准判断如果需求里出现“自定义工具栏”“只渲染当前页”“要把 PDF 页面当图片叠标注”走 API如果需求是“能看、能搜、能翻页”走viewer.html。两条路不要混着改混用最容易出现一个页面里两套缩放状态互相打架。3. 用 API 渲染第一页getDocument、canvas 与文本层的参数账自己接管渲染时核心链路只有三步getDocument拿到文档对象getPage拿到页对象page.render把内容画到 canvas。真正容易翻车的是参数和坐标scale设多少、canvas 宽高怎么算、文本层怎么和 canvas 对齐。旧版 pdf.js 的 API 风格偏 Promise写的时候要把加载失败和渲染取消分开处理不然后面排查会变成黑匣子。3.1 getDocument 的加载链路与 workerSrc 设置先写加载链路不要一上来就写渲染。下面这段把loadingTask和pdf分开存目的是失败时能拿到具体异常页面切走时也能取消。// 加载 PDFloadingTask 负责取消pdf 负责后续取页 const loadingTask pdfjsLib.getDocument({ url: /files/demo.pdf, cMapUrl: /pdfjs/web/cmaps/, cMapPacked: true, disableFontFace: false }); let pdfDoc null; loadingTask.promise.then(function (pdf) { pdfDoc pdf; console.log(总页数, pdf.numPages); return pdf.getPage(1); }).then(function (page) { // 这里拿到第一页下一步交给 render console.log(第一页尺寸, page.view); }).catch(function (err) { // 旧版异常信息有时在 err.message 里先打完整对象 console.error(PDF 加载失败, err); });这段代码的逻辑是先创建加载任务再等 Promise 完成。url是 PDF 地址必须同源或服务端允许跨域cMapUrl指向字符映射目录中文 PDF 没有它很容易空白cMapPacked表示映射文件是压缩格式通常和包内cmaps目录配套disableFontFace设false是保留字体面渲染遇到特殊字体显示异常时再考虑调整。旧版里这些参数名要以build/pdf.js源码为准不要拿新版参数硬套尤其是一些新开关在 1.9.426 里根本不存在。loadingTask和pdfDoc分开存的好处是取消时目标明确页面切走调loadingTask.destroy()已经加载完的文档调pdfDoc.destroy()。只存一个变量的话后面很容易出现“取消了但 worker 还在跑”的情况。加载失败时不要只打err.message旧版有些异常对象带name和details完整打出来才能判断是路径、跨域还是文件损坏。3.2 canvas 渲染第一页与 scale 计算拿到页对象后先算 viewport再设 canvas 宽高最后 render。顺序反了会出现画布模糊或只画一半。下面这段按scale放大 1.5 倍适合桌面端清晰度要求不高的预览。// 渲染第一页viewport 决定 canvas 尺寸scale 决定清晰度 function renderFirstPage(page) { const scale 1.5; const viewport page.getViewport({ scale: scale }); const canvas document.getElementById(pdf-canvas); const context canvas.getContext(2d); // 先设宽高再取上下文宽高一变画布就会被清空 canvas.width Math.floor(viewport.width); canvas.height Math.floor(viewport.height); canvas.style.width Math.floor(viewport.width) px; canvas.style.height Math.floor(viewport.height) px; const renderContext { canvasContext: context, viewport: viewport }; return page.render(renderContext).promise; }这段代码的关键参数是scale和viewport。scale为 1 时按 PDF 点值渲染1.5 适合普通屏幕2 以上在高分屏更清楚但内存翻倍。canvas.width和canvas.height是绘制缓冲区尺寸canvas.style.width和canvas.style.height是页面显示尺寸两者不要混。旧版里page.render返回的是RenderTask取.promise才能等渲染结束如果直接拿返回值当 Promise后面取消和错误处理都会别扭。高分屏常见做法是把scale乘上设备像素比再把 CSS 尺寸设回逻辑尺寸。这样文字边缘更干净但每页 canvas 内存会明显上升连续滚动时不要每页都开高倍率。我的习惯是首屏 1.5 到 2 倍预加载页用 1 倍等用户停下来再补清晰度。3.3 文本层叠加与坐标换算只有 canvas 时 PDF 是“图片”不能选中、不能搜索。文本层的作用是把文字 span 绝对定位到 canvas 上方让浏览器原生选择生效。下面这段是最小文本层重点是坐标换算和容器定位。// 文本层把每个文本项转成绝对定位的 span async function renderTextLayer(page, viewport) { const textContent await page.getTextContent(); const textLayer document.getElementById(text-layer); // 容器必须和 canvas 同尺寸、同定位基准 textLayer.style.position absolute; textLayer.style.left 0; textLayer.style.top 0; textLayer.style.width viewport.width px; textLayer.style.height viewport.height px; textLayer.innerHTML ; textContent.items.forEach(function (item) { const span document.createElement(span); span.textContent item.str; span.style.position absolute; span.style.left item.transform[4] px; // PDF 坐标原点在左下DOM 在左上所以用高度减 y span.style.top (viewport.height - item.transform[5]) px; span.style.fontSize Math.abs(item.transform[3]) px; span.style.whiteSpace pre; textLayer.appendChild(span); }); }这段代码的逻辑是先取文本内容再逐项创建 span。item.transform是一个数组常见位置是[a, b, c, d, e, f]其中e和f是平移量d和a和字号、缩放有关。left直接取transform[4]top用viewport.height - transform[5]做 Y 轴翻转。fontSize取Math.abs(transform[3])只是近似复杂字体会偏真实项目里还要结合item.width和item.height校正。文本层容器必须和 canvas 在同一个定位父级里并且宽高一致否则选中框会漂。文本层不是越精确越好。旧版对复杂排版、旋转文字、多栏 PDF 的处理有限强行追像素级对齐会花很多时间。我一般把文本层定位误差控制在可接受范围重点保证“能选中、能复制、搜索高亮不跑偏”。如果业务要求复制顺序严格正确就不要依赖 DOM 文本层直接用getTextContent自己拼文本按transform的 Y 坐标分行。4. 搜索、缩放与连续滚动viewer 参数怎么调到不别扭用现成viewer.html时大部分交互不用写代码但参数要调对。初始页、初始缩放、滚动模式这三个设置直接影响使用体验打开永远在第一页、缩放永远 100%、翻页要手动点用户就会觉得这个预览“能用但难用”。旧版查看器的参数分两层一层是 URL 哈希参数一层是页面内PDFViewerApplication对象调之前先分清层级别在业务页里直接改查看器内部状态。4.1 viewer.html 的 URL 参数与初始页定位URL 参数适合“打开即定位”的场景比如从列表点某条记录直接跳到 PDF 第 3 页。下面这个地址把文件、页码和缩放一起带上。/pdfjs/web/viewer.html?file%2Ffiles%2Fdemo.pdf#page3zoompage-width这段地址里file是查询参数必须编码#page3是哈希参数告诉查看器初始跳到第 3 页zoompage-width表示按页宽缩放。常见组合还有zoompage-fit按整页可见缩放pagemodethumbs打开缩略图侧栏。参数名以包内web/viewer.js为准旧版不一定支持所有新参数配完在控制台看查看器有没有报“未知参数”。实际项目里不要把#page3写死页码来自业务数据。拼接时先encodeURIComponent(fileUrl)再拼哈希。文件地址里如果带#或?不编码会把参数截断这种问题在文件服务返回带签名参数的地址时特别常见。我的习惯是文件地址统一走一个函数生成确保file参数只编码一次避免双重编码后查看器找不到文件。4.2 缩放策略page-width、page-fit 与自定义数值缩放不是越大越好。桌面端侧边栏预览适合page-width移动端适合page-fit需要固定比例对照排版时用数值。下面这段在查看器页面内调用适合自定义工具栏按钮。// 在 viewer.html 内部执行切换缩放策略 // page-width 按页宽page-fit 按整页auto 交给查看器判断 PDFViewerApplication.pdfViewer.currentScaleValue page-width; // 固定比例时直接给数值1 表示 100% // PDFViewerApplication.pdfViewer.currentScaleValue 1.25;这段代码的关键是currentScaleValue它接受字符串策略或数值。page-width适合宽屏阅读page-fit适合快速翻页看版式auto在旧版里会根据容器和页面尺寸做判断行为不如前两个稳定。数值缩放适合“打印预览”或“对照原版”场景但用户手动缩放后会被覆盖所以只在初始化时设一次不要每帧都设。如果查看器嵌在弹窗里容器高度经常变化page-fit可能在弹窗打开瞬间算出错误比例。常见做法是等弹窗动画结束再设一次缩放或者监听容器尺寸变化后重设。旧版没有现代框架那么细的响应式能力别指望它自己处理所有容器变化。4.3 连续滚动与懒加载别一次性把所有页画出来连续滚动适合长文档但旧版查看器默认会预渲染附近页面页数多时内存上涨明显。下面这段切换滚动模式并配合缩放策略减少一次性绘制量。// 切换滚动模式前先看 web/viewer.js 里的枚举旧版常见 0 连续、1 分页 PDFViewerApplication.pdfViewer.scrollMode 0; // 连续滚动时用 auto 或 page-width避免每页都按高倍率绘制 PDFViewerApplication.pdfViewer.currentScaleValue auto; // 只保留当前页附近的渲染翻页后旧页 canvas 会被回收 PDFViewerApplication.pdfViewer.currentPageNumber 1;这段代码的逻辑是先切滚动模式再设缩放最后定位页码。scrollMode的枚举值在不同小版本里可能不同改之前先在web/viewer.js里搜scrollMode确认 0 和 1 分别代表什么。currentPageNumber是页码不是索引第一页就是 1。连续滚动下不要频繁设currentScaleValue每次设置都可能触发重新布局用户滚动时会卡。懒加载的核心是“只画看得见的页”。旧版查看器内部有缓存策略但页面很多时仍建议限制同时渲染页数。常见做法是监听滚动提前一页预加载离屏超过两页的 canvas 主动释放。不要把所有页的 canvas 都留在 DOM 里几十页的高清 PDF 很容易把标签页拖崩。5. 避坑与排查跨域、CMap、字体和内存的 5 条血泪记录旧版 pdf.js 的问题大多不是 API 不会用而是资源路径和渲染状态没对齐。下面 5 条是维护旧后台时反复遇到的每条按“现象、原因、解决”写照着排查能少走很多弯路。先提醒一句控制台里的第一个报错往往不是根因worker 404 会连带出一串渲染失败先把第一个红色错误解决再看后面的。5.1 资源路径类worker 404 与 file 参数跨域现象页面一直空白控制台出现 worker 加载失败或者查看器提示无法获取文件。原因workerSrc没设、设成了相对当前路由的路径或者file参数指向了另一个域被浏览器同源策略拦下。解决worker 用根相对路径写死PDF 走同源部署或服务端代理不要在前端硬绕跨域。// 引入 pdf.js 后立刻设 worker路径按静态目录实际位置改 pdfjsLib.GlobalWorkerOptions.workerSrc /pdfjs/build/pdf.worker.js;这段代码放在所有getDocument之前。workerSrc不是 PDF 地址是解析脚本地址写错时浏览器会去当前页面同级目录找业务路由一深就 404。跨域问题不要靠改浏览器设置解决生产环境不可控最稳的是把 PDF 放到和查看器同源的静态目录或者让后端代理输出。现象iframe里传了file参数查看器能打开但提示文件加载失败。原因file地址没有encodeURIComponent带签名参数或中文路径时被截断。解决统一编码一次并在服务端日志里核对最终请求地址。注意file参数不要编码两次双重编码后查看器会把%2F当普通字符路径直接找不到。5.2 渲染与内存类重复 render 与 canvas 尺寸翻车现象翻页后上一页内容叠在新页上或者 canvas 越翻越模糊。原因在同一个 canvas 上重复render没有取消上一个RenderTask也没有重置宽高。解决每次渲染前取消旧任务重设canvas.width和canvas.height清空画布页面卸载时销毁文档对象。// 单页渲染器取消旧任务重设尺寸再开新任务 let currentRenderTask null; function renderPage(page, canvas, scale) { if (currentRenderTask) { currentRenderTask.cancel(); } const viewport page.getViewport({ scale: scale }); const context canvas.getContext(2d); // 重设宽高会清空画布避免旧页残留 canvas.width Math.floor(viewport.width); canvas.height Math.floor(viewport.height); currentRenderTask page.render({ canvasContext: context, viewport: viewport }); return currentRenderTask.promise.catch(function (err) { // 主动取消会抛 RenderingCancelledException不算真错误 if (err err.name ! RenderingCancelledException) { throw err; } }); }这段代码的关键是cancel()和异常过滤。翻页很快时上一个渲染还没结束就开下一个不取消会同时画两页。RenderingCancelledException是主动取消的正常结果不要当成加载失败弹错误框。scale每次按当前容器算不要缓存 viewport容器尺寸变了还会用旧尺寸。现象文本层能选中但选中框和文字错位。原因文本层容器没有和 canvas 同尺寸或者 CSS 缩放后坐标没跟着换算。解决文本层和 canvas 放同一个定位父级宽高按 viewport 设坐标用同一套 viewport 算。5.3 字体与文本层类CMap 缺失、字体替换与复制乱序现象中文 PDF 页面空白、显示方框或者只有英文正常。原因cmaps目录没部署cMapUrl指错或者cMapPacked和实际文件格式不匹配。解决把web/cmaps原样部署cMapUrl指向目录并以斜杠结尾cMapPacked按包内文件类型设。// 中文 PDF 加载时显式带 cMap 配置路径以斜杠结尾 const loadingTask pdfjsLib.getDocument({ url: /files/demo.pdf, cMapUrl: /pdfjs/web/cmaps/, cMapPacked: true });这段配置里cMapUrl是目录不是单个文件结尾斜杠不能少cMapPacked为true表示使用压缩映射如果包内是未压缩文件就设false。旧版对某些嵌入字体的处理不如新版遇到字体替换导致版面偏移时可以试disableFontFace但设true后文字可能变成路径绘制选中和搜索效果会变差不要一上来就关。现象文本层能选中但复制出来顺序乱、换行不对。原因旧版文本层按 span 绝对定位多栏或旋转文字下 DOM 顺序不等于阅读顺序。解决把文本层当选择辅助复制走getTextContent自己按坐标排序拼接对排版复杂的 PDF 接受一定限制。现象连续翻十几页后标签页明显变卡。原因每页 canvas 都留在 DOM 里高倍率下内存成倍增长。解决离屏页主动释放 canvas只保留当前页和前后各一页文档切走时调destroy。// 页面切走时释放文档和 worker避免长时间驻留 if (pdfDoc) { pdfDoc.destroy(); pdfDoc null; }这段清理代码放在路由离开或弹窗关闭时。destroy()会释放文档占用的资源但不会自动清掉你手动创建的 canvascanvas 还要自己移除或重置宽高。旧版没有现代框架的自动回收资源生命周期要自己管。6. 进阶worker 路径、按需渲染与打印导出的收尾习惯旧版 pdf.js 的进阶空间不大但把 worker 和 cMap 路径固定、把渲染任务收回能解决大部分“越用越卡”的问题。生产环境不要把 worker 放在业务路由下面路径随路由变化是常见翻车点统一放静态目录用根相对路径写死。// 生产环境固定 worker 和 cMap 路径避免相对路径随路由漂移 pdfjsLib.GlobalWorkerOptions.workerSrc /static/pdfjs/build/pdf.worker.js; const task pdfjsLib.getDocument({ url: /files/demo.pdf, cMapUrl: /static/pdfjs/web/cmaps/, cMapPacked: true }); // 页面切走时销毁加载任务未完成的解析也会停 task.destroy().then(function () { console.log(PDF 资源已释放); });这段代码的验证方法很直接打开控制台网络面板看pdf.worker.js和cmaps下的映射文件是不是 200翻页几次后看内存是否持续上涨关闭弹窗后看 worker 是否停止。打印导出不要把 canvas 直接当图片打分辨率不够会糊常见做法是提高scale重新渲染到离屏 canvas再走浏览器打印或者后端按页转图片。我的习惯是每次接旧后台预览先把 workerSrc、cMapUrl、file 编码这三件事走一遍再谈样式和按钮。从那以后我每次交付 pdf.js 相关页面都强制按这个顺序自检一遍少了很多“打开空白”的返工。希望帮到你。本文还有配套的精品资源点击获取