怎么将 reveal.js 幻灯片导出为 PDF 文档

作者：键盘侠

时间：2026-11-03

详细讲解如何将 reveal.js 制作的 HTML 幻灯片导出为高质量 PDF 文档，包括官方推荐的浏览器打印参数配置、底层样式重排原理、演讲者备注导出、DeckTape 命令行自动化方案以及常见排版故障解决。

文章目录

将 reveal.js 幻灯片导出为 PDF 文档最直接且官方推荐的做法，是在本地 HTTP 服务下打开幻灯片，在 URL 尾部添加 ?print-pdf 查询参数，随后在 Chromium 内核浏览器（如 Google Chrome 或 Microsoft Edge）中打开打印对话框，将目标打印机设为“另存为 PDF”，并将布局设为“横向”、边距设为“无”、勾选“背景图形”即可完成高质量矢量导出。如果需要将其接入持续交付或自动化脚本，则可以通过无头工具 DeckTape 实行无人值守导出。

怎么将 reveal.js 幻灯片导出为 PDF 文档 — 图 0：reveal.js 幻灯片至 PDF 矢量文档导出转换全景

为什么不能直接在浏览器中按 Ctrl+P 打印？

reveal.js 本质上是一个单页面 Web 应用程序。在普通的屏幕演示模式下，为了适应不同分辨率的显示器，它的布局引擎会使用 CSS transform: scale(...) 对内容进行等比例缩放，并依靠绝对定位（position: absolute）将当前幻灯片居中固定在视口中央，其他幻灯片则被隐藏在可视区域之外。如果此时直接调起系统打印，浏览器只能捕获当前可见的单张幻灯片，导出的 PDF 不仅只有一页，还会因全屏居中样式产生四周裁切或大面积留白。

为了解决这个问题，reveal.js 内置了一套专用的打印样式表。只要在访问地址中传入 ?print-pdf 参数，框架在初始化时就会检测到该参数，进而自动载入打印专用样式，解除绝对定位和缩放矩阵，把所有幻灯片逐一平铺展开成标准的离散文档流，供浏览器打印引擎切片输出。

方法一：通过浏览器打印导出（标准官方流程）

这是日常准备讲义、会议课件分享最常用、效果最可控的方法。整个操作无需安装额外的命令行依赖，只需借助日常使用的现代浏览器即可完成。具体操作分为以下五个环节：

第一步：通过本地 HTTP 服务启动幻灯片

在导出之前，必须确保幻灯片是通过 Web 服务器提供的 HTTP 协议访问，而不是直接在文件管理器中双击 HTML 文件（即 file:// 协议）。

原因在于：现代浏览器的安全沙箱机制会对 file:// 协议施加严格的同源策略限制。直接打开本地文件会导致外部引入的 Web 字体、数学公式渲染脚本（如 MathJax 或 KaTeX）、代码高亮主题以及 Canvas 矢量图表无法跨域异步加载，进而在导出的 PDF 中产生乱码或空白占位。

如果是在 reveal.js 源码工程目录下，可以直接执行项目自带的启动命令：

# 在 reveal.js 项目根目录下运行
npm start

如果是独立的单 HTML 文件演示文稿，可以使用系统内置的轻量服务快速挂载：

# 进入幻灯片所在目录，启动 Python 3 内置静态服务
python3 -m http.server 8000

启动完成后，控制台会输出访问端口，在浏览器中打开 http://localhost:8000 确认幻灯片可以正常翻页显示。

第二步：在 URL 中注入 ?print-pdf 参数

在浏览器地址栏中，将访问链接的末尾加上 ?print-pdf 参数并回车刷新：

# 基础访问路径示例
http://localhost:8000/?print-pdf

注意事项：参数与 Hash 锚点的先后顺序
如果你的幻灯片启用了 Hash 路由（例如指定了起始幻灯片编号 #/2），查询参数 ?print-pdf 必须写在 # 符号的前面，例如：
http://localhost:8000/?print-pdf#/2
如果错误地写成 http://localhost:8000/#/2?print-pdf，参数会被浏览器当作前端 Hash 的一部分而非 HTTP Query，导致 reveal.js 无法识别并无法激活打印样式。

