企业官网建设流程全解析

Slidev 幻灯片导出实战指南：用slidev export与浏览器导出 PDF / PPTX / PNG / Markdown

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev

本文是围绕 Slidev 官方文档 core-exporting.md（配套完整版见 docs/guide/exporting.md）展开的技术指南，系统讲解如何把.md幻灯片源文件一键导出为 PDF、PPTX、PNG、Markdown 四种格式。你既可以用浏览器可视化面板导出，也可以用slidev exportCLI 精确控制点击步进、页面范围、暗色主题、渲染等待策略与输出目录，文中同时结合 export.ts 的实现细节解释每条参数在底层是如何生效的，读完即可在自己的演示项目中落地一套可靠、可复现的导出方案。

为什么需要导出

幻灯片通常运行在浏览器里，交互组件（点击动画、Monaco 编辑器、可拖拽元素等）是浏览器环境下的能力。当需要分享给不依赖网络的观众、打印、归档时，把演示文稿静态化为文件就非常必要。Slidev 支持四种导出目标：

需要指出的是：导出产物中交互功能不可用。若希望在线保留全部交互（点击、代码编辑等），应使用slidev build构建可部署的 Web 应用，参见 hosting.md。

前置条件：安装 Playwright Chromium

PDF、PPTX、PNG 三类导出都依赖 Playwright 在后台无头浏览器中渲染幻灯片，因此必须先在项目里安装playwright-chromium开发依赖：

# pnpm pnpm add -D playwright-chromium # npm npm i -D playwright-chromium # yarn yarn add -D playwright-chromium

注意：只能作为项目本地依赖安装，因为导出的底层模块会按「用户根目录 → workspace 根目录 → 全局 → 当前 CLI 安装位置」的顺序解析该包；找不到时会直接报错提示安装（见 export.ts）。

方式一：浏览器导出器（推荐交互式操作）

从 v0.50.0-beta.11 起，Slidev 提供了开箱即用的浏览器导出 UI，无需安装 Playwright 也能导出。

两种打开方式：

1. 在演示页导航栏More options（更多选项）菜单中点击Export按钮；
2. 直接访问http://localhost:3030/export（默认开发端口，对应页面组件为 export.vue）。

在导出页面中可：

• 选择导出格式并设置参数；
• 实时预览；
• 直接下载结果文件（PDF，或以 PPTX / zip 形式打包的逐页图片）。

浏览器导出器面向现代 Chromium 内核浏览器做了优化；若在 Firefox 等非 Chromium 浏览器中遇到异常，请改用 CLI 导出。

方式二：CLI 导出（可脚本化、可进 CI/CD）

slidev export由@slidev/cli提供，完整参数定义见 docs/builtin/cli.md，ExportArgs类型见 cli.ts。命令基本形态：

slidev export [entry] [options]

• [entry]：幻灯片入口 Markdown 文件，默认slides.md；也支持传多个文件一次导出多份。

PDF 导出（默认格式）

slidev export # 输出 ./slides-export.pdf slidev export --output my-slides.pdf

默认输出文件名为slides-export.pdf（命名规则为[入口文件名]-export，即slides.md → slides-export，随后自动补.pdf后缀）。PPTX / MD 同理会自动补对应后缀，例如--output slides最终生成slides.pdf。

PPTX 导出

slidev export --format pptx

三点重要特性（与源码 export.ts 一致）：

• 每页都是一张图片，因此文字不可选中、不可编辑；这是“所见即所得”的权衡；
• 演讲者备注会逐页写入PPTX 的 notes 区域，适合演讲者直接使用备注讲解；
• 默认开启--with-clicks（点击步进按页拆开）；要关闭请显式传--with-clicks false。这个默认行为在选项合并时实现：withClicks: withClicks ?? format === 'pptx'。

PNG 导出

slidev export --format png

默认导出全部页；结合--range可只截取部分页：

slidev export --format png --range 1-5

不带--with-clicks时每页一个文件（按幻灯片序号命名，如01.png），开启点击步进后文件名会带上步进编号。

Markdown 导出

slidev export --format md

该模式会先为范围内的每一页渲染 PNG，再拼装一个 Markdown 文件：图片使用标题语法引用，并把对应页的演讲者备注原样附在图片之后，页与页之间以---分隔（实现见 export.ts）。

常用导出参数详解

