企业官网建设流程全解析

在Vue 3项目里做PDF预览，网上搜一圈方案不少，但真正用起来顺手的其实不多。vue-pdf这个老牌组件库，去年我还在用，今年一看已经不怎么维护了，而且对Vue 3的Composition API支持一直半吊子，报错全靠自己猜。pdfjs-dist是Mozilla官方维护的PDF解析渲染引擎，也是浏览器内置PDF阅读器的底层依赖，Vue 3 + Vite项目里直接用它做二次开发，可控性最强，想实现什么交互基本都能做到。

这篇文章我不会只贴一段能跑的代码就完事，而是把我在实际项目里踩过的坑、调过的参数、封装组件的思路都整理出来，按从零到可用的完整流程走一遍。内容包括为什么不用现成组件库、pdfjs-dist在Vue 3里怎么正确初始化、worker线程怎么配置才不会报错、如何实现翻页缩放旋转打印等基础功能，以及大文件渲染的性能优化思路。适合正在用Vue 3做后台管理系统、需要在线预览合同、报告、简历等PDF文件的开发同学，也适合想搞懂pdfjs-dist内部工作机制的进阶读者。

1. 为什么选pdfjs-dist而不是其他方案

1.1 你需要解决的到底是什么问题

做PDF浏览器预览，表面上看是"把PDF显示在页面上"，实际上要拆成几个层次来看。最基础的需求是把PDF第一页渲染成图片展示出来，这种用canvas手动画一下就行；稍微进阶一点要支持翻页、缩放、跳转到指定页；再往上还有文本选择、复制、打印、文字高亮注释等需求。

很多项目一开始觉得"只要能看就行"，结果产品经理第二天就提了一堆要加的功能。所以技术选型不能只看能不能显示，要看扩展边界在哪里。

在浏览器里渲染PDF，现在大致有几条路线。一是用浏览器原生能力，Chrome、Edge、Firefox都内置了PDF查看器，用iframe或者embed标签直接塞一个PDF链接进去就行，但缺点很明显，不同浏览器渲染出来的UI不一样，你没法控制工具栏，也没法做定制交互，而且微信内置浏览器、某些国产浏览器对PDF的原生支持很弱。

二是用服务端把PDF转成图片，前端只负责展示图片，这种方式实现简单，但交互体验很差，缩放会模糊，不能选文字，每次翻页都要请求网络，服务器压力也大。

三是纯前端用pdf.js系的技术方案，把PDF解析和渲染全部放到浏览器端完成。这条路线里，再用layer细分的话，vue-pdf、react-pdf这类封装好的组件是最省事的，但封装组件的问题在于，一旦版本停滞或者功能满足不了需求，你去读它的源码改内部逻辑，有时候比自己写还费劲。

1.2 几种常见方案的对比与踩坑

官方pdf.js库和pdfjs-dist的关系可能有些人不太清楚。pdf.js是Mozilla开发的PDF渲染引擎，以源码形式维护在GitHub上，构建后的npm包就叫pdfjs-dist。所以我们npm install pdfjs-dist，装的其实就是pdf.js的发行版，JavaScript和Worker文件都已经打包好了。

选pdfjs-dist而不选其它现成Vue组件的原因，除了上面提到的维护性问题，还有一个关键点是对Vite和Vue 3的适配程度。Vite作为构建工具，对无头浏览器环境下自动加载Worker的处理方式和Webpack不一样，pdfjs-dist的官方示例虽然也给了Webpack、Vite的接入方式，但版本更新之后接口会变，网上的教程很多都是老版本的写法，照抄大概率报错。

我对比过几个方案的优缺点：

实际项目中最终选pdfjs-dist，不是因为它完美，而是它在"可控性"和"功能完整性"之间最平衡。后面要做的缩放、翻页、打印、文本选择，它全都原生支持，我们要做的只是封装一层Vue组件，把它接进来，再用状态管理或者组件内部状态把交互串起来。

1.3 版本选型：Vue 3项目里该装哪个版本

