怎么使用 npm 安装 pdf.js 及处理依赖冲突

在 npm 生态中，Mozilla 官方维护的 PDF.js 发布的包名是 pdfjs-dist。在现代前端工程中安装该库时，开发者经常遇到两类典型阻碍：一是 npm 7 及以上版本对 peerDependencies 进行严格树解析时触发的 ERESOLVE 依赖冲突；二是构建完成后因 Web Worker 路径或版本不一致抛出的运行时异常。本文直接提供标准安装方式、工程化 Worker 配置示例以及彻底化解版本冲突的有效方案。

一、明确官方包名与安装命令

在 npm 注册表搜索 PDF.js 时，经常能看到 pdf.js、pdfjs 与 pdfjs-dist。许多人在初次使用时直接输入 npm install pdf.js，结果安装的是社区个人早已停更的占位包或第三方实现。Mozilla 官方提供并持续维护的唯一分发包是 pdfjs-dist。

打开终端，进入你的前端或 Node.js 项目根目录（即包含 package.json 的路径），执行如下安装命令：

npm install pdfjs-dist

如果你使用的是现代打包工具（如 Vite 4+、Webpack 5 或支持 ES2022 的构建流水线），上述命令会拉取最新的稳定版本（通常为 v4.x 系列）。安装成功后，可以在 package.json 的 dependencies 中看到形如 "pdfjs-dist": "^4.0.379" 的记录。

二、工程化构建中的 Worker 配置与完整流程

PDF 文件本身解析计算量大，为了防止解析大文件或嵌入字体时阻塞主线程造成页面卡死，PDF.js 采用双模块协同架构：主线程负责 API 调用与 DOM/Canvas 挂载，而复杂的二进制流解析则交由底层的 Web Worker（即 pdf.worker.mjs 或 pdf.worker.js）在独立线程中执行。

这意味着单纯执行 npm i pdfjs-dist 并不能让代码立即工作。在主线程初始化时，必须显式配置 GlobalWorkerOptions.workerSrc。

现代打包工具（Vite / Webpack 5）中的推荐写法

推荐采用基于 new URL(..., import.meta.url) 的标准化资源引用方式，让打包工具在编译期自动提取 Worker 并生成合法的产物路径，避免引入外部 CDN 带来的网络抖动和版本漂移问题：

import * as pdfjsLib from 'pdfjs-dist';

// 声明 Worker 资源的引入路径（以 Vite / Webpack 5 现代 ESM 为例）
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).href;

// 基础加载并渲染第一页示例
async function renderFirstPage(pdfUrl, canvasElement) {
  const loadingTask = pdfjsLib.getDocument(pdfUrl);
  const pdfDocument = await loadingTask.promise;
  const page = await pdfDocument.getPage(1);

  const viewport = page.getViewport({ scale: 1.5 });
  const context = canvasElement.getContext('2d');
  canvasElement.width = viewport.width;
  canvasElement.height = viewport.height;

  const renderContext = {
    canvasContext: context,
    viewport: viewport,
  };
  await page.render(renderContext).promise;
}

三、为什么会出现 npm 依赖冲突（ERESOLVE）

许多前端工程并非直接调用 pdfjs-dist，而是通过第三方 UI 组件库（例如 vue-pdf、react-pdf、ngx-extended-pdf-viewer）进行二次封装调用。在 npm 7 之前，npm 默认会宽松对待对等依赖（peer dependencies）；但自 npm 7 起，安装程序默认会对整个工程的依赖树进行严格的 peerDependencies 校验。

当一个第三方组件在 peerDependencies 中明确声明仅支持 pdfjs-dist@^2.10.377，而你在工程中执行 npm install pdfjs-dist（获取了 4.x），或者另一个依赖项要求了 3.x 时，npm 会发现同一个依赖树下无法生成满足双边约束的无歧义依赖结构，随即终止安装并打印类似如下的错误信息：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: your-project@1.0.0
npm ERR! Found: pdfjs-dist@4.0.379
npm ERR! node_modules/pdfjs-dist
npm ERR!   pdfjs-dist@"^4.0.379" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer pdfjs-dist@"^2.10.377" from vue-pdf@4.3.0

