pdf.js 官方下载：GitHub Releases 预构建包获取指南

一、定位 GitHub Releases 官方发布页

pdf.js 是 Mozilla 团队主导的开源项目，其唯一官方源代码与二进制资产托管在 GitHub 上。很多初学者在 GitHub 首页会习惯性点击绿色的“Code”按钮并选择“Download ZIP”，这种方式下载的是纯源代码，缺少 build/ 产物目录，无法在浏览器中直接运行。

获取预构建包需要准确访问 Releases 发布归档：

• 官方仓库地址：https://github.com/mozilla/pdf.js
• 直接发布入口：进入仓库首页后，在右侧边栏中找到 Releases，或者在浏览器地址栏直接输入 https://github.com/mozilla/pdf.js/releases。

关键操作点说明

1. 识别正式发布版与预发布版：在 Releases 页面中，每个版本号上方会有状态标识。在正式生产环境中，务必选择带有绿色 Latest 标签的稳定发布版本，避开标注有 Pre-release 的预览测试版。
2. 展开 Assets 附件列表：在目标版本的正文说明底部，默认可能会折叠附件。点击展开 Assets，可以看到该版本对应的所有打包文件。
3. 避开源码压缩包：列表底部的 Source code (zip) 和 Source code (tar.gz) 是未编译代码。我们需要下载的是名称中包含 dist 的压缩包。

二、标准版与旧版兼容版的区别与选择依据

在展开的 Assets 清单中，会看到两份核心 zip 压缩包：标准版 pdfjs-<version>-dist.zip 与旧版兼容版 pdfjs-<version>-legacy-dist.zip。它们虽然基于完全相同的 PDF 解析引擎核心代码，但在打包编译的目标环境策略上有着本质差异。

三、解压后的目录结构与核心组成解析

下载所选的 zip 压缩包后，将其解压到本地或项目静态资源目录。解压后的目录树非常规整，主要由核心逻辑库与开箱即用的查看器界面组成。

pdfjs-[version]-dist/
├── build/
│   ├── pdf.mjs              # 核心主线程 API
│   ├── pdf.worker.mjs       # PDF 解析后台 Worker 脚本
│   └── pdf.sandbox.mjs      # 表单执行与脚本计算沙箱环境
└── web/
    ├── viewer.html          # 官方完整查看器入口网页
    ├── viewer.mjs           # 查看器交互控制逻辑
    ├── viewer.css           # 查看器界面样式表
    ├── cmaps/               # CJK（中日韩）字体字符映射表
    ├── standard_fonts/      # PDF 规范定义的 14 种标准字体
    ├── images/              # 查看器工具栏按钮与图标资源
    └── locale/              # 界面多语言本地化资源包

核心文件的功能分工

• build/pdf.mjs 与 build/pdf.worker.mjs：这是整个 pdf.js 的发动机。主线程的 pdf.mjs 提供 getDocument()、页面视口计算等顶层 API；而 pdf.worker.mjs 运行在独立的 Web Worker 线程中，负责密集的 PDF 二进制数据流解包、流解析与字体矢量解码。这种架构能防止主线程在解析大文件时出现界面假死。
• web/viewer.html：Mozilla 官方维护的高质量 PDF 查看器前端，具备缩略图目录、文本划词选择、关键字搜索、页面缩放、全屏演示和打印功能。如果仅需在系统内展示 PDF，直接以 iframe 方式内嵌此页面是最经济高效的做法。
• cmaps/ 目录：东亚文字编码映射表。如果待展示的文档包含非内嵌中文字体，pdf.js 必须依靠 cmaps 将字符编码正确映射为字形。若遗漏该目录，中文内容会出现方块或乱码。

四、本地运行验证与常见注意事项

完成下载与解压后，应首先在本地完成可用性自检。在这一环节，许多开发者最容易犯的错误是直接在操作系统中双击 web/viewer.html 文件。

1. 本地启动轻量 HTTP 服务

打开终端或命令行工具，进入解压后的 pdf.js 根目录，执行以下任一命令快速启动本地静态服务器：

# 方式一：使用系统内置的 Python 3（推荐）
python3 -m http.server 8000

# 方式二：使用 Node.js 的 npx 临时启动
npx serve -l 8000 .

2. 验证查看器与加载自定义文档

服务启动后，在浏览器地址栏中访问查看器入口：

http://localhost:8000/web/viewer.html

如果能正常显示带工具栏的查看器以及默认的压缩包内测试样张，说明预构建包完整无误。若要加载自己的 PDF 文件，可以通过 file 查询参数传入目标文档的相对路径或 URL 编码地址：

http://localhost:8000/web/viewer.html?file=/my-documents/sample.pdf

3. 跨域访问（CORS）与服务器配置

当 PDF 文件存放在独立的对象存储（如阿里云 OSS、腾讯云 COS、AWS S3）或第三方服务器上时，浏览器的 fetch 请求会受到跨域资源共享（CORS）限制。此时存储服务器必须返回以下 HTTP 响应头：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Expose-Headers: Accept-Ranges, Content-Encoding, Content-Length, Content-Range
Content-Type: application/pdf

五、全流程总结与排错清单

通过 GitHub Releases 获取 pdf.js 预构建包，是在不依赖繁重前端构建链的情况下，最快速、最稳妥的引入方式。整个落地过程可以总结为资产识别、解压规整、协议启动与参数集成四个核心阶段。