版本这个东西，在npm上可能看起来只是数字不同，但在pdfjs-dist这里，不同版本之间的API差异非常大。3.x版本和4.x版本的导入方式、Worker配置方式都有变化，网上的很多代码片段还是基于2.x时代写的。

如果你用的是Vue 3 + Vite，我建议直接用最新版本。当前写这篇文章时，pdfjs-dist稳定版已经在4.x系列。4.x版本最大的变化是全面转向ES Module，Worker文件和主文件都是.mjs后缀，如果你从网上的老教程复制代码，用require('pdfjs-dist/build/pdf.worker.js')这种方式引入Worker，大概率会报错，因为根本没有这个文件了。

Vue 2 + Webpack项目则建议用3.11.174这个版本，这是3.x系列的最后一个版本，兼容性最稳，网上踩坑记录也最全，大部分问题都能搜到解决方案。Vue 3 + Vite项目直接用4.x即可，因为Vite对ES Module的支持本来就很好。

我用的是Vue 3.4 + Vite 5 + pdfjs-dist 4.x的组合，后面所有的代码和问题排查都是基于这个组合。如果你用了其他版本，遇到报错时优先检查是不是版本兼容问题。

2. 环境准备与基础接入

2.1 安装与依赖说明

安装就一条命令：

npm install pdfjs-dist

装完之后，在node_modules里能看到pdfjs-dist目录，里面有几个关键文件：

• build/pdf.mjs：主入口文件，包含PDF文档的解析、页面渲染、文本提取等核心API
• build/pdf.worker.mjs：Worker线程的入口文件，负责在后台线程执行PDF解析任务
• web/pdf_viewer.mjs：查看器组件，可以在页面上做完整的PDF阅读器，但它是面向原生JS的，封装进Vue比较费劲
• cmaps/：字符映射表目录，处理某些PDF文件里的中文、日文编码时会用到

依赖就一个pdfjs-dist，不需要额外安装别的库。如果你用TypeScript，可能需要安装@types/pdfjs-dist，但4.x版本的包里面已经带了类型声明文件，我试下来是不需要额外装类型的。

2.2 Worker配置的两种方式

pdfjs-dist的架构是主线程和Worker线程分离的，主线程负责渲染操作和DOM交互，Worker线程负责解析PDF文件数据、执行底层计算。如果不配置Worker，pdfjs-dist会尝试从当前脚本所在目录加载pdf.worker，但在Vite构建的项目里，这个默认路径几乎总是错的，所以必须要手动配置。

在Vue 3 + Vite项目里，Worker配置推荐用Vite的?url导入语法：

// worker配置 import workerUrl from 'pdfjs-dist/build/pdf.worker.mjs?url' pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl

这么做的好处是Vite会自动处理Worker文件的拷贝和路径替换，开发环境和构建环境都能正常工作。构建后会在assets目录里生成pdf.worker.mjs文件，路径由Vite自动管理。

如果你用的是Vue 2 + Webpack，配置方式不一样：

// Webpack 5 配置 import workerUrl from 'pdfjs-dist/build/pdf.worker.min.js?url' pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl

要注意的是，Webpack对?url的支持依赖asset modules配置，不是所有模板都默认开启的，可能需要额外配置。

还有一种是直接把Worker代码以Blob形式注入，或者用new URL('pdfjs-dist/build/pdf.worker.mjs', import.meta.url)这种方式，但?url在Vite里是最简洁稳妥的，我建议优先用。

提示：如果你看到的教程里用的是pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://unpkg.com/pdfjs-dist@4.x/build/pdf.worker.min.mjs'这种CDN方式，开发环境勉强能用，但生产环境不建议，一是外网依赖不可控，二是和你的本地版本可能不一致，产生奇怪的兼容问题。

2.3 第一个能跑通的渲染Demo

在封装完整组件之前，先写一个最小的渲染Demo，确认基本流程能走通。这个Demo做的事情很简单：从本地public目录放一个测试PDF，页面加载后把第一页渲染到canvas上。