下面按参数逐一说明行为与适用场景。默认值与解析逻辑可对照getExportOptions()（export.ts）。

点击步进导出（--with-clicks）

默认情况下每张幻灯片只导出一页，v-click等点击动画处于未展开的最终态被折叠。如需把每个点击步骤拆成独立页面（PPTX 尤其常用）：

slidev export --with-clicks

底层实现上，导出器打开每页后用键盘发送一次ArrowRight推进到下一步，再读取 URL 中clicks=N参数递归渲染下一个步进，直到没有更多步进为止（见 export.ts）。点击动画的编写方式参见 animations.md。

输出文件名（--output / exportFilename）

slidev export --output my-pdf-export

也可以在 frontmatter（headmatter）里配置，CLI 未传--output时即采用该文件名：

--- exportFilename: my-presentation ---

exportFilename的语义定义于 frontmatter.ts：只写文件名主体，扩展名（.pdf/.pptx等）会自动追加。

页面范围（--range）

slidev export --range 1,4-7,10

范围语法兼容“单页与连续区间混写”，上例会导出第 1、4、5、6、7、10 页；范围解析由@slidev/parser/core提供的parseRangeString完成（调用见 export.ts）。

多入口一次性导出

slidev export slides1.md slides2.md # 每个入口独立产出一个 PDF slidev export *.md # 部分 shell 支持的通配写法

暗色主题（--dark）

slidev export --dark

让导出结果使用当前主题的暗色变体。一个容易忽略的细节：当你的 headmatter 中colorSchema本身配置为暗色时，导出会默认按暗色处理（dark: dark || colorSchema === 'dark'），无需再传--dark。

渲染超时（--timeout）

大演示（嵌入大量远程资源、图表等）渲染耗时更长，默认 30 秒超时可能不够：

slidev export --timeout 60000

该值以毫秒为单位，作用于每次page.goto以及内部若干等待环节（默认30000）。缓慢页面建议配合--wait一起使用。

捕获前等待（--wait）

slidev export --wait 2000

单位为毫秒，表示打开每页并完成内部加载流程后再额外延时，用于兜底异步内容（图表动画、远程字体、第三方 iframe）的最终落定。

等待条件（--wait-until）

--wait-until控制导航的“就绪判定”，取值如下：

slidev export --wait-until networkidle slidev export --wait-until none

选用networkidle以外的值时，请务必检查打印页内容是否完整正确；内容缺失时需用--wait补足（none会被映射为“不等待”，源码中waitUntil === 'none' ? undefined）。

透明背景（--omit-background）

slidev export --omit-background

仅对 PNG/图片类截图有意义：去掉浏览器默认的白色视口底色（注意这与幻灯片里通过 CSS 设置的背景是两回事）。去掉后，页面真实背景将透出，因此通常需要额外 CSS 把应用内所有背景也置为透明：

* { background: transparent !important; }

指定系统浏览器（--executable-path）

无头 Chromium 可能缺少部分系统组件（如某些视频编解码器），此时可把渲染指向本地安装的 Chrome / Edge：

slidev export --executable-path /path/to/chrome

该路径会原样传给chromium.launch({ executablePath })（见 export.ts）。

PDF 书签目录（--with-toc）

从 v0.36.10 起可为 PDF 生成可点击的书签大纲，便于长文档定位：

slidev export --with-toc

实现上会按各页标题层级构造一棵TocItem树（含hideInToc支持），再调用outlinePdf把大纲写入 PDF（见 export.ts）。

逐页渲染（--per-slide）

如果幻灯片包含全局组件，且某几页的状态会“污染”后续页面（例如全局层动画状态不正确），可切换为逐页独立渲染：

slidev export --per-slide

需要权衡的是：逐页模式下 PDF 的跨页锚点链接与书签目录可能失效；同理，全局层如果必须保留可交互上下文，官方建议用slide-top.vue/slide-bottom.vue替代global-top.vue/global-bottom.vue，详见 global-layers.md。源码侧 PDF 两种路径可对照genPagePdfOnePiece()（整页一次打印）与genPagePdfPerSlide()（逐页打印后合并），见 export.ts。

Headmatter 配置导出

除了逐条传 CLI 参数，也可把导出偏好固化到幻灯片 frontmatter，形成团队约定：

--- exportFilename: my-presentation # CLI 未指定 --output 时使用 download: true # build 产物内附带 PDF 下载按钮 export: format: pdf timeout: 30000 withClicks: false ---

