Slidev 构建时生成可下载 PDF:download 配置与 `slidev build --download` 完整实战

发布时间:2026/10/31 16:58:21

Slidev 构建时生成可下载 PDF:download 配置与 `slidev build --download` 完整实战 Slidev 构建时生成可下载 PDFdownload 配置与slidev build --download完整实战【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev在 Slidev 中你可以让静态站点SPA构建产物自带一份 PDF 演讲稿既可在 Markdown 顶部的 headmatter 中用一行download: true开启生成 PDF 内嵌下载按钮也可通过slidev build --download命令行参数在打包时触发同样的渲染管线。本文以 skills/slidev/references/build-pdf.md 为核心骨架结合本仓库packages/slidev、packages/client、packages/types等源码实现讲清 headmatter 与 CLI 两种开关、自定义 PDF 链接、导出参数透传、底层渲染链路以及常见故障排查帮助你为演讲站点一键交付网页 PDF双形态。一、功能定位面向发行Distribution的 PDF 内嵌方案Slidev 官方文档将这一能力描述为Generate a downloadable PDF alongside your built slides——在构建 SPA 的同时生成一份可下载的 PDF。它针对的是已部署站点的访问者这一受众演讲者把幻灯片发布成网页后访客希望直接下载一份 PDF 离线翻阅而不必再自行运行导出命令。与独立的slidev export相比它有几个鲜明特点构建期自动完成不需要额外手动导出slidev build一条命令既产出 SPA 又产出 PDF产物自带下载入口PDF 生成后内置的导航控件区域会自动出现一个 Download as PDF 按钮可跳过生成如果你已有成品 PDF可以通过给download传入字符串 URL只挂下载按钮、不触发任何渲染成本底层复用同一套导出管线生成的 PDF 与slidev export使用相同的 Playwright 渲染实现行为一致。二、在 headmatter 中开启download: true最直接的用法是在幻灯片 Markdown 文件顶部的 headmatter即第一段 frontmatter中加入--- download: true ---2.1 这一开关做了什么从类型定义可以看到该字段的完整语义packages/types/src/frontmatter.ts/** * Show a download button in the SPA build, * could also be a link to custom pdf * * default false */ download?: boolean | string它同时承担两种职责值为布尔真时构建产物中显示下载按钮并在构建阶段触发 PDF 生成值为字符串时仅作为自定义 PDF 链接使用详见下文第三节。其默认值为false对应解析层的默认配置见 packages/parser/src/config.ts 中的download: false。2.2 下载按钮出现在哪里生成的下载按钮位于内置的导航控件NavControls中源码在 packages/client/internals/NavControls.vueIconButton v-ifconfigs.download titleDownload as PDF clickdownloadPDF当且仅当解析后的configs.download有值时导航栏渲染该按钮。点击后调用downloadPDF()其实现位于 packages/client/utils.ts基于file-saver触发浏览器下载export async function downloadPDF() { const { saveAs } await import(file-saver) saveAs( typeof configs.download string ? configs.download : configs.exportFilename ? ${configs.exportFilename}.pdf : ${import.meta.env.BASE_URL}slidev-exported.pdf, ${configs.title}.pdf, ) }可以看到下载来源优先级为自定义字符串 URL headmatter 中的exportFilename 默认的slidev-exported.pdf而落盘到用户本地的文件名则是${configs.title}.pdf即 headmatter 的title字段。另外downloadPDF还被注册进了快捷键见 packages/client/setup/shortcuts.ts方便演示时快速调用。2.3 构建期的判定逻辑download: true之所以能在构建期触发导出是因为底层在 build 模式下通过一个特性开关开启了打印/导出支持packages/slidev/node/options.ts__SLIDEV_FEATURE_PRINT__: options.mode export || (options.mode build [true, true, auto].includes(options.data.config.download)),随后构建收尾阶段根据同一判定进入导出分支逻辑详见 packages/slidev/node/commands/build.tsif ([true, true, auto].includes(options.data.config.download)) { const { exportSlides, getExportOptions } await import(./export) const port 12445 // 用 sirv 静态托管刚生成的 outDir // ... const filename options.data.config.exportFilename || slidev-exported await exportSlides({ port, base: config.base, ...getExportOptions(args, options, join(outDir, ${filename}.pdf)), }) server.close() }即构建完成 SPA 后在本地 12445 端口起一个临时静态服务器托管outDir默认dist随后通过导出的页面级渲染逻辑对每一页截图拼装 PDF最终把 PDF 写回输出目录。文件名优先级是exportFilename未设置则回退到slidev-exported产出dist/slidev-exported.pdf。三、复用已有 PDFdownload传入字符串 URL如果不想在每次构建时都重新渲染 PDF比如内容已稳定、想节省构建时间或 PDF 托管在别处可以把download设为一个自定义 URL 字符串--- download: https://example.com/my-talk.pdf ---这种写法会跳过 PDF 的自动生成因为字符串不在[true, true, auto]的白名单里build.ts 的导出分支不会执行但下载按钮依然会出现在构建产物中——点击时前端直接把该 URL 交给file-saver的saveAs()下载并以title.pdf命名见上文 downloadPDF 的字符串分支。使用建议URL 必须是构建产物部署后可公开访问的地址绝对 URL 最稳妥如果希望按钮指向站点自身的静态 PDF例如部署前手动放到发布目录也可使用相对路径形式但要确保该文件随站点一起发布且路径与base匹配使用字符串模式时不会再产生构建期渲染开销适合 CI 流水线中只打包、不渲染的诉求。四、CLI 方式slidev build --download如果不想把开关写进幻灯片源文件可直接在命令行指定slidev build --download该选项在 CLI 中的注册位置为 packages/slidev/node/cli.ts并提供了-d短别名.option(download, { alias: d, type: boolean, describe: allow download as PDF, })命令行参数会与 headmatter 合并当用户在命令行显式传入--download时若 headmatter 未配置download则写入配置packages/slidev/node/options.tsif (entryOptions.download) config.download || entryOptions.download因此三种合法来源的最终效果一致headmatterdownload: true/ 命令行--download/ 二者同时存在都会让构建产出内嵌下载按钮的 SPA 与配套 PDF。4.1 build 命令的完整形态slidev build同时接受一批导出参数与输出参数见 ExportArgs/BuildArgs 与 cli.ts 的.option()注册组合起来可写slidev build --download --out dist --base /my-talk/ --with-clicks --timeout 60000常用参数速查参数别名说明--download-d生成 PDF 并在 SPA 中加入下载按钮--out dir-o输出目录默认dist--base path—输出 base例如/my-talk/--without-notes—构建产物中剔除演讲者备注--router-mode—覆盖构建产物的路由模式hash/history/memory--inspect—开启 inspect 插件便于调试4.2 build 与 export 的命令差别slidev build是先产出可托管 SPA再顺带导出 PDF而单独的slidev export对应文档 docs/guide/exporting.md则是只做渲染导出、不产出 SPA 页面。两者共享同一份导出选项定义exportOptions()帮助函数注册了--output、--format、--timeout等选项见 packages/slidev/node/cli.ts因此 build 也能透传--format以外的导出参数。如果你的目标是发布网页给访客下载 PDF首选build --download如果只是本地留档用export更轻量。五、导出选项的完整配置无论是 headmatter 开关还是 CLI 开关触发的构建期导出最终都汇入统一的getExportOptions()packages/slidev/node/commands/export.ts。参数按优先级合并headmatter 中的export:子配置 命令行显式参数 CLI 归一化字段。下面从参考文档给出的示例展开slidev build --download --with-clicks --timeout 60000导出项CLI 写法默认行为源码回退值说明每步点击展开--with-clicks/-c仅当format pptx时默认开启每个 click 步骤导出一页适合逐段演示的 PDF渲染超时--timeout ms3000030 秒单页渲染超时上限动画/资源多的页面可调大输出文件名--output pathexportFilename或entry-export注意 build 模式下由outDir exportFilename \|\| slidev-exported决定等待时长--wait ms0导出每页前额外等待的毫秒数等待事件--wait-until evtnetworkidle可选networkidle/load/domcontentloaded/none导出范围--range spec全部页面例如1,4-5,6暗色主题--dark跟随colorSchema dark导出为暗色主题目录页--with-tocfalse导出带大纲目录的页面逐页渲染--per-slidefalse逐页渲染以兼容全局组件但会破坏跨页链接与 PDF 内目录缩放系数--scale n2影响图片类导出的清晰度浏览器路径--executable-path pathPlaywright 内置浏览器覆盖浏览器可执行文件5.1 headmatter 侧的两个配套字段参考文档明确提示 headmatter 中可设置exportFilename、withClicks等。源码证实了这一点exportFilename字符串类型默认packages/parser/src/config.ts。类型注释强调扩展名如.pdf会被自动追加packages/types/src/frontmatter.ts。它在 build 导出分支与独立slidev export中都被优先采纳为输出文件名。export:子配置对象解析后的配置结构ResolvedSlidevConfigSub中包含独立的export子项packages/types/src/config.ts其类型ResolvedExportOptions支持withClicks、executablePath、withToc等packages/types/src/config.ts与getExportOptions中...options.data.config.export的合并逻辑一一对应。组合示例headmatter 声明导出策略让每次构建行为一致、无需记忆 CLI 参数--- title: My Talk download: true exportFilename: my-talk-deck export: withClicks: true timeout: 60000 ---此时构建产物中的 PDF 将被命名为my-talk-deck.pdf前端下载按钮也会以此为准而非默认的slidev-exported.pdf。六、底层渲染链路从按钮到 PDF 的完整调用链将散落的源码串起来download的完整工作流如下入口解析slidev build [--download]将 CLI 参数并入 headmatteroptions.ts构建 SPA执行常规 Vite 构建产出静态站点到outDir判定导出若download为true/true/auto同时启用打印特性并进入导出分支options.ts、build.ts本地托管用sirv在127.0.0.1:12445静态托管产物目录build.tsPlaywright 渲染exportSlides逐页访问渲染地址等待页面与帧稳定对data-waitfor元素、iframe、Mermaid 图等都有专门等待逻辑见 packages/slidev/node/commands/export.ts最终写出exportFilename || slidev-exported命名的 PDF前端入口构建产物导航栏渲染Download as PDF按钮点击触发downloadPDF()完成浏览器下载NavControls.vue、utils.ts。6.1 硬性依赖Playwright Chromium整个 PDF 渲染由 Playwright 驱动浏览器完成。导入逻辑会依次从用户项目根、workspace 根、全局注册表、当前 CLI 安装四处解析playwright-chromiumpackages/slidev/node/commands/export.ts全部失败时抛出明确错误The exporting for Slidev is powered by Playwright, please install it vianpm i -D playwright-chromium因此首次使用download: true或--download前请先在幻灯片项目中安装依赖pnpm add -D playwright-chromium # 或 npm i -D playwright-chromiumskills 文档 skills/slidev/SKILL.md 的Export Build一节也明确注明该前置要求PDF/PPTX/PNG 导出均依赖playwright-chromium若导出时出现浏览器相关报错应先安装此依赖。七、验证与常见问题构建完成后建议做如下验证# 1) 检查 SPA 与 PDF 均生成 ls -lh dist/ # 预期看到 index.html 与 slidev-exported.pdf或 exportFilename 指定的名字 # 2) 本地预览并确认按钮 pnpm preview # 或任意静态服务器指向 dist/打开预览页面导航栏右下角区域应出现 Download as PDF 图标按钮点击后浏览器应下载一份title.pdf。现象原因与对策构建报 The exporting for Slidev is powered by Playwright...未安装playwright-chromium见 6.1 节产物里没有下载按钮download未被解析为真值检查 headmatter 拼写、是否被错误放到分页 frontmatter、或命令行是否真的传入了--download有按钮但点击下载的是默认slidev-exported.pdfheadmatter 设置了自定义字符串 URL 时以 URL 为准布尔模式则确认exportFilename是否需要显式命名导出超时动画、Mermaid、远程资源较多的页面可加大--timeout例如 60000或使用--wait-until load放宽等待条件PDF 每页未展开 click 内容默认不展开 click 步骤需加--with-clicks或 headmatterexport.withClicks: true八、相关资源参考文档本功能速查卡片 skills/slidev/references/build-pdf.md以及总览 skills/slidev/SKILL.md 中 Export Build 表格类型定义download字段 packages/types/src/frontmatter.tsCLI 参数 packages/types/src/cli.ts导出解析配置 packages/types/src/config.ts实现源码构建期导出分支 packages/slidev/node/commands/build.ts导出参数归并 packages/slidev/node/commands/export.tsCLI 注册 packages/slidev/node/cli.ts特性开关与参数合并 packages/slidev/node/options.ts客户端侧下载按钮 packages/client/internals/NavControls.vue下载实现 packages/client/utils.ts相关功能通用导出指南 docs/guide/exporting.md 与配套参考 skills/slidev/references/core-exporting.md、托管部署参考 skills/slidev/references/core-hosting.md【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/10/31 16:56:41

YOLOv9反光衣检测系统:工地安全监控的实时视觉方案

简介:本资源是一套面向计算机相关专业学生与初学者的工地安全监控实战项目,基于YOLOv9实现工人反光衣佩戴状态的高精度目标检测,适用于课程设计、毕业设计及深度学习入门实践。压缩包含187个文件,主体为83个Python源码&#xff08…

2026/10/27 10:51:54

蒙特卡洛树搜索实战:用Python从零构建五子棋AI

简介:基于蒙特卡洛树搜索的AI五子棋算法实现代码,面向学习人工智能与博弈算法的学生或开发者,以UCT算法为核心,完整覆盖选择、扩展、模拟、回传四个标准步骤。资源包共31个文件,包含9个Java源文件与对应class文件、项目…

2026/10/31 16:54:34

自建VoiceStudio:本地声音克隆与语音合成工作台实战指南

做配音交付的朋友,最近应该都有同一个感受:客户不再只满足于"找个声音像的人念一遍",而是会问"能不能用我们老板的声音做企业培训视频""能不能复刻这期播客主播的语气""这个宣传片想用固定一个人的声线批…

2026/10/31 16:54:34

VS Code与MinGW搭建高效C语言开发环境指南

1. 为什么选择VS Code作为C语言开发环境? 作为一名带过三届计算机专业新生的助教,我见过太多同学在C语言环境配置上栽跟头。VS Code之所以成为我的首推工具,是因为它完美平衡了轻量化和功能性——安装包仅70MB左右,却能通过插件扩…

2026/10/31 16:54:34

VS Code配置C语言开发环境全攻略

1. 为什么选择VS Code作为C语言开发环境?作为一名带过三届计算机专业新生的助教,我见过太多同学在C语言环境配置上栽跟头。Visual Studio虽然开箱即用,但体积臃肿;Dev-C又过于老旧。VS Code凭借其轻量级(安装包仅80MB左…

2026/10/31 16:54:34

BPSK匹配滤波原理与根升余弦成形实战

简介:本资源是一份面向通信工程专业本科生及数字信号处理初学者的MATLAB仿真实验包,聚焦BPSK调制系统中匹配滤波与脉冲成形的核心原理验证。通过仿真完整实现BPSK信号生成、根升余弦成形滤波、加性高斯白噪声信道模拟、接收端匹配滤波及误码率统计全过程…

2026/10/31 16:54:34

前端后台翻译三重语义分层指南

1. 这个看似简单的翻译问题,为什么让团队吵了三天?“前台”到底该翻成 frontend 还是 front office?“后台”写成 backend 还是 back office?上周在某跨平台系统重构会上,前端组和后端组的两位技术负责人对着一份中英双…

2026/10/31 16:49:34

金融数据分析转型:AI技术如何解决行业痛点

1. 智能金融分析的行业痛点与转型契机金融投资研究领域正面临前所未有的数据挑战。传统投研团队每天需要处理上百份财报、数千条新闻资讯和实时市场数据,分析师平均花费60%的工作时间在数据收集和基础处理上。这种低效模式导致三个核心痛点:信息过载与处…

2026/10/30 20:55:10

全国计算机二级C语言真题PDF高效刷题指南

简介:这份PDF是全国计算机二级C语言考试的试题与答案解析,专为备考二级C语言的考生准备。内容涵盖C语言特点与设计理念、程序基本组成单位、main函数执行流程、函数嵌套调用规则、标识符命名规范、整型实型字符型数据类型、八进制十六进制数合法形式、运…

2026/10/30 20:55:10

requests+BeautifulSoup:爬虫抓取h1标题的入门实战指南

简介:一份以实战为导向的Python爬虫入门资源,面向具备基本编程基础、希望快速掌握网络数据抓取的初学者,可解决从零编写简单爬虫的常见困惑。实例以requests库发送HTTP请求、BeautifulSoup解析HTML文档,完整演示从网页中提取 标题…

2026/10/30 20:55:09

递推最小二乘参数辨识MATLAB编程:二阶系统与渐消记忆实现

简介:这是一篇面向控制系统、信号处理与机器学习等领域学习者的最小二乘参数辨识程序说明文档。资源共包含一个docx格式文档,压缩包大小七十八KB,内容围绕递推最小二乘算法和渐消记忆最小二乘算法展开:先构造一个极点位于单位圆内…

2026/10/31 0:02:41

猫狗目标检测数据集:VOC/COCO/YOLO三格式一体化实战包

简介:本资源是一套面向计算机视觉初学者与YOLO目标检测实践者的猫狗图像数据集及配套开发工具包,专为快速上手目标检测模型训练而设计。资源包含1000张真实场景高清猫狗图片,标注质量高,同时提供VOC(XML)、…

2026/10/31 0:02:41

HDU2017多校标程复现:算法竞赛工程化真题沙盒

简介:本资源为2017年HDU多校联合训练第一场官方配套资料,面向ACM程序设计竞赛备赛学生、算法爱好者及高校编程集训队成员,旨在提供权威解题参考与完整测试验证环境。压缩包共40个文件,含15份C标程(覆盖全部赛题&#x…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