<template> <div> <canvas ref="canvasRef"></canvas> </div> </template> <script setup> import { ref, onMounted } from 'vue' import * as pdfjsLib from 'pdfjs-dist' import workerUrl from 'pdfjs-dist/build/pdf.worker.mjs?url' pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl const canvasRef = ref(null) onMounted(async () => { // 加载PDF文档 const task = pdfjsLib.getDocument('/test.pdf') const pdf = await task.promise // 获取第一页 const page = await pdf.getPage(1) // 设置视口，scale=1表示原始大小 const viewport = page.getViewport({ scale: 1 }) // 配置canvas const canvas = canvasRef.value const context = canvas.getContext('2d') canvas.width = viewport.width canvas.height = viewport.height // 渲染页面 await page.render({ canvasContext: context, viewport }).promise }) </script>

这段代码看起来简单，但里面已经包含了pdfjs-dist最核心的流程：

1. getDocument接收PDF数据源，返回一个PDFDocumentLoadingTask对象，通过它的promise属性拿到PDFDocument实例。
2. pdf.getPage(pageNum)获取指定页面的PDFPageProxy对象。
3. page.getViewport({ scale })根据缩放比例计算页面的尺寸信息，返回viewport对象。
4. page.render({ canvasContext, viewport })执行渲染，返回一个RenderTask，等它的promiseresolve之后，canvas上就有内容了。

有一个细节要注意：getDocument的参数，可以传URL字符串、ArrayBuffer、TypedArray，也可以传一个{ url }或{ data }对象。传URL字符串时，pdfjs-dist会自动发起请求，但这种方式对于跨域或者需要自定义请求头的情况不太好处理，后面在项目封装的时候我会建议大家用fetch获取数据再传给pdfjs-dist，这样可控性更强。

3. 从Demo到可用组件：完整实现

3.1 组件设计思路

Demo能跑通不等于能用到项目里，真实场景下你至少需要处理：大文件加载时的loading状态、加载失败的错误提示、翻页交互、缩放交互、页码跳转、以及不同屏幕尺寸下的自适应显示。这些如果全都堆在一个组件里，代码会越来越乱。

我习惯把功能拆成两个层次：底层是一个PDF渲染的核心模块，负责加载文档、渲染页面、销毁资源；上层是Vue组件，接收props（PDF地址、缩放比例、页码等），维护内部状态（加载进度、当前页等），并通过事件向父组件通信。

组件的基本代码如下：

<template> <div class="pdf-viewer"> <div v-if="loading" class="loading">加载中...</div> <div v-if="error" class="error">{{ error }}</div> <canvas ref="canvasRef"></canvas> </div> </template> <script setup> import { ref, watch, onMounted, onBeforeUnmount } from 'vue' import * as pdfjsLib from 'pdfjs-dist' import workerUrl from 'pdfjs-dist/build/pdf.worker.mjs?url' pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl const props = defineProps({ url: { type: String, required: true }, scale: { type: Number, default: 1 }, page: { type: Number, default: 1 } }) const emit = defineEmits(['loaded', 'error']) const canvasRef = ref(null) const loading = ref(false) const error = ref('') let pdfDoc = null let currentPage = null let renderTask = null // 加载文档 async function loadDocument() { if (!props.url) return loading.value = true error.value = '' try { const task = pdfjsLib.getDocument(props.url) pdfDoc = await task.promise emit('loaded', { pageCount: pdfDoc.numPages }) await renderPage(props.page) } catch (e) { console.error('PDF加载失败:', e) error.value = 'PDF加载失败，请检查文件地址或网络' emit('error', e) } finally { loading.value = false } } // 渲染指定页面 async function renderPage(pageNum) { if (!pdfDoc || loading.value) return // 如果正在渲染，先取消 if (renderTask) { renderTask.cancel() } try { const page = await pdfDoc.getPage(pageNum) currentPage = page const viewport = page.getViewport({ scale: props.scale }) const canvas = canvasRef.value const context = canvas.getContext('2d') // 设置canvas尺寸，这里需要考虑devicePixelRatio const dpr = window.devicePixelRatio || 1 canvas.width = viewport.width * dpr canvas.height = viewport.height * dpr canvas.style.width = `${viewport.width}px` canvas.style.height = `${viewport.height}px` // 渲染前先缩放context context.setTransform(dpr, 0, 0, dpr, 0, 0) renderTask = page.render({ canvasContext: context, viewport }) await renderTask.promise renderTask = null } catch (e) { if (e.name === 'RenderingCancelledException') { // 渲染被取消，是正常的，不用处理 return } throw e } } watch(() => props.url, () => { pdfDoc?.destroy() pdfDoc = null loadDocument() }) watch(() => props.page, (newPage) => { if (pdfDoc && newPage >= 1 && newPage <= pdfDoc.numPages) { renderPage(newPage) } }) watch(() => props.scale, () => { if (pdfDoc) { renderPage(props.page) } }) onMounted(loadDocument) onBeforeUnmount(() => { renderTask?.cancel() pdfDoc?.destroy() }) </script>

3.2 加载PDF并渲染首页

组件里有个关键点容易被忽略，就是devicePixelRatio的处理。在普通屏幕上，canvas按viewport的尺寸设置就够了，但在Retina屏上，如果不做处理，渲染出来的PDF文字和线条会发虚。

处理方式是让canvas的实际像素尺寸等于CSS像素尺寸乘以dpr，然后通过context.setTransform(dpr, 0, 0, dpr, 0, 0)让pdfjs的渲染坐标和CSS坐标对齐。这样渲染出来的清晰度就会有明显提升，尤其文字边缘，从发虚变成锐利。

3.3 翻页与页码显示

翻页的核心逻辑是改变当前页码，触发页面渲染。组件本身不直接接收"上一页""下一页"的指令，而是通过父组件传过来的page prop来控制。这样做的好处是页码状态和业务状态可以联动，比如从列表点击某个文件时，直接跳转到之前阅读的页。

<template> <div class="pdf-toolbar"> <button :disabled="currentPage <= 1" @click="prevPage">上一页</button> <span>{{ currentPage }} / {{ pageCount }}</span> <button :disabled="currentPage >= pageCount" @click="nextPage">下一页</button> </div> </template> <script setup> import { ref, computed } from 'vue' const props = defineProps({ page: { type: Number, default: 1 }, pageCount: { type: Number, default: 0 } }) const emit = defineEmits(['update:page']) const currentPage = computed({ get: () => props.page, set: (val) => emit('update:page', val) }) function prevPage() { if (currentPage.value > 1) currentPage.value-- } function nextPage() { if (currentPage.value < props.pageCount) currentPage.value++ } </script>

这里用了v-model风格的双向绑定，父组件通过v-model:page="pageNum"控制页码，子组件通过emit('update:page', newPage)同步页码变化。整个数据流很清晰：父组件持有页码状态，子组件只负责渲染和发事件。

3.4 缩放与旋转

缩放功能的实现思路，是重新计算viewport并重新渲染当前页。因为PDF渲染是基于viewport的，只要你修改scale参数，viewport的宽高就会变化，canvas尺寸也跟着变，重新渲染后页面就放大缩小了。

function zoomIn() { emit('update:scale', props.scale * 1.2) } function zoomOut() { emit('update:scale', props.scale / 1.2) } function resetZoom() { emit('update:scale', 1) }

这里我用update:scale事件把缩放值传给父组件，父组件再通过props把scale传回来。刚开始写的时候我觉得这样做有点绕，后来发现这种单向数据流的好处是，缩放值和页码值都集中在父组件里，如果要实现"保存阅读进度"的功能，直接读取父组件的两个状态就行，不用去子组件里挖。

旋转功能用pdfjs的rotate参数实现。getViewport({ scale, rotation })支持rotation参数，取值是90的倍数。旋转后viewport的宽高会互换，canvas尺寸也随之变化。

function rotate(degrees) { currentRotation.value = (currentRotation.value + degrees) % 360 const viewport = page.getViewport({ scale: props.scale, rotation: currentRotation.value }) // 更新canvas尺寸并重新渲染 }

3.5 文本复制支持

PDF有两种类型：一种是文本型PDF，文字本身就是可提取的内容，比如用Word生成的PDF；另一种是扫描型PDF，本质是图片，文字是印在图片上的。pdfjs-dist提供了page.getTextContent()方法，可以对文本型PDF进行文本提取，返回文本片段和它们的位置信息。

文本复制功能有两个实现层面。第一层只是"能提取到文本"，可以用getTextContent拿到纯文本；第二层是"在页面上选中文字并复制"，这需要在canvas上盖一层透明的文本层，把文字的位置信息映射成DOM元素，让浏览器的原生选区和右键复制功能作用于这些DOM元素。

完整实现文本选择功能比较复杂，需要像pdfjs官方查看器那样，在渲染页面的同时渲染一个文本层。但我发现大部分业务场景只需要"提取PDF里的文字"这个功能，比如做全文搜索、内容摘要、关键词定位，所以我的组件里单独提供了一个提取文本的方法：

async function extractText(pageNum) { const page = await pdfDoc.getPage(pageNum) const textContent = await page.getTextContent() return textContent.items .filter(item => item.str) .map(item => item.str) .join(' ') }

3.6 打印支持

浏览器打印PDF有几种方案，最简单的是直接用window.open(pdfUrl)打开PDF，让浏览器原生工具栏处理打印，但这样会跳出一个新窗口，体验不太友好。

如果要在当前页面里实现打印，可以用iframe隐藏加载PDF，然后调用iframe的print方法：

function printPDF() { const iframe = document.createElement('iframe') iframe.style.display = 'none' iframe.src = props.url document.body.appendChild(iframe) iframe.onload = () => { iframe.contentWindow.print() // 有些浏览器在自动打印后需要手动移除iframe setTimeout(() => { document.body.removeChild(iframe) }, 10000) } }

但要说明的是，这种方式依赖浏览器对PDF的内置渲染，如果产品要求打印出来的效果和页面里渲染的完全一致，通常需要后端生成打印专用的PDF版本，前端只负责调起打印，这个属于业务层面的约定，不是pdfjs-dist的职责范围。

4. 进阶：多页渲染与性能优化

4.1 一页一页渲染还是全部渲染

业务里最常见的需求是"PDF文件里有N页，希望一下全部展示出来，页面往下滚动时连续阅读"。这时候如果用单页canvas按需渲染，就需要处理滚动位置和页码的对应关系，逻辑会复杂一些。

我测试下来，20页以内的PDF，一次性全部渲染其实可以接受。20页以上就要考虑性能了，因为每一页都是一块canvas，页数多了DOM节点爆发，内存占用和首屏渲染时间都会飙升。

一个折中方案是懒加载：页面容器滚动到的区域才渲染该页，出了可视区就清除canvas内容或者直接销毁canvas节点。这个方案实现成本不算太高，核心是监听滚动事件，判断每页是否在可视区内。

// 简化版懒加载逻辑 const containerRef = ref(null) const visiblePages = ref(new Set()) function checkVisiblePages() { const containerRect = containerRef.value.getBoundingClientRect() // 遍历所有已经创建了占位节点的页面 pageNodes.value.forEach((node, index) => { const nodeRect = node.getBoundingClientRect() const isVisible = nodeRect.top < containerRect.bottom && nodeRect.bottom > containerRect.top if (isVisible && !visiblePages.value.has(index)) { visiblePages.value.add(index) renderPageToCanvas(index + 1, node) } }) }

4.2 大文件加载与性能优化

大文件场景下，第一个瓶颈是解析时间。解析一个200MB的PDF，主线程可能会卡顿一两秒，用户体验不好。优化方向是在加载前先检查文件大小，超过阈值时提示"文件较大，正在加载中"，同时配合进度事件，让用户知道确实在加载。

pdfjs-dist的getDocument支持接收onProgress回调，可以拿到加载进度：

const task = pdfjsLib.getDocument({ url: props.url, onProgress: (progressData) => { if (progressData.total) { const percent = Math.round((progressData.loaded / progressData.total) * 100) loadingPercent.value = percent } } })

第二个瓶颈是canvas数量。全部页面都渲染的话，页数越多，canvas占用的GPU内存越多。我之前做过一个100页的PDF预览，一屏一屏往下滚，结果Android平板上直接卡死。后来改了策略：只保留可视区内外的两页canvas，其他页面只显示一个占位div，滚动到再渲染。

第三个瓶颈是内存泄漏。频繁翻页时，每页都创建新的RenderTask，旧的如果不取消，会一直占用内存。这也是我在组件里加了renderTask.cancel()的原因。

4.3 清晰度优化与DPR适配

前面提到了devicePixelRatio，这里再展开说一下为什么必须处理。pdfjs的viewport默认是按CSS像素算的，如果你的CSS里设置canvas宽度为800px，那么viewport.width也是800。渲染时，canvas内部的像素位深是按照canvas.width和canvas.height来算的。在dpr=2的Retina屏上，CSS的800px对应物理像素1600px，如果你canvas.width只设成800，浏览器拉伸填充时就会模糊。

处理方式就是上面代码里的那个写法，把canvas.width和canvas.height设置成viewport尺寸乘以dpr，然后通过context.setTransform进行坐标映射。注意：不推荐用canvas.style.width = viewport.width + 'px'这种CSS强拉方式，因为直接设置canvas的style尺寸会导致画布内部渲染分辨率没有变化，内容还是会模糊。正确做法是同时设置canvas的width/height属性和style的width/height，但style的width/height用viewport的原始CSS尺寸，canvas的width/height用乘以dpr后的值。

5. 常见问题与排查实录

5.1 Worker加载失败的排查

这个错误出现频率最高，错误信息通常是：

Failed to fetch dynamically imported module: http://localhost:5173/pdf.worker.min.mjs

或者是：

The API version "4.x" does not match the Worker version "3.x"

第一种情况说明workerSrc配置的路径不对，或者是Vite没有正确处理?url导入。排查思路：先看控制台Network面板里有没有请求pdf.worker文件，如果根本没有请求，说明workerSrc没有生效；如果有请求但404，说明路径解析错误。

解决方案优先检查代码里的import路径是否和你安装的pdfjs-dist版本匹配。4.x版本要用pdfjs-dist/build/pdf.worker.mjs?url，不要用pdfjs-dist/build/pdf.worker.min.js?url，这两个文件在新版本里可能不存在了。

第二种情况API版本和Worker版本不匹配，基本上是因为你从CDN加载了workerSrc，但CDN的版本和本地npm包的版本不一致。解决办法就是不要用CDN，直接用本地?url方式导入。

5.2 跨域问题的处理

如果你的PDF文件放在OSS或者另一个域名下，直接用url传给getDocument可能会遇到CORS错误。pdfjs-dist的getDocument发起的fetch请求受浏览器同源策略限制，目标服务器必须返回CORS头，前端才能读取数据。

解决方案有两个方向。第一个是后端配合，在OSS或对象存储的CORS配置里加上你的前端域名，这是最推荐的方式。第二个是前端自己做一次fetch请求，把PDF数据先以ArrayBuffer形式取回来，再传给getDocument：

async function loadPdfFromUrl(url) { const response = await fetch(url) const arrayBuffer = await response.arrayBuffer() const task = pdfjsLib.getDocument({ data: arrayBuffer }) return task.promise }

这种做法可以绕开一部分CORS限制，但前提是fetch本身能成功。如果服务器根本不返回CORS头，fetch也会报错，这种情况只能让后端配合加头，或者走代理。

5.3 渲染模糊与文字发虚

页面渲染出来模糊，第一检查dpr处理，第二检查canvas的style宽高是否被外部样式覆盖了。有时候你明明设置了正确的canvas尺寸，但父容器有display: flex或者width: 100%的样式，会把canvas的style强制撑开或压缩，导致显示模糊。

排查技巧是在浏览器开发者工具里检查canvas元素的计算样式，看它的实际渲染尺寸是否和canvas.width/height一致。如果style宽高是被外部撑开的，需要给canvas加display: block，并且设置max-width: 100%来防止溢出，但要注意max-width: 100%也会导致等比缩小时canvas被拉大，所以对canvas最好用固定宽度或者内联样式控制。

5.4 内存泄漏与页面卡顿

页面卡顿的本质原因是渲染任务没有管理好。每次翻页都会触发render，如果用户快速点击上一页下一页，会有很多个渲染任务同时在跑，互相抢占资源。

解决方案我上面的代码里已经体现了：

1. 每次渲染前检查renderTask，如果存在则先cancel。
2. 渲染期间设置loading状态，提示用户正在渲染。
3. 组件销毁前调用pdfDoc.destroy()，释放PDFDocument对象占用的资源。

还有一个容易被忽略的点：如果你监听了一些事件，比如滚动事件做懒加载，组件卸载时必须移除监听器，否则组件虽然销毁了，但监听器还在回调里访问已经被销毁的DOM节点，造成内存泄漏。

5.5 中文字体显示异常

部分PDF文件用了内嵌字体，浏览器端渲染时如果字体文件过大或者不完整，可能出现中文显示成方框的问题。pdfjs-dist的cmaps目录里包含了常用的字符映射表，但需要你手动配置cmaps的加载路径。

pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl pdfjsLib.GlobalWorkerOptions.cMapUrl = cmapUrl pdfjsLib.GlobalWorkerOptions.cMapPacked = true

cmapUrl指向pdfjs-dist的cmaps目录，在Vite里可以这样配置：

import cmapUrl from 'pdfjs-dist/cmaps?url'

但说实话，中文字体问题在pdfjs-dist里相对少见，因为PDF解析后字体是以字形渲染的，不是依赖系统字体。真正会遇到字体问题的场景大部分是扫描版PDF或者字体未嵌入的PDF，这已经超出了pdfjs-dist能解决的范畴，需要在PDF生成端根治。

5.6 移动端适配与触摸事件

移动端上使用这个组件，还需要考虑触摸翻页、双指缩放这些交互。基础思路是监听touch事件，结合手势库或者自己计算触点的中心距离。

我自己做移动端适配时发现，pdfjs-dist的渲染本身在移动端没什么问题，问题出在canvas的尺寸上。移动端屏幕宽度小，如果按原始尺寸渲染再CSS缩放，体验不太好。更合理的做法是初始scale根据容器宽度动态计算，让页面宽度刚好填满容器：

function calculateInitialScale(containerWidth, viewportWidth) { return containerWidth / viewportWidth }

这样首屏展示效果最好，用户如果需要放大细节，再通过缩放操作调整。

6. 组件封装经验与后续扩展

在实际项目里，我一般不在业务代码里直接写pdfjs-dist的调用，而是封装成一个通用组件，对外暴露最小化的接口。这样做的好处是，业务方不需要关心pdfjs的复杂API，只需要传入PDF地址和必要的props；以后如果要切换或者升级底层渲染方案，业务代码几乎不用改。

组件对外暴露的核心内容：

• props：url、page、scale
• events：loaded（返回页数等信息）、error（加载失败）、pageChange、scaleChange
• 方法（通过defineExpose）：nextPage、prevPage、zoomIn、zoomOut、print、download

这种设计既保证了组件的复用性，又不把pdfjs的具体实现细节暴露给业务层。

如果要在组件基础上加更复杂的功能，比如PDF文字搜索、书签、标注、批注，pdfjs-dist也提供了相应底层的API支持。TextLayer可以实现文字搜索高亮，AnnotationLayer可以渲染PDF里的注释内容。这些功能的实现复杂度会高很多，一般项目的核心需求做到预览、翻页、缩放、打印其实已经够用了。

如果你在用这个方案做线上项目，最后再分享一个Webpack项目的经验：Webpack 5 + pdfjs-dist 4.x的搭配，Worker配置方式不是?url，而是需要配合copy-webpack-plugin把worker文件复制到构建输出目录，然后手动设置workerSrc，这个和Vite的处理逻辑不一样。如果你用的是老项目，升级构建工具之前，最好先测试一下pdfjs的worker在目标构建环境里是否能正常加载。