参数注入成功后，页面外观会发生明显变化：原先的全屏交互控制条和切换动画消失，所有幻灯片按照垂直方向依次从上到下完整平铺展示。这说明专用打印样式已经顺利生效。

第三步：唤起系统打印对话框

在页面完成平铺排版后，按下打印快捷键：

Windows / Linux 系统：按下快捷键 Ctrl + P
macOS 系统：按下快捷键 Command + P

官方明确推荐使用 Chromium 内核的浏览器（例如 Google Chrome、Microsoft Edge、Brave 等）。其他浏览器（如 Firefox 或 Safari）在处理 CSS 分页符（page-break-after）以及页面缩放比例时存在内核差异，极易出现内容截断或分页错位。

第四步：精确调整打印关键参数

调出打印面板后，右侧会展示 PDF 打印预览。为了确保版面完整、无白边且背景图案完好，必须按照以下要求逐一核对选项：

打印配置项	推荐设置值	设置原因与技术解释
目标打印机 (Destination)	另存为 PDF (Save as PDF)	调用浏览器内置的 Chromium PDF 矢量转录引擎生成文件。
布局 (Layout)	横向 (Landscape)	绝大多数 reveal.js 幻灯片默认按照 16:9 或 4:3 比例设计，必须匹配横向版面。
边距 (Margins)	无 (None)	默认边距会在四周强行加入物理留白，导致幻灯片内容整体缩小并可能切分为多页。
背景图形 (Background graphics)	必须勾选 [√]	浏览器打印默认启用节墨模式，未勾选会导致深色背景、渐变背景以及代码高亮背景全部变白。
纸张尺寸 (Paper size)	A4 或自适应	与幻灯片比例相符即可；配合“无边距”设置后系统会自动等比满幅填充。
标头和脚注 (Headers and footers)	取消勾选 [ ]	避免在导出的每一页 PDF 顶部和底部打印当前时间、网址及页码字符串。

第五步：检查预览并导出

在右侧预览区中上下滑动滚轮，逐页检查每一张幻灯片的分页情况。确认每页幻灯片恰好占据单张 PDF 纸面、无多余截断后，点击右下角的“保存”按钮，选择本地存储路径即可得到一份清晰的矢量 PDF 文档。

底层原理：reveal.js 是如何实现 PDF 分页的？

理解导出背后的运行机制，有助于我们在遇到复杂动画或排版错乱时快速定位原因。reveal.js 的 PDF 导出流程可以划分为三个层级：

首先是运行期状态捕获。当浏览器加载页面时，reveal.js 的核心初始化代码会执行 window.location.search.match(/print-pdf/gi)。一旦匹配成功，框架会在文档 <head> 中动态插入或激活 reveal.js/dist/theme/print/pdf.css 样式表。

其次是DOM 盒模型与视口解绑。在标准演示模式下，幻灯片外层容器 .reveal 拥有固定的视口尺寸，子节点 .slides 依靠绝对定位和视口缩放矩阵居中呈现。而在激活打印样式后：

外层容器的高宽限制被完全移除，position 属性重置为普通流式布局；
移除 transform: scale(...)，各页幻灯片恢复其实际声明的绝对像素尺寸（默认为 960x700 像素）；
针对每个幻灯片段落元素 .reveal .slides > section 注入 CSS 打印切片规则：break-after: page 与兼容旧内核的 page-break-after: always；
全局声明 @page { size: ...; margin: 0; }，明确告知打印合成器不需要外边距。

最后是Chromium 矢量合成流水线。打印流水线接收到连续的分页盒模型后，将各 section 分块光栅化背景并保留字体、SVG 路径为矢量指令，最终合成为符合 PDF/X 规范的多页矢量流。

进阶控制：演讲者备注与分步动画导出

在实际使用中，经常需要针对不同受众导出不同格式的 PDF。例如为听众提供不含冗余动画的简洁课件，或者为自己打印附带备课讲稿的讲义文档。

1. 导出附带演讲者备注（Speaker Notes）

reveal.js 支持在幻灯片中通过 <aside class="notes">...</aside> 添加演讲备忘录。若想在导出的 PDF 中包含这些备注内容，可以通过 URL 组合参数开启：

