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），仅供参考