• download: true作用于slidev build场景：构建产物中会额外生成一份 PDF 并提供下载按钮，参见 build-with-pdf.md；
• export:下的键名与 CLI 参数一一对应，允许把 pdf 之外的默认format、更长timeout等直接固化在源文件里。

这些配置与 CLI 参数的合并顺序是：headmatter/配置文件中的export段为基底，命令行显式传入的参数覆盖它，因此同一份演示既可内置默认值，又可临时用命令行覆盖（对应getExportOptions()中{ ...config.export, ...args }的展开顺序）。

导出流程底层做了什么

理解导出器的实现能帮你更准确地诊断问题。以 PDF 为例，export.ts 中的渲染主流程大致如下：

1. 解析范围：用parseRangeString展开--range，得到待渲染页列表；
2. 启动浏览器：按--executable-path、画布宽高与--scale（默认 2，即 2 倍高清）创建 context 与页面；
3. 逐页导航到打印视图：对每一页拼接形如/print?print=true&range=...&clicks=N#N的 URL 并goto；路由为memory模式时因内存路由不响应 URL，会自动回退为history模式（export.ts）；
4. 多级就绪等待：等待该页所有.slidev-slide-loading挂载完成、所有带data-waitfor属性指定的元素可见、全部 iframe 加载完成、Mermaid 容器#mermaid-rendering-container渲染结束、并隐藏 Monaco 的 aria 无障碍容器避免干扰截图；
5. 按格式分流：pdf直接打印页面；png逐容器截图；pptx先截图再交给pptxgenjs拼装（同时写入每页备注与作者/主题元数据）；md截图后拼装 Markdown（分派逻辑见 export.ts）；
6. 后处理 PDF：注入标题（取自首屏标题）、作者、关键词、主题等元数据，若启用--with-toc再追加书签大纲（export.ts）。

值得注意的两点默认行为：

• 导出的尺寸与布局配置保持一致：宽度取配置canvasWidth（默认 1920），高度由canvasWidth / aspectRatio计算得出，因此导出结果与浏览器中的画面比例一致；
• PPTX 画布以每英寸 96 像素换算为英寸单位建页，保证跨 Office 版本排版稳定。

故障排查

内容缺失或动画未完成

现象：导出的 PDF 里部分图表、远程内容缺失，或动画停留在中间态。

原因：页面就绪判定过早，异步渲染尚未完成。

对策：加大等待与超时：

slidev export --wait 3000 --timeout 60000

若仍出现超时，可尝试放宽导航判定（详见上文--wait-until的告警说明）：

slidev export --wait-until none

全局层状态错乱

现象：使用了global-top.vue/global-bottom.vue的演示在导出时出现层状态残留或不一致。

对策：改用逐页渲染模式slidev export --per-slide；或将这些全局元素替换为slide-top.vue/slide-bottom.vue，使它们跟随幻灯片上下文而非全局上下文。

Emoji 显示为方框（broken emojis）

现象：导出的 PDF/PNG 中 Emoji 显示为空白方块或豆腐块。

原因：运行环境（尤其容器化 CI 场景）缺少彩色 Emoji 字体。服务端环境请在系统字体目录安装如 Noto Color Emoji 这类字体（下载后放入/usr/local/share/fonts/等目录并执行fc-cache -fv刷新字体缓存）；本地桌面环境请确认系统字体完整，或在--executable-path指定带完整字体的浏览器。相关字体定制方式可参考 config-fonts.md。

CI/CD 中导出失败

若在 CI 流水线里执行导出，需要显式安装 Playwright 所需的 Chromium 浏览器二进制：

npx playwright install chromium

随后正常执行slidev export即可。

延伸阅读

• 完整 CLI 参考（含--theme、构建参数）：docs/builtin/cli.md
• 导出 UI 与浏览器交互能力的官方说明：docs/guide/exporting.md
• 导出器全部实现（范围解析、逐页渲染、PPTX/MD 拼装、PDF 元数据与大纲）：commands/export.ts
• 导出相关类型定义（ExportArgs、导出配置选项）：packages/types/src/cli.ts 与 packages/types/src/config.ts
• 全局层（global layers）与逐页上下文问题：features/global-layers.md
• 构建产物内嵌 PDF 下载按钮（download: true）：features/build-with-pdf.md

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev