Slidev:开发者导向的 Markdown 幻灯片方案——从 npm init slidev 到导出、主题与远程控制的完整实践

Slidev 是一个面向开发者的幻灯片制作与演示工具,以 Markdown 为内容载体,由 Vite 驱动开发服务,支持主题化、代码高亮、LaTeX、图表、绘图、录制与多格式导出。读完本文,你将掌握 Slidev 的初始化流程、常用 CLI 命令与参数、默认模板结构,以及仓库中对应的源码实现位置,从而能独立搭建、定制和发布一套幻灯片。

项目定位:为开发者设计的幻灯片

README 对 Slidev 的定位非常明确:"Presentation slides for developers"。它不是传统 PPT 的替代品,而是一套运行在浏览器中的 Web 应用:幻灯片内容写在 Markdown 文件里,编辑体验接近写技术文档,同时又具备 HTML、Vue 组件与样式系统的全部能力。

其核心特性清单(源自 README 的 Features 一节,括号内为仓库中对应的文档位置)如下:

特性	说明	仓库内参考文档
Markdown-based	以 Markdown 组织内容,专注内容本身	Markdown 语法
Developer Friendly	内置代码高亮、可实时代码编辑等	语法指南 · 代码块
Themable	主题可以打包为 npm 包共享复用	主题指南
Stylish	基于 UnoCSS 的按需原子化样式	配置 UnoCSS
Interactive	无缝嵌入 Vue 组件	目录结构 · 组件
Presenter Mode	独立窗口(甚至手机)控制演示	界面指南 · 演讲者模式
Drawing	在幻灯片上直接绘画与标注	绘图功能
LaTeX	内置数学公式支持	LaTeX 支持
Diagrams	用文本描述生成图表(Mermaid 等)	语法指南 · 图表
Icons	直接引用任意图标集的图标	图标功能
Editor	集成编辑器,另有 VSCode 扩展	使用指南、VSCode 扩展
Recording	内置录屏与摄像头画面	录制功能
Portable	导出 PDF、PNG 或 PPTX	导出指南
Fast	基于 Vite 的即时热更新	—
Hackable	可叠加 Vite 插件、Vue 组件与任意 npm 包	自定义扩展

这些特性并非营销性罗列,在仓库中都能找到对应的实现与文档支撑,例如绘图逻辑位于 recording 同级的 client 逻辑层,导出命令实现在 export 命令模块。

环境要求与本地初始化

README 要求先安装 Node.js >= 20.12.0,然后运行:

npm init slidev

这一版本要求并非文档随口一说:根 package.json 与 CLI 包清单 中的 engines 字段均声明了 "node": ">=20.12.0"。

npm init slidev 到底做了什么

脚手架逻辑位于 create-app 入口,其执行流程为:

1. 交互式询问项目名:若未通过位置参数传入目录名,会提示 Project name:,默认值为 slidev;
2. 包名校验与修正:项目名若不满足 npm 包名规范(正则见 index.mjs 中的 RE_VALID_PACKAGE_NAME),会自动建议一个合法的小写连字符命名并二次确认;
3. 复制模板:从 template 目录 拷贝全部文件,其中 _gitignore 会被重命名为 .gitignore(源码中的 renameFiles 映射);
4. 改写 package.json:将模板包名替换为你输入的项目名;
5. 自动检测包管理器:通过 package-manager-detector 识别 npm/pnpm/yarn 等,并询问是否立即执行安装与启动(对应命令为 <pm> install 和 <pm> run dev);若不立即启动,会打印后续手动执行的命令提示,同时根据包管理器重写生成的 README 中的命令示例。

默认模板结构

模板位于 packages/create-app/template/,包含一个最小可用的幻灯片工程:

• slides.md:幻灯片入口文件(默认入口);
• components/Counter.vue:示例自定义组件,用于演示在幻灯片中嵌入 Vue 组件;
• vite.config.ts:Vite 配置扩展点;
• _gitignore、netlify.toml、vercel.json:版本控制与部署预设;
• package.json:预置了三个核心脚本。

生成的 package.json 脚本与依赖如下(见 template/package.json):

{
  "scripts": {
    "build": "slidev build",
    "dev": "slidev --open",
    "export": "slidev export"
  },
  "dependencies": {
    "@slidev/cli": "^52.19.1",
    "@slidev/theme-default": "latest",
    "@slidev/theme-seriph": "latest",
    "vue": "^3.5.33"
  }
}

即模板同时预装了 default 与 seriph 两套主题,切换主题只需修改 frontmatter 中的 theme 字段。模板 README 还指出开发服务默认访问地址为 http://localhost:3030。

CLI 命令详解(基于源码)

slidev 可执行文件由 CLI 包 提供(bin/slidev.mjs),命令定义集中在 cli.ts。下面按命令梳理可用参数,均以当前仓库代码为准。

