怎么指定版本下载 pdf.js 旧版资源

假设你正在维护一个需要支持老旧浏览器、嵌入式工控屏，或者早期企业微信内置 WebView 的前端系统。当你从 Mozilla 官网直接点击下载最新的 pdf.js 并部署到项目后，很可能立刻在低版本设备上遭遇白屏，并在控制台看到诸如 SyntaxError: Unexpected token '?' 或 Promise.withResolvers is not a function 这类现代 JavaScript 语法错误。此时，唯一的解决方案不是硬性升级用户的浏览器，而是将 pdf.js 回退并锁定到一个能稳定运行的旧版本。

然而，pdf.js 官方网站的首页通常只提供当前最新的发行版本或预发布版本，并不直接展示历史版本的独立下载入口。要在项目中精准使用历史版本，我们需要通过官方 GitHub Releases 仓库、npm 包管理器，或静态资源 CDN 这三条途径进行定向下载。本文将详细演示如何下载指定版本的旧版资源，并解析版本选型与文件配套中的关键注意事项。

一、为什么不能盲目使用最新版：版本与兼容性背景

Mozilla pdf.js 自 3.x 以及 4.x 起，全面拥抱了现代 ECMAScript 语法标准，包括可选链操作符（Optional Chaining）、空值合并运算符（Nullish Coalescing）、顶层 await 以及私有类字段等。同时，官方也逐步调整了对旧版浏览器 Polyfill 的打包策略。

二、方法一：通过 GitHub Releases 获取官方完整预编译包

如果你需要开箱即用的预制阅读器（内置 web/viewer.html 和工具栏），或者需要包含官方自带的完整资源文件，从 GitHub Releases 归档中下载是首选方案。

1. 定位官方 Releases 归档页

Mozilla pdf.js 的所有预编译资产均上传在 GitHub 仓库的 Releases 专区中：

• 发行列表地址：https://github.com/mozilla/pdf.js/releases
• 指定版本直达格式：https://github.com/mozilla/pdf.js/releases/tag/v{版本号}

例如，若要下载经典的 v2.16.105，可以直接访问：
https://github.com/mozilla/pdf.js/releases/tag/v2.16.105

2. 识别并下载对应的 Assets 文件

展开该版本底部的 Assets 列表，你会看到数个压缩文件。请根据以下规则辨析并下载：

• pdfjs-2.16.105-dist.zip：标准发行版。适用于较新的现代浏览器，体积相对精简。
• pdfjs-2.16.105-legacy-dist.zip：旧版兼容发行版（推荐）。经过 Babel 与 Polyfill 处理，向下兼容老旧浏览器内核。

点击链接即可直接下载压缩包。解压后即可得到包含 build/（存放核心 js）、web/（开箱即用阅读器页面）以及 cmaps/（中日韩等复杂文字编码映射表）的完整静态目录。

三、方法二：通过 npm 指定版本获取或打包提取

在前端模块化项目中，或者只需要将 pdf.js 当作静态依赖解压到公共目录时，使用 npm 可以非常精准地下载指定版本，避免通过浏览器手动翻页。

1. 方式 A：工程项目内指定版本安装

在项目根目录下，通过 @版本号 语法直接安装：

# 安装指定的 v2.16.105 版本
npm install pdfjs-dist@2.16.105 --save

# 如果使用的是 yarn 或 pnpm
yarn add pdfjs-dist@2.16.105
pnpm add pdfjs-dist@2.16.105

安装完成后，相关资产将位于 node_modules/pdfjs-dist/ 目录下，其中针对旧版兼容的代码存放在 node_modules/pdfjs-dist/legacy/ 子目录中。

2. 方式 B：使用 npm pack 提取独立压缩包（无需安装到项目）

若不需要在 package.json 中引入依赖，只希望单次提取该版本的离线资源包，可以使用 npm pack 命令：

# 执行命令下载指定版本的官方 tarball 离线包
npm pack pdfjs-dist@2.16.105

# 运行后将在当前目录生成：pdfjs-dist-2.16.105.tgz
# 解压该文件：
tar -xzf pdfjs-dist-2.16.105.tgz

解压后会产生一个 package/ 文件夹，里面包含了该版本的所有核心 JS 文件与 cmaps/ 目录，你可以直接将其重命名并拷贝至项目静态资源目录。

四、方法三：通过公共 CDN 定向获取单文件资源

如果不需要全套 UI，只需要主库和 Worker 脚本嵌入到已有 Canvas 逻辑中，可以直接利用支持版本号索引的公共 CDN 下载对应资源。