此时若想准确诊断冲突源头，请在项目根目录运行以下命令查看依赖树分支：

npm ls pdfjs-dist

输出中会清晰标出是哪个上游包在哪一层声明了不兼容的 peer 依赖要求。

四、处理依赖冲突的三种有效途径

遇到依赖冲突后，切勿盲目使用 npm i --force，因为该参数会强行破坏依赖树校验，可能导致运行时隐蔽的 undefined 缺失。应根据项目维护状态和技术栈选用以下针对性方案。

方法一：在 package.json 中配置 overrides 强制统一版本（首选）

npm 8.3.0+ 提供了官方原生特性 overrides，允许工程管理者强制重写任何子依赖及其对等依赖的版本。即使上游组件要求的是旧版，只要该组件核心 API 尚能向下兼容，就可以在 package.json 中强制指定统一的 pdfjs-dist 版本：

{
  "name": "my-pdf-project",
  "version": "1.0.0",
  "dependencies": {
    "pdfjs-dist": "^3.11.174",
    "some-pdf-wrapper": "^2.0.0"
  },
  "overrides": {
    "pdfjs-dist": "^3.11.174"
  }
}

配置完成后，删除 package-lock.json 和 node_modules，重新执行 npm install。npm 将遵循 overrides 的全局规则，生成单一且一致的依赖结构，彻底消除依赖冲突警告。

方法二：升级或替换过时的上游包装库

在前端生态中，像经典的 vue-pdf 已经停更数年，其内部锁死在旧版 pdfjs-dist@2.x，不支持现代 Vite 与 Vue 3 环境。面对此类由于封装库长期失修造成的依赖死锁，最佳实践是主动淘汰陈旧库：

• Vue 3 生态： 迁移到活跃维护的 vue-pdf-embed 或 @vue-pdf-viewer/core，或者直接基于原生 pdfjs-dist 写一个百行以内的轻量 Canvas 渲染组件。
• React 生态： 升级 react-pdf 到最新主版本（例如 react-pdf v9 已经原生适配 pdfjs-dist v4）。

从源头上消除过时的对等依赖声明，是保持项目长期健康度的最佳方案。

方法三：使用 --legacy-peer-deps 临时排障

在已有复杂老项目的紧急修复期，如果暂时无法升级老旧组件库，可以在执行安装时附加 --legacy-peer-deps 参数：

npm install pdfjs-dist --legacy-peer-deps

该参数会指示 npm 跳过严格的 peerDependencies 依赖图强校验，恢复到 npm 6 时代的自动忽略策略。虽然它能让安装顺利完成并生成产物，但在后续运行时仍须重点验证以下问题：上游组件调用的旧版 API（如老版 pdfjsLib.renderTextLayer 参数格式）是否已被新版 pdfjs-dist 废弃或移除。

五、运行时常见问题与验证清单

即使成功通过了 npm 安装与依赖解析，在浏览器或构建流水线中还必须防范以下两个常见坑点：

• Warning: API version does not match Worker version： 当主库通过 npm 打包引入，而 workerSrc 误配置了外部公共 CDN 链接且两者的版本号没有锁定完全一致时，控制台便会弹出严重警告甚至报错闪退。务必确保引用的 Worker 脚本与主库完全来自同一个 npm 包实例。
• Node.js / SSR 环境下缺少 Canvas 或 DOMMatrix 报错： pdfjs-dist 默认依赖浏览器 DOM 环境。若在 Next.js / Nuxt 等服务端渲染框架中，必须将 PDF 渲染代码放置在仅客户端执行的生命周期中（例如 Vue 的 onMounted 或 React 的 useEffect），或使用动态 import() 阻止在服务端打包时触发执行。