2026/9/9 19:05:08
FEATURED · 精选文章 
简介PDF.js是由Mozilla团队开发的开源JavaScript库能够在浏览器端完成PDF文档的解析、渲染与交互这套调试可用版资源适合需要快速为网站或系统加入在线预览能力的开发者解决了传统方案需安装插件或依赖本地软件的问题。压缩包内共367个文件整体仅1.7MB主要包含按区域语言划分的bcmap字符映射文件、properties资源定义、png与svg界面图标、核心js脚本以及html演示页面和css样式覆盖了开发、调试、部署所需的关键组成部分。相比官方发布包该调试版保留了更丰富的日志输出和错误检查机制当PDF加载异常或字体映射缺失时可以快速定位原因同时借助Canvas绘制技术在IE、Firefox、Chrome等多浏览器下均能保持较为一致的展示效果。目前已有1082人学习本调试版从Ajax获取PDF数据到页面渲染的完整调用链都有体现目录内还提供license与光标等附属资源既适合初学者理清库的组成和调用关系也适合有经验的工程师作为可运行基础快速嵌入业务项目。 最近好几个朋友不约而同地来问我同一个问题网页里要展示PDF能不能不要一打开就被浏览器“接管”跳出一个带下载按钮、打印按钮的外壳还有人说“客户要求页面里直接看PDF但不能让他随意下载能实现吗”——这就是我折腾pdf.js在线查看PDF工具的起点。先说结论能实现而且做出来之后不只是“能看”这么简单。pdf.js这套开源方案是Mozilla团队用JavaScript和HTML5实现的PDF解析与渲染引擎目前Firefox的内置PDF阅读器就是它的作品。它的价值在于把PDF的解析、渲染、交互全部交还给前端开发者控制浏览器的原生查看器可以完全被替代。这个工具适合前端开发者、做企业内部系统的同学、以及所有需要把PDF预览嵌入到Web产品里的从业者参考。下面我从原理、架构、实操和踩坑四个维度把这套东西讲透。1. 为什么放着现成的浏览器PDF查看器不用这个问题的答案决定了你到底有没有必要引入pdf.js。浏览器自带的PDF查看器过去叫PDF Viewer现在Chrome和Edge里面叫PDFium和Adobe Acrobat扩展它们有个共同特点非常好用但不归你控制。最典型的痛点就是下载按钮。你用Chrome打开一个PDF链接右上角永远有一个下载图标地址栏里也有一个“下载文件”的按钮。产品经理说“这个PDF只能在系统里看不允许下载”你告诉他不支持他说你去掉这个按钮就行——你根本做不到。浏览器的UI是浏览器厂商的产品不是你的产品它的按钮、布局、交互逻辑都跟你无关。再往下说不同浏览器的查看器体验差别很大。Chrome的PDFium虽然渲染速度不错但对某些特殊字体的PDF支持一般Firefox自己的PDF.js版本更新频繁样式跟Chrome完全不同Safari的QuickLook预览甚至不给你滚动条。做企业内部系统的人应该深有体会同一个链接有人用Chrome打开正常有人用Edge打开变成两页横向排列电话就来了“你们这系统是不是有问题”——其实问题出在浏览器差异上但用户只会找你。还有移动端。手机浏览器打开PDF默认行为就是直接下载文件或者唤起系统预览器这在小屏幕上的体验非常差。用户想的是像看图片一样上下滑动翻页现实却是需要不断缩放、拖动折腾两下就放弃了。所以“在线查看PDF”这件事本质上是把浏览器的默认行为替换成你自己的产品逻辑。你想让用户看到什么样的工具栏、翻页方式、缩放范围、水印叠加都是由你的代码说了算。这不只是“去掉下载按钮”的问题是产品体验、权限控制和品牌一致性的问题。而pdf.js给了你一个从零搭建这一切的基础。2. pdf.js到底干了什么活解析、渲染与Worker线程要正确使用pdf.js你得先把它的原理摸清。很多人直接用vue-pdf组件遇到点问题就不知道怎么排查核心原因是“黑盒使用”——不知道怎么运行自然不知道怎么调试。一个PDF文件从磁盘到屏幕上的画面大概要走这么几步读取字节流、词法解析、对象解析、内容流解析、矢量绘制、栅格化渲染。pdf.js的解析器用JavaScript实现了完整的PDF规范包括对加密PDF的处理、字体嵌入的解析、颜色空间转换、图像解码等等。它对PDF文件里的每个对象进行分类页面对象、字体对象、图像对象、资源字典、内容流指令然后逐页把内容翻译成Canvas的绘制指令。这里要重点说一个机制那就是Web Worker。PDF解析和渲染是重计算任务如果直接放在主线程里跑UI会被卡死。用户在拖动滚动条或者点击缩放按钮时页面的响应速度会变得非常糟糕。pdf.js的做法是在后台线程里完成解析工作然后通过消息传递把渲染结果交给主线程绘制到Canvas上。所以初始化Worker这一步非常关键代码里常见的一个报错“Setting up fake worker”就是因为Worker没有正常加载脚本降级到主线程执行虽然功能还在但性能大打折扣。再提一下版本。现在的pdf.js已经更新到v4.x和v3.x最大的区别在于语言包、CMap和标准字体文件不再打包进主库需要单独从CDN或本地路径加载。这意味着如果你的部署环境没有外网必须在初始化时显式配置这些资源的路径否则中文PDF或者某些特殊字体的文档渲染出来全是空白或乱码。我见过不少从v3升级到v4后中文不显示的问题十有八九是忘了配以下这段路径pdfjsLib.GlobalWorkerOptions.workerSrc /public/pdfjs/pdf.worker.min.js; const pdf await pdfjsLib.getDocument({ url: pdfUrl, cMapUrl: /public/pdfjs/cmaps/, cMapPacked: true, standardFontDataUrl: /public/pdfjs/standard_fonts/, }).promise;cMapUrl是PDF中CID字体到Unicode字符映射表的目录standardFontDataUrl是标准14种字体的数据目录。这两个路径不配置很多PDF在解析阶段会报“Unknown character collection”或者字体字形缺失渲染出来的效果就是方框或者空白。3. 一个能上线的在线PDF预览工具需要哪些零件很多教程只教你在前端页面里引入pdf.js然后渲染一个PDF文件出来但真实项目里要做的事情远比这个多。我列一下我上一个项目里用到的全部零件先说基础设施。PDF的存储位置最常见的是对象存储服务比如阿里云OSS、腾讯云COS、AWS S3或者你自建的MinIO。PDF文件不能直接公开读取否则用户拿到链接就能下载所以需要用签名URL或者代理转发的方式做鉴权。签名URL的思路是后端生成一个有时效的访问链接交给前端好处是实现简单、压力在后端控制代理转发的思路是前端只请求你自己的后端接口后端再去拉流好处是更好地控制访问权限和审计日志缺点是会增加带宽成本。不管用哪种方式必须注意一个点Worker请求的URL和主文档请求的URL最好不要跨域。Worker加载本身就是跨域敏感的如果worker文件放在CDN上而主应用在另一个域就需要配置跨域头如果PDF文档本身也是协同签名链接也要注意携带正确的请求头或者直接把字节流拿到前端再传给pdf.js避免它自己发起可能没有权限的请求。再说前端组件。我建议把PDF预览封装成一个独立组件因为业务里往往要多处复用。一个完整组件需要的UI内容包括工具栏上一页、下一页、页码输入框、缩放级别、旋转、适配宽度/页面、主画布区至少包含当前页渲染、翻页缓冲、加载状态、错误状态、以及特殊需求比如水印层、文本选择层。还要注意联动需求。比如有一种场景是PDF和审批流程关联用户翻到某一页时需要把当前页码记录下来下次进来继续看。这个功能想做得顺滑就得把页面的渲染生命周期设计好——不是每次直接渲染指定页而是先加载文档然后跳转到上次阅读位置再渲染缓冲页。后端接口的设计也不可忽视。一个完善的PDF加载链路里后端应该提供这些接口获取PDF元数据文件名、页数、大小、获取PDF文件的签名URL或流式接口、记录打开/关闭日志、校验用户是否有预览权限。页数的获取就很有意思如果你不用pdf.js去解析就得自己写个PDF解析器读页树工作量很大但如果你直接让前端拿到PDF文件对象用pdf.js解析又可能暴露文件内容本身所以通常的做法是上传时用Python或Java解析一次页数、存到数据库预览时直接查库返回。这个看似多余的一步在权限控制严格的内部系统里非常重要。4. 核心实现从加载文档到渲染出第一页下面直接给一个可上手的核心实现我会把每一步的目的解释清楚。假设你的项目是Vue 3 Vite底层的pdfjs-dist版本是4.x。第一步安装依赖npm install pdfjs-dist4第二步把pdfjs相关的静态资源放到public目录。这一步非常关键也是最容易被新手忽略的。在node_modules/pdfjs-dist里找到cmaps、standard_fonts和build/pdf.worker.min.mjs手动复制到public/pdfjs/下。为什么必须手动复制因为Vite不会自动帮你处理这些非模块化的资源webpack5以前有copy-webpack-plugin的方案Vite下面就得自己配vite-plugin-static-copy或者干脆手动放。第三步初始化加载器。这里有两个选择getDocument传URL还是传二进制数据。我的建议是如果后端给的签名URL有效期足够长直接传URL如果有效期短或者需要携带自定义请求头就用fetch拿到ArrayBuffer再塞给getDocument。第二种方式更稳定还能复用前端的统一请求逻辑async function loadPdf(fileUrl) { const response await fetch(fileUrl, { headers: { Authorization: Bearer token } }); const data await response.arrayBuffer(); const task pdfjsLib.getDocument({ data, cMapUrl: /pdfjs/cmaps/, cMapPacked: true, standardFontDataUrl: /pdfjs/standard_fonts/, }); const pdf await task.promise; return pdf; }注意getDocument返回的是一个PDFDocumentLoadingTask实例它有两个阶段loadingTask.promise是文档加载完成的Promisepdf.getPage(pageIndex)才是获取页面的方法。页面索引从1开始这是pdf.js的官方约定踩过一次之后你就记住了。第四步渲染第一页。渲染PDF页面需要把PDF的单位换算成CSS像素。PDF里页面的单位是pt1pt约等于1/72英寸而CSS像素在不同DPI设备上有所不同。所以需要先设置一个scale常规做法是scale 1.5或者根据设备DPI计算async function renderPage(pdf, pageNumber, canvas, scale 1.5) { const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale }); canvas.width viewport.width; canvas.height viewport.height; const context canvas.getContext(2d); await page.render({ canvasContext: context, viewport }).promise; }这里有一个很常见的坑高DPI屏幕比如MacBook的Retina屏渲染出来的PDF文字发虚。原因是你直接用CSS去拉伸Canvas尺寸没有考虑devicePixelRatio。修正方法是const dpr window.devicePixelRatio || 1; canvas.width Math.floor(viewport.width * dpr); canvas.height Math.floor(viewport.height * dpr); canvas.style.width ${viewport.width}px; canvas.style.height ${viewport.height}px; context.scale(dpr, dpr);先按DPR放大画布物理像素再用CSS还原视觉尺寸文字就锐利了。这条经验来自实际项目不写进去你大概率要在“为什么我的清晰度不如浏览器原生查看器”这个问题上纠结很久。第五步翻页与缩放。翻页的逻辑很简单维护一个当前页变量重新调用renderPage即可。但要注意渲染队列的问题用户快速连续点击下一页时上一次渲染可能还没结束直接开第二次渲染会报“Cannot use the same canvas during multiple render operations”。解决办法是每次渲染前调用renderTask.cancel()取消前一次任务并捕获取消抛出的异常let currentRenderTask null; async function goToPage(pdf, pageNumber, canvas) { if (currentRenderTask) { currentRenderTask.cancel(); } const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale: currentScale }); const canvasContext canvas.getContext(2d); currentRenderTask page.render({ canvasContext, viewport }); try { await currentRenderTask.promise; } catch (err) { if (err.name ! RenderingCancelledException) throw err; } }缩放的实现一样只是改变scale值后重新渲染。常见的缩放模式有固定百分比50%、75%、100%、适配页面宽度根据容器宽度反推scale、适配整页同时考虑宽度和高度。适配页面宽度的核心公式也不复杂const containerWidth containerRef.value.clientWidth - 32; // 减去左右padding const scale containerWidth / viewportAtScale1.width;这个公式属于“想明白就不难但没想到就会用蠢办法”的类型直接在代码里写死各种分辨率然后手动微调度数是完全没有必要的。5. 我在实际项目中踩过的坑从报错到解决的完整链路这部分是最值钱的因为每个坑都让我花过大量时间排查。我按排查路径来写你以后遇到类似问题可以照着走一遍不要上来就直接搜答案那样下次还是不会。第一个坑报错“Failed to fetch”或者PDF一直不加载。很多人第一反应是网络问题但我在实际项目里遇到的情况是pdf.js请求worker文件时被服务器返回了HTML内容作为兜底。因为当时把pdf.worker.min.js放在了一个会重写URL的目录下服务器识别不了这个新文件就回退到了index.html导致worker加载变成了加载一个HTML文档自然解析不了。排查链路是打开DevTools看Network面板确认worker请求的响应类型是不是application/javascriptContent-Type不对先从这里找。第二个坑跨域导致Canvas被“污染”。这个坑场景是PDF文件放在对象存储服务直链不跨域但前端配置了worker从CDN加载二者域不一致然后渲染还算正常但当你想把渲染好的Canvas导出为图片或复制内容时Canvas变成了一片空白。原因是Canvas已经被标记为“被跨域数据污染”浏览器禁止读取它的像素数据这是安全策略的一部分。解决办法是给对象存储的响应加上Access-Control-Allow-Origin: *或者把worker也传到同一个域名下。这里还衍生出一个小需求很多后台系统需要“导出当前页为图片”如果你的PDF跨域了这个功能永远做不了排查方向就是先把跨域问题解决。第三个坑中文文本无法选中或搜索不到文字。这要分两种情况。第一种是PDF本身就是扫描件没有OCR里面根本没有文字层任何前端方案都提取不出文字这跟工具无关跟源文件有关你要跟业务方解释清楚。第二种是PDF有文字层但pdf.js解析出来的字符映射不对常见于一些国产软件生成的PDF。排查方式是用pdf.js自带的文本内容API试提取文字再跟PDF阅读器里的结果对比如果提取出来是乱码多半是CMap路径没配好。另外如果你的预览组件做了自定义渲染记得调用renderTextLayer方法生成文本层否则用户永远没法选中复制文字。第四个坑大文件的性能问题。一个300MB的PDF直接丢给前端解析用户等半天界面卡死这是不可避免的。pdf.js是支持分页懒加载的但它一次性加载文档对象和部分解析结果文件太大时内存占用依然惊人。实际项目里我的做法是在服务端提前把PDF压缩为预览版降低图片分辨率、压缩流给在线预览用原文件只在用户有下载权限时提供。这不是pdf.js的问题是产品架构的问题。用户在线预览图的加载体验和信息安全都必须通过分流来解决。另外一个实际经验是对于超过100页的PDF不建议一次把连续20页以上的Canvas放进DOM里体验会明显变差更好的做法是维持两侧缓冲滚动时动态销毁远端页面只保留当前可视区的渲染结果。第五个坑打印需求。在线预览工具往往会连带一个“打印”按钮。这里有两个实现路线直接用浏览器的window.print()好处是零成本坏处是打印出来的效果依赖浏览器的打印排版容易多出页眉页脚另一个路线是生成一个隐藏的iframe把PDF的嵌入标签放进去再触打印这种方式更可控。用了pdf.js之后如果需要打印当前预览的PDF一个比较靠谱的做法是把原文件URL丢到一个隐藏iframe里如果用户已有查看权限加载和打印自然没问题如果文件是带权限的代理流那需要额外处理响应头保证iframe加载时带Cookie或token。6. 不只是看图pdf.js的能力边界与进阶玩法很多人在了解pdf.js之后容易产生一个误解它能解析PDF那我是不是可以用它来做PDF编辑器、PDF转Word工具、PDF压缩工具这里必须把能力边界划清楚。pdf.js是只读解析与渲染引擎它不提供PDF内容修改、格式转换的能力。你可以用它做查看、在页面上叠加批注图层、提取文本、提取图片但你不能用它把PDF转成Word文档。为什么因为PDF的内部结构是“指令流”不是“文本流”转Word需要把指令流还原成可编辑的段落、表格、图片这已经超出了“渲染”的范畴涉及反向排版难度有两个数量级的差距。现实情况是市面上的PDF转Word工具都依赖大量的模板规则、OCR识别和人工训练前端JS方案做不了高质量还原。不过pdf.js可以配合一些库实现部分编辑需求。比如pdf-lib这个库可以用于创建、修改PDF文件合并、拆分、旋转页面、编辑文本它的底层不是渲染而是直接操作PDF对象结构再比如jsPDF可以从零生成PDF常用于前端导出报表。把pdf.js的查看能力和pdf-lib的编辑能力结合可以做出一套简单但完整的Web版PDF工具常见场景包括把多份PDF合并成一个、从PDF中删除不需要的页面、旋转某几页方向。注意pdf-lib和pdf.js同时使用同一文件时要避免互相覆盖版本里的共享依赖最好把文件数据统一用ArrayBuffer传递。回到“不让他下载”这个需求。技术上纯前端可以做到不提供下载按钮、禁止右键保存、禁止拖拽文件但这些都挡不住走网络请求的人。真正可靠的做法是服务端只给你预览所需的局部数据比如按页渲染后实时抽取成图片前端只看到图片流拿不到原始PDF字节。pdf.js可以直接解析服务端返回的图片流吗不行但你可以把服务端渲染好的PNG图片直接作为img标签显示这样前端就完全接触不到PDF源文件。劣势是失去了文字选择和矢量放大的能力优势是安全等级很高。如果你面对的业务是保密性强的合同、图纸我会建议直接走图片流方案不要在前端放PDF文件。还有一个进阶方向是移动端触控适配。pdf.js的官方Demo在桌面端没问题但放到手机上单指滑动、双指缩放的交互需要自己实现。我在移动端项目里的做法是容器设置为固定高度内部用滚动容器单指滑动时渲染缓冲区始终保持两页双指缩放时监听touchmove事件计算scale增量。这套逻辑麻烦的地方在于双指缩放过程中每帧都要重新计算viewport并裁剪渲染区域否则会出现上下大片空白。如果不想自己写也可以考虑接一个成熟的手势库比如hammer.js先识别手势再由pdf.js重绘。7. 给刚入门的人几个选型建议如果你正打算自己开发一个在线PDF预览工具我的建议是先花半天时间跑通官方示例别急着封装组件。官方示例里的web/viewer.html已经是一个完整的PDF阅读器你可以先把它跑起来逐个功能对照着看缩放、翻页、文本选择、搜索、打印、进度条。搞清楚每个功能点对应的源码位置比看十篇教程都有用。如果时间紧、只求一个能用的阅读器可以直接集成pdf.js官方的pre-built viewer也就是那个viewer.html通过URL参数控制PDF文件地址viewer.html?filexxx.pdf。这种方式的好处是功能完备、样式统一缺点是比较难跟现有业务深度集成比如自定义工具栏、动态鉴权、水印叠加都得改源码。如果项目是纯展示需求、并发不高也可以考虑用iframe嵌入Google Docs Viewer或Microsoft Office Web Viewer但这些要求文件公网可访问且对国内访问并不友好还得把文件托管到第三方多数内部系统不会接受。如果你需要的是跟业务深度绑定的自定义工具那就要走“pdfjs-dist做渲染内核 自定义React/Vue组件 服务端配合鉴权与解析”这条路。这条路前期工作量确实大但后期收益也最明显你能完全掌控UI、交互、权限、日志甚至做成一个独立的微服务给公司内多个系统共用。最后再说一个小技巧。如果你只是想知道某个PDF有多少页、不关心渲染效果可以只用pdf.js的getMetadata和numPages接口配合getPage拦截特定页面渲染这样加载开销会小很多适合在列表页做“共X页”的展示。别一上来就把所有页面全渲染见过太多因为All Pages渲染导致的性能事故了。这套工具的维护成本不高Mozilla团队持续在更新社区活跃度也高。只要你把Worker加载、CMap路径、跨域配置、渲染队列这几个关键节点处理干净它就能稳定地支撑起在线预览、打印、移动端适配这些日常需求。做完了之后你会发现一个在线PDF查看器不只是“能看”它已经变成了整个产品里用户触感最直接、最容易形成好感度的模块之一。本文还有配套的精品资源点击获取
用pdf.js构建自定义在线PDF预览工具：原理、实现与踩坑指南
简介PDF.js是由Mozilla团队开发的开源JavaScript库能够在浏览器端完成PDF文档的解析、渲染与交互这套调试可用版资源适合需要快速为网站或系统加入在线预览能力的开发者解决了传统方案需安装插件或依赖本地软件的问题。压缩包内共367个文件整体仅1.7MB主要包含按区域语言划分的bcmap字符映射文件、properties资源定义、png与svg界面图标、核心js脚本以及html演示页面和css样式覆盖了开发、调试、部署所需的关键组成部分。相比官方发布包该调试版保留了更丰富的日志输出和错误检查机制当PDF加载异常或字体映射缺失时可以快速定位原因同时借助Canvas绘制技术在IE、Firefox、Chrome等多浏览器下均能保持较为一致的展示效果。目前已有1082人学习本调试版从Ajax获取PDF数据到页面渲染的完整调用链都有体现目录内还提供license与光标等附属资源既适合初学者理清库的组成和调用关系也适合有经验的工程师作为可运行基础快速嵌入业务项目。 最近好几个朋友不约而同地来问我同一个问题网页里要展示PDF能不能不要一打开就被浏览器“接管”跳出一个带下载按钮、打印按钮的外壳还有人说“客户要求页面里直接看PDF但不能让他随意下载能实现吗”——这就是我折腾pdf.js在线查看PDF工具的起点。先说结论能实现而且做出来之后不只是“能看”这么简单。pdf.js这套开源方案是Mozilla团队用JavaScript和HTML5实现的PDF解析与渲染引擎目前Firefox的内置PDF阅读器就是它的作品。它的价值在于把PDF的解析、渲染、交互全部交还给前端开发者控制浏览器的原生查看器可以完全被替代。这个工具适合前端开发者、做企业内部系统的同学、以及所有需要把PDF预览嵌入到Web产品里的从业者参考。下面我从原理、架构、实操和踩坑四个维度把这套东西讲透。1. 为什么放着现成的浏览器PDF查看器不用这个问题的答案决定了你到底有没有必要引入pdf.js。浏览器自带的PDF查看器过去叫PDF Viewer现在Chrome和Edge里面叫PDFium和Adobe Acrobat扩展它们有个共同特点非常好用但不归你控制。最典型的痛点就是下载按钮。你用Chrome打开一个PDF链接右上角永远有一个下载图标地址栏里也有一个“下载文件”的按钮。产品经理说“这个PDF只能在系统里看不允许下载”你告诉他不支持他说你去掉这个按钮就行——你根本做不到。浏览器的UI是浏览器厂商的产品不是你的产品它的按钮、布局、交互逻辑都跟你无关。再往下说不同浏览器的查看器体验差别很大。Chrome的PDFium虽然渲染速度不错但对某些特殊字体的PDF支持一般Firefox自己的PDF.js版本更新频繁样式跟Chrome完全不同Safari的QuickLook预览甚至不给你滚动条。做企业内部系统的人应该深有体会同一个链接有人用Chrome打开正常有人用Edge打开变成两页横向排列电话就来了“你们这系统是不是有问题”——其实问题出在浏览器差异上但用户只会找你。还有移动端。手机浏览器打开PDF默认行为就是直接下载文件或者唤起系统预览器这在小屏幕上的体验非常差。用户想的是像看图片一样上下滑动翻页现实却是需要不断缩放、拖动折腾两下就放弃了。所以“在线查看PDF”这件事本质上是把浏览器的默认行为替换成你自己的产品逻辑。你想让用户看到什么样的工具栏、翻页方式、缩放范围、水印叠加都是由你的代码说了算。这不只是“去掉下载按钮”的问题是产品体验、权限控制和品牌一致性的问题。而pdf.js给了你一个从零搭建这一切的基础。2. pdf.js到底干了什么活解析、渲染与Worker线程要正确使用pdf.js你得先把它的原理摸清。很多人直接用vue-pdf组件遇到点问题就不知道怎么排查核心原因是“黑盒使用”——不知道怎么运行自然不知道怎么调试。一个PDF文件从磁盘到屏幕上的画面大概要走这么几步读取字节流、词法解析、对象解析、内容流解析、矢量绘制、栅格化渲染。pdf.js的解析器用JavaScript实现了完整的PDF规范包括对加密PDF的处理、字体嵌入的解析、颜色空间转换、图像解码等等。它对PDF文件里的每个对象进行分类页面对象、字体对象、图像对象、资源字典、内容流指令然后逐页把内容翻译成Canvas的绘制指令。这里要重点说一个机制那就是Web Worker。PDF解析和渲染是重计算任务如果直接放在主线程里跑UI会被卡死。用户在拖动滚动条或者点击缩放按钮时页面的响应速度会变得非常糟糕。pdf.js的做法是在后台线程里完成解析工作然后通过消息传递把渲染结果交给主线程绘制到Canvas上。所以初始化Worker这一步非常关键代码里常见的一个报错“Setting up fake worker”就是因为Worker没有正常加载脚本降级到主线程执行虽然功能还在但性能大打折扣。再提一下版本。现在的pdf.js已经更新到v4.x和v3.x最大的区别在于语言包、CMap和标准字体文件不再打包进主库需要单独从CDN或本地路径加载。这意味着如果你的部署环境没有外网必须在初始化时显式配置这些资源的路径否则中文PDF或者某些特殊字体的文档渲染出来全是空白或乱码。我见过不少从v3升级到v4后中文不显示的问题十有八九是忘了配以下这段路径pdfjsLib.GlobalWorkerOptions.workerSrc /public/pdfjs/pdf.worker.min.js; const pdf await pdfjsLib.getDocument({ url: pdfUrl, cMapUrl: /public/pdfjs/cmaps/, cMapPacked: true, standardFontDataUrl: /public/pdfjs/standard_fonts/, }).promise;cMapUrl是PDF中CID字体到Unicode字符映射表的目录standardFontDataUrl是标准14种字体的数据目录。这两个路径不配置很多PDF在解析阶段会报“Unknown character collection”或者字体字形缺失渲染出来的效果就是方框或者空白。3. 一个能上线的在线PDF预览工具需要哪些零件很多教程只教你在前端页面里引入pdf.js然后渲染一个PDF文件出来但真实项目里要做的事情远比这个多。我列一下我上一个项目里用到的全部零件先说基础设施。PDF的存储位置最常见的是对象存储服务比如阿里云OSS、腾讯云COS、AWS S3或者你自建的MinIO。PDF文件不能直接公开读取否则用户拿到链接就能下载所以需要用签名URL或者代理转发的方式做鉴权。签名URL的思路是后端生成一个有时效的访问链接交给前端好处是实现简单、压力在后端控制代理转发的思路是前端只请求你自己的后端接口后端再去拉流好处是更好地控制访问权限和审计日志缺点是会增加带宽成本。不管用哪种方式必须注意一个点Worker请求的URL和主文档请求的URL最好不要跨域。Worker加载本身就是跨域敏感的如果worker文件放在CDN上而主应用在另一个域就需要配置跨域头如果PDF文档本身也是协同签名链接也要注意携带正确的请求头或者直接把字节流拿到前端再传给pdf.js避免它自己发起可能没有权限的请求。再说前端组件。我建议把PDF预览封装成一个独立组件因为业务里往往要多处复用。一个完整组件需要的UI内容包括工具栏上一页、下一页、页码输入框、缩放级别、旋转、适配宽度/页面、主画布区至少包含当前页渲染、翻页缓冲、加载状态、错误状态、以及特殊需求比如水印层、文本选择层。还要注意联动需求。比如有一种场景是PDF和审批流程关联用户翻到某一页时需要把当前页码记录下来下次进来继续看。这个功能想做得顺滑就得把页面的渲染生命周期设计好——不是每次直接渲染指定页而是先加载文档然后跳转到上次阅读位置再渲染缓冲页。后端接口的设计也不可忽视。一个完善的PDF加载链路里后端应该提供这些接口获取PDF元数据文件名、页数、大小、获取PDF文件的签名URL或流式接口、记录打开/关闭日志、校验用户是否有预览权限。页数的获取就很有意思如果你不用pdf.js去解析就得自己写个PDF解析器读页树工作量很大但如果你直接让前端拿到PDF文件对象用pdf.js解析又可能暴露文件内容本身所以通常的做法是上传时用Python或Java解析一次页数、存到数据库预览时直接查库返回。这个看似多余的一步在权限控制严格的内部系统里非常重要。4. 核心实现从加载文档到渲染出第一页下面直接给一个可上手的核心实现我会把每一步的目的解释清楚。假设你的项目是Vue 3 Vite底层的pdfjs-dist版本是4.x。第一步安装依赖npm install pdfjs-dist4第二步把pdfjs相关的静态资源放到public目录。这一步非常关键也是最容易被新手忽略的。在node_modules/pdfjs-dist里找到cmaps、standard_fonts和build/pdf.worker.min.mjs手动复制到public/pdfjs/下。为什么必须手动复制因为Vite不会自动帮你处理这些非模块化的资源webpack5以前有copy-webpack-plugin的方案Vite下面就得自己配vite-plugin-static-copy或者干脆手动放。第三步初始化加载器。这里有两个选择getDocument传URL还是传二进制数据。我的建议是如果后端给的签名URL有效期足够长直接传URL如果有效期短或者需要携带自定义请求头就用fetch拿到ArrayBuffer再塞给getDocument。第二种方式更稳定还能复用前端的统一请求逻辑async function loadPdf(fileUrl) { const response await fetch(fileUrl, { headers: { Authorization: Bearer token } }); const data await response.arrayBuffer(); const task pdfjsLib.getDocument({ data, cMapUrl: /pdfjs/cmaps/, cMapPacked: true, standardFontDataUrl: /pdfjs/standard_fonts/, }); const pdf await task.promise; return pdf; }注意getDocument返回的是一个PDFDocumentLoadingTask实例它有两个阶段loadingTask.promise是文档加载完成的Promisepdf.getPage(pageIndex)才是获取页面的方法。页面索引从1开始这是pdf.js的官方约定踩过一次之后你就记住了。第四步渲染第一页。渲染PDF页面需要把PDF的单位换算成CSS像素。PDF里页面的单位是pt1pt约等于1/72英寸而CSS像素在不同DPI设备上有所不同。所以需要先设置一个scale常规做法是scale 1.5或者根据设备DPI计算async function renderPage(pdf, pageNumber, canvas, scale 1.5) { const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale }); canvas.width viewport.width; canvas.height viewport.height; const context canvas.getContext(2d); await page.render({ canvasContext: context, viewport }).promise; }这里有一个很常见的坑高DPI屏幕比如MacBook的Retina屏渲染出来的PDF文字发虚。原因是你直接用CSS去拉伸Canvas尺寸没有考虑devicePixelRatio。修正方法是const dpr window.devicePixelRatio || 1; canvas.width Math.floor(viewport.width * dpr); canvas.height Math.floor(viewport.height * dpr); canvas.style.width ${viewport.width}px; canvas.style.height ${viewport.height}px; context.scale(dpr, dpr);先按DPR放大画布物理像素再用CSS还原视觉尺寸文字就锐利了。这条经验来自实际项目不写进去你大概率要在“为什么我的清晰度不如浏览器原生查看器”这个问题上纠结很久。第五步翻页与缩放。翻页的逻辑很简单维护一个当前页变量重新调用renderPage即可。但要注意渲染队列的问题用户快速连续点击下一页时上一次渲染可能还没结束直接开第二次渲染会报“Cannot use the same canvas during multiple render operations”。解决办法是每次渲染前调用renderTask.cancel()取消前一次任务并捕获取消抛出的异常let currentRenderTask null; async function goToPage(pdf, pageNumber, canvas) { if (currentRenderTask) { currentRenderTask.cancel(); } const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale: currentScale }); const canvasContext canvas.getContext(2d); currentRenderTask page.render({ canvasContext, viewport }); try { await currentRenderTask.promise; } catch (err) { if (err.name ! RenderingCancelledException) throw err; } }缩放的实现一样只是改变scale值后重新渲染。常见的缩放模式有固定百分比50%、75%、100%、适配页面宽度根据容器宽度反推scale、适配整页同时考虑宽度和高度。适配页面宽度的核心公式也不复杂const containerWidth containerRef.value.clientWidth - 32; // 减去左右padding const scale containerWidth / viewportAtScale1.width;这个公式属于“想明白就不难但没想到就会用蠢办法”的类型直接在代码里写死各种分辨率然后手动微调度数是完全没有必要的。5. 我在实际项目中踩过的坑从报错到解决的完整链路这部分是最值钱的因为每个坑都让我花过大量时间排查。我按排查路径来写你以后遇到类似问题可以照着走一遍不要上来就直接搜答案那样下次还是不会。第一个坑报错“Failed to fetch”或者PDF一直不加载。很多人第一反应是网络问题但我在实际项目里遇到的情况是pdf.js请求worker文件时被服务器返回了HTML内容作为兜底。因为当时把pdf.worker.min.js放在了一个会重写URL的目录下服务器识别不了这个新文件就回退到了index.html导致worker加载变成了加载一个HTML文档自然解析不了。排查链路是打开DevTools看Network面板确认worker请求的响应类型是不是application/javascriptContent-Type不对先从这里找。第二个坑跨域导致Canvas被“污染”。这个坑场景是PDF文件放在对象存储服务直链不跨域但前端配置了worker从CDN加载二者域不一致然后渲染还算正常但当你想把渲染好的Canvas导出为图片或复制内容时Canvas变成了一片空白。原因是Canvas已经被标记为“被跨域数据污染”浏览器禁止读取它的像素数据这是安全策略的一部分。解决办法是给对象存储的响应加上Access-Control-Allow-Origin: *或者把worker也传到同一个域名下。这里还衍生出一个小需求很多后台系统需要“导出当前页为图片”如果你的PDF跨域了这个功能永远做不了排查方向就是先把跨域问题解决。第三个坑中文文本无法选中或搜索不到文字。这要分两种情况。第一种是PDF本身就是扫描件没有OCR里面根本没有文字层任何前端方案都提取不出文字这跟工具无关跟源文件有关你要跟业务方解释清楚。第二种是PDF有文字层但pdf.js解析出来的字符映射不对常见于一些国产软件生成的PDF。排查方式是用pdf.js自带的文本内容API试提取文字再跟PDF阅读器里的结果对比如果提取出来是乱码多半是CMap路径没配好。另外如果你的预览组件做了自定义渲染记得调用renderTextLayer方法生成文本层否则用户永远没法选中复制文字。第四个坑大文件的性能问题。一个300MB的PDF直接丢给前端解析用户等半天界面卡死这是不可避免的。pdf.js是支持分页懒加载的但它一次性加载文档对象和部分解析结果文件太大时内存占用依然惊人。实际项目里我的做法是在服务端提前把PDF压缩为预览版降低图片分辨率、压缩流给在线预览用原文件只在用户有下载权限时提供。这不是pdf.js的问题是产品架构的问题。用户在线预览图的加载体验和信息安全都必须通过分流来解决。另外一个实际经验是对于超过100页的PDF不建议一次把连续20页以上的Canvas放进DOM里体验会明显变差更好的做法是维持两侧缓冲滚动时动态销毁远端页面只保留当前可视区的渲染结果。第五个坑打印需求。在线预览工具往往会连带一个“打印”按钮。这里有两个实现路线直接用浏览器的window.print()好处是零成本坏处是打印出来的效果依赖浏览器的打印排版容易多出页眉页脚另一个路线是生成一个隐藏的iframe把PDF的嵌入标签放进去再触打印这种方式更可控。用了pdf.js之后如果需要打印当前预览的PDF一个比较靠谱的做法是把原文件URL丢到一个隐藏iframe里如果用户已有查看权限加载和打印自然没问题如果文件是带权限的代理流那需要额外处理响应头保证iframe加载时带Cookie或token。6. 不只是看图pdf.js的能力边界与进阶玩法很多人在了解pdf.js之后容易产生一个误解它能解析PDF那我是不是可以用它来做PDF编辑器、PDF转Word工具、PDF压缩工具这里必须把能力边界划清楚。pdf.js是只读解析与渲染引擎它不提供PDF内容修改、格式转换的能力。你可以用它做查看、在页面上叠加批注图层、提取文本、提取图片但你不能用它把PDF转成Word文档。为什么因为PDF的内部结构是“指令流”不是“文本流”转Word需要把指令流还原成可编辑的段落、表格、图片这已经超出了“渲染”的范畴涉及反向排版难度有两个数量级的差距。现实情况是市面上的PDF转Word工具都依赖大量的模板规则、OCR识别和人工训练前端JS方案做不了高质量还原。不过pdf.js可以配合一些库实现部分编辑需求。比如pdf-lib这个库可以用于创建、修改PDF文件合并、拆分、旋转页面、编辑文本它的底层不是渲染而是直接操作PDF对象结构再比如jsPDF可以从零生成PDF常用于前端导出报表。把pdf.js的查看能力和pdf-lib的编辑能力结合可以做出一套简单但完整的Web版PDF工具常见场景包括把多份PDF合并成一个、从PDF中删除不需要的页面、旋转某几页方向。注意pdf-lib和pdf.js同时使用同一文件时要避免互相覆盖版本里的共享依赖最好把文件数据统一用ArrayBuffer传递。回到“不让他下载”这个需求。技术上纯前端可以做到不提供下载按钮、禁止右键保存、禁止拖拽文件但这些都挡不住走网络请求的人。真正可靠的做法是服务端只给你预览所需的局部数据比如按页渲染后实时抽取成图片前端只看到图片流拿不到原始PDF字节。pdf.js可以直接解析服务端返回的图片流吗不行但你可以把服务端渲染好的PNG图片直接作为img标签显示这样前端就完全接触不到PDF源文件。劣势是失去了文字选择和矢量放大的能力优势是安全等级很高。如果你面对的业务是保密性强的合同、图纸我会建议直接走图片流方案不要在前端放PDF文件。还有一个进阶方向是移动端触控适配。pdf.js的官方Demo在桌面端没问题但放到手机上单指滑动、双指缩放的交互需要自己实现。我在移动端项目里的做法是容器设置为固定高度内部用滚动容器单指滑动时渲染缓冲区始终保持两页双指缩放时监听touchmove事件计算scale增量。这套逻辑麻烦的地方在于双指缩放过程中每帧都要重新计算viewport并裁剪渲染区域否则会出现上下大片空白。如果不想自己写也可以考虑接一个成熟的手势库比如hammer.js先识别手势再由pdf.js重绘。7. 给刚入门的人几个选型建议如果你正打算自己开发一个在线PDF预览工具我的建议是先花半天时间跑通官方示例别急着封装组件。官方示例里的web/viewer.html已经是一个完整的PDF阅读器你可以先把它跑起来逐个功能对照着看缩放、翻页、文本选择、搜索、打印、进度条。搞清楚每个功能点对应的源码位置比看十篇教程都有用。如果时间紧、只求一个能用的阅读器可以直接集成pdf.js官方的pre-built viewer也就是那个viewer.html通过URL参数控制PDF文件地址viewer.html?filexxx.pdf。这种方式的好处是功能完备、样式统一缺点是比较难跟现有业务深度集成比如自定义工具栏、动态鉴权、水印叠加都得改源码。如果项目是纯展示需求、并发不高也可以考虑用iframe嵌入Google Docs Viewer或Microsoft Office Web Viewer但这些要求文件公网可访问且对国内访问并不友好还得把文件托管到第三方多数内部系统不会接受。如果你需要的是跟业务深度绑定的自定义工具那就要走“pdfjs-dist做渲染内核 自定义React/Vue组件 服务端配合鉴权与解析”这条路。这条路前期工作量确实大但后期收益也最明显你能完全掌控UI、交互、权限、日志甚至做成一个独立的微服务给公司内多个系统共用。最后再说一个小技巧。如果你只是想知道某个PDF有多少页、不关心渲染效果可以只用pdf.js的getMetadata和numPages接口配合getPage拦截特定页面渲染这样加载开销会小很多适合在列表页做“共X页”的展示。别一上来就把所有页面全渲染见过太多因为All Pages渲染导致的性能事故了。这套工具的维护成本不高Mozilla团队持续在更新社区活跃度也高。只要你把Worker加载、CMap路径、跨域配置、渲染队列这几个关键节点处理干净它就能稳定地支撑起在线预览、打印、移动端适配这些日常需求。做完了之后你会发现一个在线PDF查看器不只是“能看”它已经变成了整个产品里用户触感最直接、最容易形成好感度的模块之一。本文还有配套的精品资源点击获取 