1. 常见的稳定 CDN 路径格式

• cdnjs：
  https://cdnjs.cloudflare.com/ajax/libs/pdf.js/{版本号}/pdf.min.js
https://cdnjs.cloudflare.com/ajax/libs/pdf.js/{版本号}/pdf.worker.min.js
• unpkg：
  https://unpkg.com/pdfjs-dist@{版本号}/build/pdf.min.js
https://unpkg.com/pdfjs-dist@{版本号}/legacy/build/pdf.min.js（旧版分支）
• 国内 npm 镜像源（npmmirror）：
  https://registry.npmmirror.com/pdfjs-dist/{版本号}/files/build/pdf.min.js

你可以在浏览器中直接打开上述 URL 并按 Ctrl + S（或 Cmd + S）另存为本地文件，也可以通过 curl 或 wget 命令批量下载：

# 示例：下载 v2.16.105 的核心库与 Worker 脚本
curl -O https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.16.105/pdf.min.js
curl -O https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.16.105/pdf.worker.min.js

五、下载后的关键资产构成与协同关系

下载旧版资源并解压后，很多初学者容易误以为只要在 HTML 里引入一个 pdf.js 就能正常工作。实际上，pdf.js 是一个高度分工的多线程架构库，各部分文件必须协同工作。

1. build/pdf.js 与 build/pdf.worker.js

pdf.js 是暴露给页面的主接口，负责在主线程中调度渲染任务、向 Canvas 提交绘制指令；而 pdf.worker.js 是其在 Web Worker 中运行的后台线程，负责极度消耗 CPU 的 PDF 二进制流反序列化、排版计算与字体解析。

2. cmaps/ 字符映射目录

许多中文、日文和韩文（CJK）PDF 文档并没有在 PDF 内部完整内嵌字体文件，而是依赖外部字符编码映射。如果下载旧版本时遗漏了 cmaps/ 目录，页面虽然能正常打开，但所有中文字符均会变为空白或乱码。

3. web/ 官方阅读器（可选）

该目录提供了完整的 PDF 阅读器界面（包含缩放、翻页、缩略图抽屉、打印和下载按钮）。如果你需要一个现成的开箱即用阅读器，保留该目录并配置其对 build/ 的引用即可。

六、下载后的正确配置与版本验证

将下载下来的旧版资源放置到项目目录（例如 /public/pdfjs/）后，通过以下配置确保正常工作并完成版本验证：

1. 手动绑定 Worker 路径

引入 pdf.js 后，必须显式指定本地同版本的 Worker 路径，避免库自动拉取远程不一致的版本：

// 引入本地下载的旧版 pdf.js
import * as pdfjsLib from '/public/pdfjs/build/pdf.js';

// 显式指定同版本的本地 Worker 文件路径
pdfjsLib.GlobalWorkerOptions.workerSrc = '/public/pdfjs/build/pdf.worker.js';

// 加载文档并配置中文字符集
const loadingTask = pdfjsLib.getDocument({
  url: '/path/to/sample.pdf',
  cMapUrl: '/public/pdfjs/cmaps/',
  cMapPacked: true
});

loadingTask.promise.then(pdf => {
  console.log('PDF 加载成功，总页数：', pdf.numPages);
}).catch(err => {
  console.error('PDF 解析失败：', err);
});

2. 打印验证已加载的版本号

在控制台执行以下命令，核对当前加载的库是否为目标版本：

console.log('当前运行的 PDF.js 版本：', pdfjsLib.version);
// 正确输出示例：当前运行的 PDF.js 版本： 2.16.105

七、总结与建议

指定版本下载 pdf.js 旧版资源的核心逻辑可以归纳为两句话：“按需选型找渠道，主客双端配成套”。当你需要支持早期环境时，切勿直接使用官网首页的“Download”按钮，而应当：

1. 根据目标内核评估版本需求。对于兼顾老旧终端的项目，直接锁定带有 legacy 构建的稳定旧版（如 v2.16.105）。
2. 通过 GitHub Releases Tag（获取带 UI 的全量 Zip 包）、npm pack（获取干净独立的工程离线包）或 CDN 精确 URL 获取对应资产。
3. 务必确保 pdf.js、pdf.worker.js 和 cmaps/ 保持版本一致，并在初始化代码中正确配置 workerSrc 与 cMapUrl。

按照上述路径操作，便可以彻底摆脱新版 pdf.js 在老旧设备上的白屏与语法报错困扰，实现平稳受控的文档预览体验。