1. 默认命令:启动开发服务

直接运行 slidev [entry] 即启动本地 Vite 开发服务器,entry 默认为 slides.md。主要选项(见 cli.ts 的默认命令定义):

选项	别名	类型	说明
--theme	-t	string	覆盖 frontmatter 中指定的主题
--port	-p	number	指定端口
--open	-o	boolean	启动后自动打开浏览器
--remote	—	string	监听公网地址并启用远程控制(作为演示密码)
--tunnel	—	boolean	结合 --remote 通过 Cloudflare Quick Tunnel 暴露到互联网
--log	—	string	日志级别,可选 error / warn / info / silent,默认 warn
--inspect	—	boolean	启用 Vite inspect 插件用于调试
--force	-f	boolean	强制忽略依赖预构建缓存
--bind	—	string	remote 模式下服务器监听的 IP,默认 0.0.0.0
--base	—	string	基础 URL(如 /demo/),默认 /

几个从源码可见的运行时细节:

• 端口策略:默认从 3030 开始,在 3030–4000 范围内寻找可用端口(见 initServer 中调用 get-port-please 的部分),这也解释了模板 README 中 localhost:3030 的由来;
• 终端快捷键:服务运行期间,终端支持 r(重启)、o(打开浏览器)、e(用 $EDITOR 或 VSCode 打开入口文件)、q(退出)、c(在 remote 模式下打印远程控制的终端二维码),实现见 SHORTCUTS 定义;
• 配置变更自动重启:以下 frontmatter 字段变更会触发服务器重启(monaco、routerMode、fonts、css、mdc、editor、theme、seoMeta,见 CONFIG_RESTART_FIELDS);而 setup/shiki.ts、setup/katex.ts、setup/unocss.ts、vite.config.ts、uno.config.ts 等文件的新增/修改/删除则会通过 chokidar 监听触发重启(见 FILES_CHANGE_RESTART);
• MCP 服务:开发模式下默认还会在 http://localhost:<port>/__mcp 暴露一个 MCP(Model Context Protocol)端点,供 AI Agent 查看和编辑幻灯片,见 printInfo 输出逻辑 与 MCP 服务实现。

2. slidev build:构建可托管的 SPA

将幻灯片构建为可部署的静态站点(见 build 命令定义):

选项	默认值	说明
--out	dist	输出目录;构建多个入口时按入口文件名分目录
--base	—	输出基础路径,如 /demo/
--download	—	允许在构建产物中下载 PDF
--without-notes	—	构建产物中排除演讲者备注
--router-mode	—	覆盖路由模式,可选 hash / history / memory;hash 适合 GitHub Pages 之类的子目录部署,memory 则让页码不出现在 URL 中,适合投屏跟随场景

3. slidev export:导出 PDF / PNG / PPTX / Markdown

export [entry..] 会先在本地拉起一个临时 Vite 服务(默认尝试 12445 端口),再通过浏览器完成渲染导出,输出格式支持 pdf、png、pptx、md。完整选项(见 exportOptions):

• --output:输出路径;
• --format:输出格式,pdf | png | pptx | md;
• --timeout / --wait / --wait-until:控制打印页渲染的超时与等待事件(可选 networkidle / load / domcontentloaded / none);
• --range:页码范围,例如 "1,4-5,6";
• --dark:按暗色模式导出;
• --with-clicks(别名 -c):为每一级点击动画分别导出页面;
• --executable-path:覆盖 Playwright 自带的浏览器可执行文件;
• --with-toc:导出带目录大纲的页面;
• --per-slide:逐页滑动导出,对全局组件更友好,但会破坏 PDF 中跨页链接与 TOC;
• --scale:图片导出的缩放系数;
• --omit-background:导出 PNG 时省略默认浏览器背景。

此外还有独立的 export-notes 命令,专门把演讲者备注导出为 PDF(选项含 --output、--timeout、--wait,见 export-notes 命令)。需要说明的是,导出依赖浏览器自动化能力,@slidev/cli 对 playwright-chromium 与 vite-plugin-pwa 均为可选 peer 依赖(见 package.json 的 peerDependenciesMeta),按需安装即可。

4. 其他命令

• slidev format [entry..]:对 Markdown 入口做规范化整理(解析、prettify、回写),实现直接调用 parser;
• slidev mcp [entry]:以 stdio 方式启动 MCP 服务器,供 AI Agent 检查与编辑幻灯片;
• slidev theme eject:把当前 npm 主题"弹出"为本地目录(默认 ./theme),复制主题文件并自动把入口 frontmatter 的 theme 改为本地路径;已弹出的本地主题或 none 会报错退出,逻辑见 theme eject 子命令。

幻灯片怎么写:入口文件与 frontmatter 实战