# 导出 PDF 并输出演讲者备注
http://localhost:8000/?print-pdf&showNotes=true

或者在初始化脚本中配置 showNotes 属性：

Reveal.initialize({
  // 打印时为每页的演讲者备注单独生成附加页
  showNotes: 'separate-page'
});

当配置为 separate-page 时，每张包含备注的幻灯片后面都会紧跟一页专门排版的文本备忘页，极大方便了线下备课与复习。

2. 控制动画碎片（Fragments）的展示形态

reveal.js 中的 class="fragment" 用于实现点击后逐行显现的动画效果。在 PDF 导出时，有两种截然不同的处理需求：

合并碎片（默认模式）：将同一张幻灯片中的所有动画项直接一次性完整呈现，整张幻灯片只占 1 页 PDF。这适合绝大部分阅读与归档场景。
拆分碎片为独立页面：将每一个动画步进都渲染为独立的 PDF 页面，完全还原演示时的逐字呈现过程。

若需要逐帧保留动画效果，可以在初始化配置中开启 pdfSeparateFragments：

Reveal.initialize({
  // 设为 true 会把每一个 fragment 单独输出为一页 PDF
  // 设为 false 则将同一页内的所有 fragment 展开并合并为 1 页 PDF
  pdfSeparateFragments: true,
  
  // 防止超长内容无限拆页的安全阈值（默认每幻灯片最多切分 2 页）
  pdfMaxPagesPerSlide: 1
});

方法二：使用 DeckTape 命令行实现自动化构建

在团队协作、持续交付（CI/CD）或静态站点生成（如 GitHub Pages）场景下，无法依赖人工打开桌面浏览器手动点击打印。此时可以使用专门针对 HTML 演示文稿设计的无头自动化工具 DeckTape。

1. 使用 npx 免安装直接执行

只要本地安装了 Node.js 环境，可以直接通过 npx 调用 DeckTape，无需全局安装：

# 命令格式：npx decktape [演示框架名称] [本地服务URL] [输出PDF文件名]
npx decktape reveal http://localhost:8000/ presentation.pdf

DeckTape 会在后台自动拉取 Headless Chrome，导航到指定页面，模拟逐页按键翻页并自动拼接成 PDF 文档，执行完毕后在当前目录输出文件。

2. 常用调优参数

当幻灯片包含复杂数学公式（MathJax）、异步图表（ECharts/Chart.js）或超高清矢量图时，网络渲染可能需要额外的加载时间，可以通过参数进行精细控制：

# 设定输出视口分辨率为 1080P，且每页等待渲染延时 1200 毫秒
npx decktape --size 1920x1080 --pause 1200 reveal http://localhost:8000/ slides-hd.pdf

3. Docker 容器化运行（无 Node 环境方案）

在 Linux 构建机或没有 Node.js 的服务器上，推荐直接使用官方 Docker 镜像：

docker run --rm -t -v `pwd`:/slides astefanutti/decktape reveal http://host.docker.internal:8000/ slides.pdf

常见导出故障排查与解决清单

在导出 PDF 时，最常见的排版异常集中在背景、边距、分页和字体四个方面。遇到问题时可以按照以下对照表快速修复：

排查自检备忘录：

背景色丢失或代码变白底：展开 Chrome 打印界面的“更多设置”，务必勾选“背景图形”。
周围有多余白边或内容缩小：将“边距”设置为“无”，且缩放比例保持在 100%。
所有内容挤在第一页：检查 URL 末尾是否准确拼接了 ?print-pdf，且必须放在任何 # 锚点之前。
公式或图标字体未渲染：禁止使用 file:// 协议直接双击打开，务必通过 http://localhost:8000 等本地 Web 服务提供访问。

总结

将 reveal.js 幻灯片导出为 PDF 文档的核心在于利用 ?print-pdf 触发框架内置的打印样式表，再配合 Chromium 内核浏览器的无边距和背景图形选项进行矢量转录。对于日常使用，直接通过 Chrome 快捷键打印最为直观快捷；对于工程化项目与持续发布，采用 DeckTape 命令行工具可以实现完全静默的自动化构建。掌握以上配置细节与底层原理，能够确保导出的 PDF 文件在任何设备上都保持清晰、完整、不变形的排版效果。