README 提到可以看 demo 目录获取完整示例,仓库中 demo/ 下有三个可直接运行的演示工程:starter(标准起步)、composable-vue(动画与组件密集型演示)、vue-runner(代码运行演示)。

以 demo/starter/slides.md 为例,入口文件头部是一段 frontmatter 配置:

---
theme: seriph
background: https://cover.sli.dev
title: Welcome to Slidev
info: |
  ## Slidev Starter Template
  Presentation slides for developers.
class: text-center
drawings:
  persist: false
transition: slide-left
comark: true
duration: 35min
---

其中 theme 决定视觉主题,background 设置页面背景,title / info 描述演示信息,class 直接给当前页应用 UnoCSS 工具类,transition 指定页面切换动画,duration 声明演示时长(供计时功能使用)。页面之间用 --- 分隔;每一页的最后一个注释块会被解析为演讲者备注,在 Presenter Mode 中可见可编辑。

正文层面,starter 演示覆盖了最常用的几类写法:

• 代码块增强:````ts {all|4|6} twoslash 支持行号高亮与 TwoSlash 类型悬停提示,<<< @/snippets/external.ts#snippet` 可嵌入外部代码片段;
• 点击动画:v-click 指令(支持 v-after.up、v-click.fade-in 等修饰符组合)让元素随翻页逐次出现,v-mark 指令提供内联标注效果;
• 布局插槽:layout: two-cols 配合 ::right:: 分栏,<Toc> 组件自动生成目录;
• 图表:mermaid 与 plantuml 代码块直接渲染时序图、思维导图等;
• LaTeX:$...$ 与 $$...$$ 公式开箱即用,公式块同样支持点击分页(如 $$ {1|3|all});
• Monaco 编辑器:{monaco} 让代码块变成可编辑编辑器,{monaco-run} 进一步支持在幻灯片中直接运行代码。

这些行为由 markdown 语法转换层实现,对应源码位于 syntax 目录(代码块、片段导入、拖拽、KaTeX、链接等各自的转换模块),解析器核心在 parser 包,相关测试见 parser 测试 与 magic-move 测试。

技术栈:从 README 到依赖清单的印证

README 的 Tech Stack 一节列出了 Slidev 的技术底座,与 CLI 包的依赖清单 可以逐一对应:

技术	在 Slidev 中的角色	仓库内证据
Vite	极速前端工具链,驱动开发服务与构建	vite 依赖;服务创建逻辑 commands/serve.ts
Vue 3 + Markdown	内容层,Markdown 中可直接写 Vue 组件	@vitejs/plugin-vue、unplugin-vue-markdown 依赖
UnoCSS	按需原子化 CSS 引擎	unocss、@unocss/extractor-mdc(针对 Markdown 的类名提取器)依赖
Shiki + Monaco Editor	代码高亮、类型悬停与可编辑代码块	shiki、monaco-editor、@shikijs/twoslash 依赖
RecordRTC	内置录制与摄像头视图	客户端录制逻辑 logic/recording.ts
VueUse 系列	@vueuse/core、@vueuse/motion(v-motion 动画)等	@vueuse/core 依赖;动画模块 modules/v-motion.ts
Iconify	任意图标集的图标访问	unplugin-icons、@iconify-json/* 依赖
Drauu	绘图与标注支持	客户端绘制状态 state/drawings.ts
KaTeX	LaTeX 数学渲染	katex 依赖与 KaTeX 设置
Mermaid	文本描述式图表	Mermaid 内置组件 与 mermaid 配置文档

此外,客户端运行时(布局、内置组件、组合式函数、页面路由)集中在 packages/client,Vite 侧的各类插件与虚拟模块在 packages/slidev/node/vite/,类型定义统一由 packages/types 提供,官方文档站点源码则在 docs/。

仓库导航:继续深入的路径

• 使用文档:docs/guide/(语法、动画、组件、导出、UI)、docs/custom/(目录结构、各类配置项)、docs/features/(功能特性);
• 内置命令与布局参考:docs/builtin/cli.md、docs/builtin/layouts.md、docs/builtin/components.md;
• 可直接运行的演示:demo/starter/、demo/composable-vue/、demo/vue-runner/;
• 主题脚手架:packages/create-theme/,对应文档 docs/guide/write-theme.md;
• VSCode 扩展:packages/vscode/,对应文档 docs/features/vscode-extension.md;
• 端到端测试(含一个完整的 fixture 幻灯片工程):cypress/;
• 项目协议:MIT(见 LICENSE)。

小结

Slidev 的开发者属性体现在整条工具链上:内容即 Markdown,样式即 UnoCSS,交互即 Vue 组件,工具链即 Vite。通过 npm init slidev 两分钟内即可得到一个可运行、可导出、可远程控制的演示工程;而 cli.ts、create-app 脚手架 与 demo/starter/slides.md 这三处源码,是理解其命令、初始化流程与写法约定最直接的入口。