1. 从传统演示工具到Slidev我为什么彻底转向用代码写幻灯片过去几年我做技术分享的次数不算少每年少说七八场内部分享、社区线上分享、公司级大会都有。每次准备PPT都让我很痛苦从IDE复制代码到PowerPoint或Keynote里格式永远是乱的想在幻灯片里展示一段带高亮的代码要么贴图要么反复调字体和背景色最要命的是演示文稿和代码仓库完全是两套体系改了代码就要重新截图、重新粘贴、重新对齐版本管理更是不存在的。直到我遇到Slidev这个用Markdown写演示文稿的框架才意识到开发者的演示工具本来就该长成代码的样子。Slidev不是一个把Markdown变成好看的PPT的简单转换器而是一套完整的前端工程化演示方案。它的核心思路是演示文稿就是仓库里的代码页面由Markdown驱动底层由Vue和Vite提供渲染能力。你不需要打开任何可视化编辑器只需要一个文本文件甚至可以直接在Git仓库里维护自己的演讲内容pr、diff、回滚这些开发工作流全部能用在写幻灯片上。对我来说它解决了三个最头疼的问题。第一代码高亮和排版跟IDE里看到的一模一样不用再为代码块样式浪费时间。第二所有内容都是纯文本用Git管理、多人协作、自动构建都是顺理成章的事。第三它自带一套现代化的主题系统和交互机制做出来的演示文稿在视觉上完全不输给精心设计的Keynote模板而且是可以随时用代码调整的。这篇文章适合谁来读如果你是一名受过代码高亮和版本管理毒打的开发者平时需要做技术分享、培训、课程或项目汇报那这篇文章基本可以让你从零开始做出一套能落地的Slidev演示文稿包括环境搭建、核心语法、主题美化、部署分享和避坑经验。如果你是设计师想了解一下代码写PPT能做到什么程度也可以跟着过一遍前几章的语法部分不会太深。2. 环境准备与第一个Slidev项目从npm init到浏览器跑起来2.1 版本要求与包管理器选型在动手之前先说清楚环境。Slidev是构建在Node.js生态上的官方推荐的Node版本是18我用的是Node 20 LTS运行一切正常。如果你还在用Node 16或更老的版本安装依赖的时候大概率会遇到engines不满足的警告所以建议先把Node升级到当前LTS版本。包管理器方面pnpm、npm、yarn都可以。我个人推荐pnpm因为Slidev的依赖树挺庞大的pnpm的硬链接机制能省不少磁盘空间安装速度也快。如果你没装pnpm用npm也一样能跑只是安装时间会长一些。下面的命令我都以pnpm为例换成npm只需要把pnpm改成npm把pnpm create改成npm create即可。2.2 创建项目的实际操作创建一个Slidev项目非常简单官方提供了一键脚手架命令pnpm create slidevlatest执行之后命令行会问你几个问题项目名称、是否包含示例文件、是否安装依赖。我建议初学者选择包含示例因为自带的slides.md已经把常用的功能都演示了一遍分页符、代码高亮、点击动画、双栏布局、主题配置照着改比自己从头查文档要快得多。项目创建好之后目录结构大概是这样的my-slidev/ ├── slides.md ├── .vscode/ │ └── extensions.json ├── public/ │ └── favicon.svg ├── package.json └── ...slides.md是这个项目的核心相当于整个演示文稿的入口文件。你也可以把内容拆成多个Markdown文件放在pages/目录下后续我会讲到多文件组织的方式。public/目录用来放静态资源比如图片、自定义字体、favicon它会被原样复制到最终构建产物里。2.3 启动开发环境本地预览是怎么工作的在项目根目录执行pnpm slidev终端会显示slidev的启动日志随后你在浏览器打开http://localhost:3030就能看到第一张幻灯片了。Slidev在开发模式下是热更新的保存slides.md后浏览器里的页面会立刻刷新这一点对写演示文稿特别友好——你不需要像传统PPT那样反复在编辑器和预览模式之间切换改一行文字就能立即看到效果。这里顺带说一个我常用的技巧如果你的项目里有多个演示文稿不想为每个都新建一个项目可以直接指定入口文件pnpm slidev --entry guide.md这样同一个项目可以维护多份独立的幻灯片适合做系列课程或在不同技术分享里复用同一个工程。不过要注意这种用法下slides.md就不是自动加载的入口了必须每次显式指定。2.4 写出第一份slides.md一个最小可运行示例初次上手最怕的是被太多概念淹没。先不看完整示例我们写一个最朴素的版本先把一页幻灯片的感觉建立起来。把slides.md清空成下面的内容--- theme: default --- # 第一张幻灯片 你好Slidev。 --- # 第二张幻灯片 - 用 --- 分隔页面 - 使用 Markdown 语法 - 支持代码高亮保存后浏览器里应该能看到两页幻灯片按空格键或方向键可以在页面间切换按F可以进入全屏。就这么简单——---分隔符就是新的一页的意思Page One是标题加一句话Page Two是一个无序列表。这是整个Slidev最底层的模型后面所有复杂的排版和交互都是在这个模型上长出来的。3. 核心语法拆解一页Markdown是怎么变成一页幻灯片的3.1 页面模型与Front Matter配置Slidev的页面模型非常直观整个Markdown文件被---水平线分隔成多个区块每个区块就是一页幻灯片。区块的开头可以用YAML语法的Front Matter定义这一页的元信息包括布局、背景色、类名、图标等而区块的正文就是页面的实际内容。举个例子我常用的一页配置是这样的--- layout: two-cols background: https://example.com/bg.png class: text-center --- # 左侧标题 这里写左侧内容。 ::right:: # 右侧标题 这里写右侧内容。layout字段决定了内容如何排版class字段可以给当前页加自定义CSS类名background字段可以直接指定背景图。如果你接触过Hugo或Jekyll这类静态站点生成器Front Matter的语法对你来说几乎是零成本。整套配置项里最重要的就是layout它决定了这一页的骨架Slidev内置了default、cover、center、two-cols、image-right、image-left、full等十多种布局覆盖了常见的演示场景。除了单页配置slides.md顶部的Front Matter是整个演示文稿的全局配置。全局配置里可以指定主题、语言、字体、颜色模式、幻灯片比例、快捷键等。比如下面这个配置会让整份演示文稿使用seriph主题16:9的比例默认浅色模式--- theme: seriph colorSchema: light aspectRatio: 16/9 fonts: sans: Inter serif: Noto Serif SC ---我在实际使用中养成了一个习惯全局配置里尽量少放东西只保留主题、比例和字体其余的页面级属性布局、背景、类名写在每个页面的Front Matter里。这样在多人协作时不容易产生全局配置冲突单独看某一页也能快速理解它的设置。3.2 代码块的展示逻辑技术分享的核心体验既然定位是开发者必备的演示工具代码块自然是Slidev的重头戏。默认情况下代码块会自动做语法高亮底层用的是Shiki。你可以直接在Markdown里写标准的代码块ts {1|3-5|6-8} function greet(name: string) { return Hello, ${name}!; } const users [Alice, Bob]; users.forEach(user { console.log(greet(user)); }); 注意到代码块第一行花括号{1|3-5|6-8}了吗这是Slidev的逐步高亮语法。演示时会按你定义的顺序依次高亮指定行先高亮第1行再高亮3到5行最后高亮6到8行。配合v-click指令可以让代码逐行讲出来而不是一下子把所有内容都抛给观众。这一点在代码评审类的分享中特别有用。如果要高亮一整段代码并让它逐个点击出现还可以用|n的写法ts {all|2|3-4} // 第一点初始化 const app createApp(); // 第二点挂载 app.mount(#app); all表示默认显示全部然后按点击顺序依次聚焦到第2行、第3-4行。讲代码的时候观众的目光会跟着高亮走注意力不会失散。3.3 点击动画与元素显隐指令除了代码高亮页面上的其他元素也需要按步骤出现的效果。Slidev提供了几个非常简洁的指令v-click元素在多次点击后逐个显示v-after在上一个v-click的元素出现之后再显示v-click-hide元素在点击后隐藏v-click.to指定元素在第几次点击时显示用法是在Markdown标题属性里直接写比如--- layout: center --- # 架构总览 div v-click 第一层请求入口 /div div v-click 第二层业务逻辑 /div div v-click 第三层数据存储 /div这样在演示时每按一次空格或点击鼠标就出现一层。我经常用这种方式讲解分层架构比一次性把所有内容摆出来效果好很多——观众不会因为信息过载而跟不上。3.4 演讲者模式与备注临场发挥的保险丝我认为Slidev最被低估的功能是演讲者模式。在演示界面按一次B键或通过右下角的控制按钮可以进入演讲者视图。这个视图里包含当前页内容、下一页预览、当前时间、一个计时器以及很关键的——本页备注。页面的备注写在Markdown里语法是HTML注释# 核心原理 这里讲主体内容。 !-- 这里写演讲备注记得强调缓存失效的问题接前面同事的提问。 --这些备注平时在普通视图里是看不到的只有演讲者模式才会显示。我准备分享的时候会把关键数据、停顿点、现场可能要讲的额外案例写进备注里真正演讲时即使脑子短路瞥一眼备注就能续上。对直播录制场景在演讲者模式下还可以开启自动翻页配合OBS抓屏效果非常稳。4. 主题系统与好看的模板让默认样式脱胎换骨4.1 官方主题与社区主题盘点做好看的演示文稿Slidev的官方主题默认其实就挺耐看但如果你想更进一步主题系统才是关键。Slidev主题本质上是一个npm包通过全局配置里的theme字段指定。官方推荐的主题主要有这几个主题名风格定位适合场景slidev/theme-default简洁、中性通用技术分享、培训slidev/theme-seriph衬线字体、偏学术感论文答辩、课程讲座slidev/theme-apple-basic大标题、留白多、类苹果风产品发布、高层汇报slidev/theme-simple极简、卡片式轻量分享、社区交流slidev/theme-uncanny非常“设计师”的拼贴风创意主题演讲安装主题也很简单比如pnpm add slidev/theme-apple-basic然后在slides.md头部的Front Matter里把theme改成apple-basic即可。社区主题可以在npm搜slidev-theme前缀有非常多风格迥异的包从暗黑风到杂志风都有。我的经验是先不要挑花眼默认的seriph配上自定义字体已经能覆盖90%的技术分享场景。4.2 用主题变量做一键换肤大部分Slidev主题会暴露一组CSS变量你可以很轻松地调整主题色、文字色、背景色。以默认主题为例可以在styles/index.css没有就新建一个里覆盖:root { --slidev-theme-primary: #2563eb; --slidev-theme-secondary: #f59e0b; --slidev-background: #0f172a; }只要主题包声明了这些变量你的整份演示文稿配色会立即变化。我不建议在主题源码里直接改而是单独维护一个styles/目录覆盖全局样式这样主题升级的时候不会冲突。4.3 用UnoCSS工具类快速美化文本布局比写CSS更快的方式是直接用UnoCSS工具类。Slidev底层集成了UnoCSS你可以在Markdown的HTML标签上直接使用原子类div classtext-4xl font-bold text-blue-500 px-8 py-4 border-l-4 border-blue-500 这是一段快速美化后的引文 /div写起来有点像Tailwind但它们会按需生成CSS体积控制得很好。我常用的一组是text-4xl控制字号、font-bold控制字重、text-blue-500控制颜色、border-l-4做左侧强调条。同样效果如果用纯CSS写可能需要10行以上用工具类一行解决而且排版意图一目了然。4.4 封面、目录与尾页一套完整模板的骨架所谓好看的模板其实就是封面、目录、正文页、尾页几个部分风格统一。Slidev里可以自己创建layouts/目录放自定义Vue组件作为页面布局。比如我写了一个极简封面布局template div classcover-layout h-full flex flex-col justify-center items-center slot / /div /template然后在页面里指定--- layout: cover-layout --- # 构建可观测的微服务系统 分享人某某 | 日期2025年6月这里有一个容易踩的坑自定义布局文件名如果是cover-layout.vue页面Front Matter里的layout字段就要写cover-layout不需要带.vue后缀。如果名字带下划线或特殊符号在部分版本里可能解析异常建议统一用小写字母加短横线。4.5 字体与图标决定演示质感的细节我一直觉得演示文稿的质感往往不来自配色而来自字体和图标。Slidev的全局配置里可以指定字体fonts: sans: Inter, Noto Sans SC code: JetBrains Mono, Fira Code如果你用了字体包而没有本地安装Slidev会自动去Google Fonts拉取。这里要注意一个问题在国内网络环境或离线环境分享时字体拉取会失败页面会退回默认字体。所以我的做法是把需要的字体文件放进public/fonts/用font-face自己在styles/里声明引用完全绕开在线依赖。图标方面Slidev集成了Iconify你可以直接在Markdown里写图标i-carbon-analytics classtext-2xl text-green-500 /图标名前缀是i-加集合名加图标名比如i-carbon-、i-mdi-、i-lucide-。这套方案比图片好维护多了不怕缩放糊颜色也能跟着主题CSS走。5. 动画、交互与组件嵌入让代码演示真正活起来5.1 页面过渡动画与点击节奏动画做得好演示节奏感会强很多。Slidev的源码基于是Vue的每一页都对应一个Vue组件实例所以在页面过渡上你能获得的控制能力远超传统演示软件。默认情况下页面切换是淡入淡出加轻微缩放你可以在全局配置里修改transition: slide-lefttransition字段支持fade、slide-left、slide-right、slide-up、slide-down、view-transition等预设。有些主题还会提供transition的两段式定义比如fade-out slide-left意思是一页离开时淡出新页滑入这种层叠效果很自然。我个人的审美倾向是技术分享不要用太花哨的页面动画会分散注意力。默认的淡入淡出就很好要做变化也是在元素级别做v-click而不是整页飞来飞去。5.2 用指令组织复杂的出现顺序前文提到的v-click和v-after在多轮交互下会显得有点乱这里我给一个更规范的做法用v-click配合数字排序。div v-click1第一屏问题背景/div div v-click2第二屏核心思路/div div v-click3第三屏代码实现/div这样即使页面上有几十个元素你也不需要按它们在HTML里的位置来记忆点击顺序数字直接对应演示时要讲到的第几步。调整顺序时改数字即可不用挪动DOM位置对维护非常友好。5.3 嵌入Vue组件与数据图表这是Slidev真正的降维打击能力因为底层是Vite你可以在Markdown里直接使用任何Vue组件。举个例子我在做系统架构分享时经常需要在幻灯片里嵌入一个动态拓扑图组件。只需要把这组件放进components/目录然后在Markdown里引用TopoDiagram :nodesnodes :edgesedges /数据可以写在页面的Front Matter里也可以从外部JSON文件导入。这意味着你的演示文稿可以接入真实数据讲数据报表时不用再截静态图而是直接展示实时计算的图表。Slidev社区里常见的做法是集成ECharts、Chart.js这类图表库。如果你需要的只是相对简单的架构图或流程图Slidev还支持在Markdown代码块里用图表语法直接绘制。这块具体语法各家图表库略有差异我建议先去看对应图表库的文档在Slidev里只是在代码块上额外标识语言类型而已。用熟之后画架构图的效率比用绘图工具手动拖拽高出一个量级。5.4 远程演示与键盘交互远程分享时有个非常方便的功能在启动命令时加pnpm slidev --remote终端会生成一个二维码观众或你自己可以用手机扫码控制翻页。远程连接模式下演讲者和手机端的交互是实时同步的不用担心延迟。这个模式对线下培训特别有用——你不需要特意准备激光翻页笔手机就能充当遥控器。键盘交互方面空格或→翻下一页←翻上一页F全屏B进入演讲者视图D切换深色模式C会开启一个激光笔效果鼠标可以变为高亮圈用来指内容。P可以快速调出演示大纲跳转到任意一页。这些快捷键建议贴在演讲者备注的第一行紧急时候按错了能快速恢复。6. 构建、部署与协作从本地演示到可公开访问的链接6.1 构建为静态站点的原理与产物演示文稿写完后最常用的交付方式是构建成静态站点。Slidev底层是Vite构建命令很简单pnpm slidev build运行之后会在dist/目录生成一套纯静态的SPA站点包含HTML、JS、CSS和静态资源。你不再需要Node环境就能把dist/目录放到任意Web服务器上访问。构建产物里每一页都是一个路由访问路径类似/101、/102默认首页就是第一页。你可以把构建出来的站点看成一个小型的Web应用而不只是一张PPT的导出图片。6.2 三种常见的部署方式我实际用下来下面三种方式最顺手方式操作适用场景GitHub Pages把dist/推送到仓库的gh-pages分支或根目录开源项目配套展示Netlify/Vercel接入仓库配置pnpm slidev build为构建命令dist为输出目录团队协作的自动构建任意Nginx静态服务器上传dist/到站点根目录内网分享、企业环境最省心的是第二种你在GitHub仓库里推一次代码Netlify或Vercel会自动执行构建并发布每次更新演示都只需要提交代码全流程自动化。我第一次把团队的季度技术分享部署到线上链接后再也没用过把PPT文件通过聊天工具传来传去的方式。6.3 导出PDF、图片和PPTX给不写代码的同事不是所有受众都愿意打开一个网页看幻灯片。Slidev的export命令可以把演示文稿导出成多种格式pnpm slidev export --format pdf pnpm slidev export --format png pnpm slidev export --format pptxPDF用于打印和存档PNG适用在文档里插入某几页PPTX则是为了把内容丢给没有Slidev环境的同事进一步编辑。导出PDF时我会加一个Chrome浏览器的可执行路径参数避免系统找不到Chromium示例pnpm slidev export --format pdf --executable-path /path/to/chrome导出的PPTX是基于渲染结果生成的图片所以不能指望拿到之后像原生PPT一样随意改文字这一点必须提前和协作者说清楚否则对方会以为你能交付一份可编辑的PPT源文件。6.4 用Git管理演示稿多人协作的正确姿势最后说一下团队协作。Slidev的演示文稿本质是纯文本这带来一个传统演示工具无法比拟的好处你可以像管理代码一样管理演讲内容。我所在团队的内部技术分享流程是这样的每个人开一个分支修改slides.md或pages/下的文件然后提交PR其他成员在PR里评论提意见合并之后自动部署到预览链接。这种做法最初大家觉得麻烦但坚持两个季度后好处非常明显去年的演示内容今年还能复用历史版本随时可以翻出来查演讲稿不再散落在每个人的电脑里。如果有两个人同时改同一份稿子Git会非常清楚地标出冲突位置比最终版v3修正2.pptx这种文件命名规范可靠一万倍。7. 实战中踩过的坑字体、路径、性能与兼容性7.1 图片和静态资源的路径陷阱Slidev里引用图片最保险的方式是放到public/目录。以public/images/logo.png为例在Markdown里写/images/logo.png就能访问。如果图片放在public之外开发模式可能显示正常但构建之后路径就会404这个坑我踩过不止一次。另外要注意构建到子目录部署时根路径要设置成Base路径。比如站点部署在https://example.com/slide/这个子路径下需要在全局配置里加base: /slide/如果不设所有静态资源的/开头地址会指向域名根目录在子路径下全部打不开。7.2 中文字体渲染与特殊字符中文字体是演示文稿最容易露怯的地方。Slidev默认的英文字体对中文的支持并不好中文字符会回退到浏览器默认字体在Windows和macOS上看到的样式会不一样。我的解决方案是全局配置里显式指定Noto Sans SC或Source Han Sans SC这类中文字体字体文件如果本地没有就下载放进public/fonts/里自行引入。特殊字符方面、、这类字符在Markdown转HTML时可能被转义写代码块时问题不大但如果是在普通正文里写dependency这种XML标签我建议用反引号包起来或者转义为lt;dependencygt;否则页面会被浏览器解析成标签导致显示错乱。7.3 大型演示文稿的性能问题Slidev页面多起来之后开发模式可能会有轻微卡顿这主要原因是vite按需编译和代码块的高亮计算。我试过一份接近两百页的团队文档启动时明显比几十页的稿子慢但这通常不是问题因为演示时每页内容是独立加载的。真正要警惕的是单页内容过重。如果你在一个页面里嵌入了十几个高清大图或巨型组件切换时会掉帧。我的建议是图片先压缩再放进去能切成小图就不要一张长图铺满。另外一个实用技巧是把不需要立即出现的资源放在v-if控制的元素里让它们等到点击时才渲染。7.4 版本升级与插件兼容性Slidev的版本迭代不算慢升级大版本时偶尔会遇到主题插件不兼容的情况。如果你有一套用了很久的主题或自定义组件升级前务必先在临时分支里跑一遍pnpm slidev build确认构建产物正常再合并。我的习惯是在package.json里锁住Slidev的次要版本号比如^0.48这种写法避免某天突然拉到不兼容的小版本导致开发模式崩掉。还有一个容易忽略的点Slidev的自动播放和录音功能跟浏览器版本关系很大尤其是录制相关能力依赖浏览器的MediaRecorder接口。如果现场演示需要录制和回放提前用你要用的那台演示电脑完整测一遍不要等到上台前才发现环境不支持。写在最后的个人体会做演示工具这件事我一直觉得不应该被传统编辑器束缚。Slidev把幻灯片从文档变成了代码这看起来只是一个工程上的转变但实际使用下来它对内容组织方式的影响是根本性的——你会自然地用变量、循环、组件去思考演示内容会习惯性地把每一页拆成有明确语义的模块甚至会为了复用而主动维护一套自己的组件库。这套工作流不一定适合所有人但如果你是一位长期需要做技术分享的开发者我非常建议你花一个下午把核心语法过一遍再拿一次真实分享做试验。等你在浏览器里按下全屏键、看着自己用Markdown写出的代码块逐行高亮时你会明白为什么有人愿意把幻灯片写进仓库里。最后分享一个实用小技巧在slides.md的第一页Front Matter里加上hideInToc: true可以让标题页不出现在大纲视图里。这个细节我一开始没注意直到有次演示大纲里出现了两次首页现场切换时才意识到不对劲。希望这些经验能帮你少走一些弯路。 用代码写幻灯片：Slidev从入门到部署的开发者指南
1. 从传统演示工具到Slidev我为什么彻底转向用代码写幻灯片过去几年我做技术分享的次数不算少每年少说七八场内部分享、社区线上分享、公司级大会都有。每次准备PPT都让我很痛苦从IDE复制代码到PowerPoint或Keynote里格式永远是乱的想在幻灯片里展示一段带高亮的代码要么贴图要么反复调字体和背景色最要命的是演示文稿和代码仓库完全是两套体系改了代码就要重新截图、重新粘贴、重新对齐版本管理更是不存在的。直到我遇到Slidev这个用Markdown写演示文稿的框架才意识到开发者的演示工具本来就该长成代码的样子。Slidev不是一个把Markdown变成好看的PPT的简单转换器而是一套完整的前端工程化演示方案。它的核心思路是演示文稿就是仓库里的代码页面由Markdown驱动底层由Vue和Vite提供渲染能力。你不需要打开任何可视化编辑器只需要一个文本文件甚至可以直接在Git仓库里维护自己的演讲内容pr、diff、回滚这些开发工作流全部能用在写幻灯片上。对我来说它解决了三个最头疼的问题。第一代码高亮和排版跟IDE里看到的一模一样不用再为代码块样式浪费时间。第二所有内容都是纯文本用Git管理、多人协作、自动构建都是顺理成章的事。第三它自带一套现代化的主题系统和交互机制做出来的演示文稿在视觉上完全不输给精心设计的Keynote模板而且是可以随时用代码调整的。这篇文章适合谁来读如果你是一名受过代码高亮和版本管理毒打的开发者平时需要做技术分享、培训、课程或项目汇报那这篇文章基本可以让你从零开始做出一套能落地的Slidev演示文稿包括环境搭建、核心语法、主题美化、部署分享和避坑经验。如果你是设计师想了解一下代码写PPT能做到什么程度也可以跟着过一遍前几章的语法部分不会太深。2. 环境准备与第一个Slidev项目从npm init到浏览器跑起来2.1 版本要求与包管理器选型在动手之前先说清楚环境。Slidev是构建在Node.js生态上的官方推荐的Node版本是18我用的是Node 20 LTS运行一切正常。如果你还在用Node 16或更老的版本安装依赖的时候大概率会遇到engines不满足的警告所以建议先把Node升级到当前LTS版本。包管理器方面pnpm、npm、yarn都可以。我个人推荐pnpm因为Slidev的依赖树挺庞大的pnpm的硬链接机制能省不少磁盘空间安装速度也快。如果你没装pnpm用npm也一样能跑只是安装时间会长一些。下面的命令我都以pnpm为例换成npm只需要把pnpm改成npm把pnpm create改成npm create即可。2.2 创建项目的实际操作创建一个Slidev项目非常简单官方提供了一键脚手架命令pnpm create slidevlatest执行之后命令行会问你几个问题项目名称、是否包含示例文件、是否安装依赖。我建议初学者选择包含示例因为自带的slides.md已经把常用的功能都演示了一遍分页符、代码高亮、点击动画、双栏布局、主题配置照着改比自己从头查文档要快得多。项目创建好之后目录结构大概是这样的my-slidev/ ├── slides.md ├── .vscode/ │ └── extensions.json ├── public/ │ └── favicon.svg ├── package.json └── ...slides.md是这个项目的核心相当于整个演示文稿的入口文件。你也可以把内容拆成多个Markdown文件放在pages/目录下后续我会讲到多文件组织的方式。public/目录用来放静态资源比如图片、自定义字体、favicon它会被原样复制到最终构建产物里。2.3 启动开发环境本地预览是怎么工作的在项目根目录执行pnpm slidev终端会显示slidev的启动日志随后你在浏览器打开http://localhost:3030就能看到第一张幻灯片了。Slidev在开发模式下是热更新的保存slides.md后浏览器里的页面会立刻刷新这一点对写演示文稿特别友好——你不需要像传统PPT那样反复在编辑器和预览模式之间切换改一行文字就能立即看到效果。这里顺带说一个我常用的技巧如果你的项目里有多个演示文稿不想为每个都新建一个项目可以直接指定入口文件pnpm slidev --entry guide.md这样同一个项目可以维护多份独立的幻灯片适合做系列课程或在不同技术分享里复用同一个工程。不过要注意这种用法下slides.md就不是自动加载的入口了必须每次显式指定。2.4 写出第一份slides.md一个最小可运行示例初次上手最怕的是被太多概念淹没。先不看完整示例我们写一个最朴素的版本先把一页幻灯片的感觉建立起来。把slides.md清空成下面的内容--- theme: default --- # 第一张幻灯片 你好Slidev。 --- # 第二张幻灯片 - 用 --- 分隔页面 - 使用 Markdown 语法 - 支持代码高亮保存后浏览器里应该能看到两页幻灯片按空格键或方向键可以在页面间切换按F可以进入全屏。就这么简单——---分隔符就是新的一页的意思Page One是标题加一句话Page Two是一个无序列表。这是整个Slidev最底层的模型后面所有复杂的排版和交互都是在这个模型上长出来的。3. 核心语法拆解一页Markdown是怎么变成一页幻灯片的3.1 页面模型与Front Matter配置Slidev的页面模型非常直观整个Markdown文件被---水平线分隔成多个区块每个区块就是一页幻灯片。区块的开头可以用YAML语法的Front Matter定义这一页的元信息包括布局、背景色、类名、图标等而区块的正文就是页面的实际内容。举个例子我常用的一页配置是这样的--- layout: two-cols background: https://example.com/bg.png class: text-center --- # 左侧标题 这里写左侧内容。 ::right:: # 右侧标题 这里写右侧内容。layout字段决定了内容如何排版class字段可以给当前页加自定义CSS类名background字段可以直接指定背景图。如果你接触过Hugo或Jekyll这类静态站点生成器Front Matter的语法对你来说几乎是零成本。整套配置项里最重要的就是layout它决定了这一页的骨架Slidev内置了default、cover、center、two-cols、image-right、image-left、full等十多种布局覆盖了常见的演示场景。除了单页配置slides.md顶部的Front Matter是整个演示文稿的全局配置。全局配置里可以指定主题、语言、字体、颜色模式、幻灯片比例、快捷键等。比如下面这个配置会让整份演示文稿使用seriph主题16:9的比例默认浅色模式--- theme: seriph colorSchema: light aspectRatio: 16/9 fonts: sans: Inter serif: Noto Serif SC ---我在实际使用中养成了一个习惯全局配置里尽量少放东西只保留主题、比例和字体其余的页面级属性布局、背景、类名写在每个页面的Front Matter里。这样在多人协作时不容易产生全局配置冲突单独看某一页也能快速理解它的设置。3.2 代码块的展示逻辑技术分享的核心体验既然定位是开发者必备的演示工具代码块自然是Slidev的重头戏。默认情况下代码块会自动做语法高亮底层用的是Shiki。你可以直接在Markdown里写标准的代码块ts {1|3-5|6-8} function greet(name: string) { return Hello, ${name}!; } const users [Alice, Bob]; users.forEach(user { console.log(greet(user)); }); 注意到代码块第一行花括号{1|3-5|6-8}了吗这是Slidev的逐步高亮语法。演示时会按你定义的顺序依次高亮指定行先高亮第1行再高亮3到5行最后高亮6到8行。配合v-click指令可以让代码逐行讲出来而不是一下子把所有内容都抛给观众。这一点在代码评审类的分享中特别有用。如果要高亮一整段代码并让它逐个点击出现还可以用|n的写法ts {all|2|3-4} // 第一点初始化 const app createApp(); // 第二点挂载 app.mount(#app); all表示默认显示全部然后按点击顺序依次聚焦到第2行、第3-4行。讲代码的时候观众的目光会跟着高亮走注意力不会失散。3.3 点击动画与元素显隐指令除了代码高亮页面上的其他元素也需要按步骤出现的效果。Slidev提供了几个非常简洁的指令v-click元素在多次点击后逐个显示v-after在上一个v-click的元素出现之后再显示v-click-hide元素在点击后隐藏v-click.to指定元素在第几次点击时显示用法是在Markdown标题属性里直接写比如--- layout: center --- # 架构总览 div v-click 第一层请求入口 /div div v-click 第二层业务逻辑 /div div v-click 第三层数据存储 /div这样在演示时每按一次空格或点击鼠标就出现一层。我经常用这种方式讲解分层架构比一次性把所有内容摆出来效果好很多——观众不会因为信息过载而跟不上。3.4 演讲者模式与备注临场发挥的保险丝我认为Slidev最被低估的功能是演讲者模式。在演示界面按一次B键或通过右下角的控制按钮可以进入演讲者视图。这个视图里包含当前页内容、下一页预览、当前时间、一个计时器以及很关键的——本页备注。页面的备注写在Markdown里语法是HTML注释# 核心原理 这里讲主体内容。 !-- 这里写演讲备注记得强调缓存失效的问题接前面同事的提问。 --这些备注平时在普通视图里是看不到的只有演讲者模式才会显示。我准备分享的时候会把关键数据、停顿点、现场可能要讲的额外案例写进备注里真正演讲时即使脑子短路瞥一眼备注就能续上。对直播录制场景在演讲者模式下还可以开启自动翻页配合OBS抓屏效果非常稳。4. 主题系统与好看的模板让默认样式脱胎换骨4.1 官方主题与社区主题盘点做好看的演示文稿Slidev的官方主题默认其实就挺耐看但如果你想更进一步主题系统才是关键。Slidev主题本质上是一个npm包通过全局配置里的theme字段指定。官方推荐的主题主要有这几个主题名风格定位适合场景slidev/theme-default简洁、中性通用技术分享、培训slidev/theme-seriph衬线字体、偏学术感论文答辩、课程讲座slidev/theme-apple-basic大标题、留白多、类苹果风产品发布、高层汇报slidev/theme-simple极简、卡片式轻量分享、社区交流slidev/theme-uncanny非常“设计师”的拼贴风创意主题演讲安装主题也很简单比如pnpm add slidev/theme-apple-basic然后在slides.md头部的Front Matter里把theme改成apple-basic即可。社区主题可以在npm搜slidev-theme前缀有非常多风格迥异的包从暗黑风到杂志风都有。我的经验是先不要挑花眼默认的seriph配上自定义字体已经能覆盖90%的技术分享场景。4.2 用主题变量做一键换肤大部分Slidev主题会暴露一组CSS变量你可以很轻松地调整主题色、文字色、背景色。以默认主题为例可以在styles/index.css没有就新建一个里覆盖:root { --slidev-theme-primary: #2563eb; --slidev-theme-secondary: #f59e0b; --slidev-background: #0f172a; }只要主题包声明了这些变量你的整份演示文稿配色会立即变化。我不建议在主题源码里直接改而是单独维护一个styles/目录覆盖全局样式这样主题升级的时候不会冲突。4.3 用UnoCSS工具类快速美化文本布局比写CSS更快的方式是直接用UnoCSS工具类。Slidev底层集成了UnoCSS你可以在Markdown的HTML标签上直接使用原子类div classtext-4xl font-bold text-blue-500 px-8 py-4 border-l-4 border-blue-500 这是一段快速美化后的引文 /div写起来有点像Tailwind但它们会按需生成CSS体积控制得很好。我常用的一组是text-4xl控制字号、font-bold控制字重、text-blue-500控制颜色、border-l-4做左侧强调条。同样效果如果用纯CSS写可能需要10行以上用工具类一行解决而且排版意图一目了然。4.4 封面、目录与尾页一套完整模板的骨架所谓好看的模板其实就是封面、目录、正文页、尾页几个部分风格统一。Slidev里可以自己创建layouts/目录放自定义Vue组件作为页面布局。比如我写了一个极简封面布局template div classcover-layout h-full flex flex-col justify-center items-center slot / /div /template然后在页面里指定--- layout: cover-layout --- # 构建可观测的微服务系统 分享人某某 | 日期2025年6月这里有一个容易踩的坑自定义布局文件名如果是cover-layout.vue页面Front Matter里的layout字段就要写cover-layout不需要带.vue后缀。如果名字带下划线或特殊符号在部分版本里可能解析异常建议统一用小写字母加短横线。4.5 字体与图标决定演示质感的细节我一直觉得演示文稿的质感往往不来自配色而来自字体和图标。Slidev的全局配置里可以指定字体fonts: sans: Inter, Noto Sans SC code: JetBrains Mono, Fira Code如果你用了字体包而没有本地安装Slidev会自动去Google Fonts拉取。这里要注意一个问题在国内网络环境或离线环境分享时字体拉取会失败页面会退回默认字体。所以我的做法是把需要的字体文件放进public/fonts/用font-face自己在styles/里声明引用完全绕开在线依赖。图标方面Slidev集成了Iconify你可以直接在Markdown里写图标i-carbon-analytics classtext-2xl text-green-500 /图标名前缀是i-加集合名加图标名比如i-carbon-、i-mdi-、i-lucide-。这套方案比图片好维护多了不怕缩放糊颜色也能跟着主题CSS走。5. 动画、交互与组件嵌入让代码演示真正活起来5.1 页面过渡动画与点击节奏动画做得好演示节奏感会强很多。Slidev的源码基于是Vue的每一页都对应一个Vue组件实例所以在页面过渡上你能获得的控制能力远超传统演示软件。默认情况下页面切换是淡入淡出加轻微缩放你可以在全局配置里修改transition: slide-lefttransition字段支持fade、slide-left、slide-right、slide-up、slide-down、view-transition等预设。有些主题还会提供transition的两段式定义比如fade-out slide-left意思是一页离开时淡出新页滑入这种层叠效果很自然。我个人的审美倾向是技术分享不要用太花哨的页面动画会分散注意力。默认的淡入淡出就很好要做变化也是在元素级别做v-click而不是整页飞来飞去。5.2 用指令组织复杂的出现顺序前文提到的v-click和v-after在多轮交互下会显得有点乱这里我给一个更规范的做法用v-click配合数字排序。div v-click1第一屏问题背景/div div v-click2第二屏核心思路/div div v-click3第三屏代码实现/div这样即使页面上有几十个元素你也不需要按它们在HTML里的位置来记忆点击顺序数字直接对应演示时要讲到的第几步。调整顺序时改数字即可不用挪动DOM位置对维护非常友好。5.3 嵌入Vue组件与数据图表这是Slidev真正的降维打击能力因为底层是Vite你可以在Markdown里直接使用任何Vue组件。举个例子我在做系统架构分享时经常需要在幻灯片里嵌入一个动态拓扑图组件。只需要把这组件放进components/目录然后在Markdown里引用TopoDiagram :nodesnodes :edgesedges /数据可以写在页面的Front Matter里也可以从外部JSON文件导入。这意味着你的演示文稿可以接入真实数据讲数据报表时不用再截静态图而是直接展示实时计算的图表。Slidev社区里常见的做法是集成ECharts、Chart.js这类图表库。如果你需要的只是相对简单的架构图或流程图Slidev还支持在Markdown代码块里用图表语法直接绘制。这块具体语法各家图表库略有差异我建议先去看对应图表库的文档在Slidev里只是在代码块上额外标识语言类型而已。用熟之后画架构图的效率比用绘图工具手动拖拽高出一个量级。5.4 远程演示与键盘交互远程分享时有个非常方便的功能在启动命令时加pnpm slidev --remote终端会生成一个二维码观众或你自己可以用手机扫码控制翻页。远程连接模式下演讲者和手机端的交互是实时同步的不用担心延迟。这个模式对线下培训特别有用——你不需要特意准备激光翻页笔手机就能充当遥控器。键盘交互方面空格或→翻下一页←翻上一页F全屏B进入演讲者视图D切换深色模式C会开启一个激光笔效果鼠标可以变为高亮圈用来指内容。P可以快速调出演示大纲跳转到任意一页。这些快捷键建议贴在演讲者备注的第一行紧急时候按错了能快速恢复。6. 构建、部署与协作从本地演示到可公开访问的链接6.1 构建为静态站点的原理与产物演示文稿写完后最常用的交付方式是构建成静态站点。Slidev底层是Vite构建命令很简单pnpm slidev build运行之后会在dist/目录生成一套纯静态的SPA站点包含HTML、JS、CSS和静态资源。你不再需要Node环境就能把dist/目录放到任意Web服务器上访问。构建产物里每一页都是一个路由访问路径类似/101、/102默认首页就是第一页。你可以把构建出来的站点看成一个小型的Web应用而不只是一张PPT的导出图片。6.2 三种常见的部署方式我实际用下来下面三种方式最顺手方式操作适用场景GitHub Pages把dist/推送到仓库的gh-pages分支或根目录开源项目配套展示Netlify/Vercel接入仓库配置pnpm slidev build为构建命令dist为输出目录团队协作的自动构建任意Nginx静态服务器上传dist/到站点根目录内网分享、企业环境最省心的是第二种你在GitHub仓库里推一次代码Netlify或Vercel会自动执行构建并发布每次更新演示都只需要提交代码全流程自动化。我第一次把团队的季度技术分享部署到线上链接后再也没用过把PPT文件通过聊天工具传来传去的方式。6.3 导出PDF、图片和PPTX给不写代码的同事不是所有受众都愿意打开一个网页看幻灯片。Slidev的export命令可以把演示文稿导出成多种格式pnpm slidev export --format pdf pnpm slidev export --format png pnpm slidev export --format pptxPDF用于打印和存档PNG适用在文档里插入某几页PPTX则是为了把内容丢给没有Slidev环境的同事进一步编辑。导出PDF时我会加一个Chrome浏览器的可执行路径参数避免系统找不到Chromium示例pnpm slidev export --format pdf --executable-path /path/to/chrome导出的PPTX是基于渲染结果生成的图片所以不能指望拿到之后像原生PPT一样随意改文字这一点必须提前和协作者说清楚否则对方会以为你能交付一份可编辑的PPT源文件。6.4 用Git管理演示稿多人协作的正确姿势最后说一下团队协作。Slidev的演示文稿本质是纯文本这带来一个传统演示工具无法比拟的好处你可以像管理代码一样管理演讲内容。我所在团队的内部技术分享流程是这样的每个人开一个分支修改slides.md或pages/下的文件然后提交PR其他成员在PR里评论提意见合并之后自动部署到预览链接。这种做法最初大家觉得麻烦但坚持两个季度后好处非常明显去年的演示内容今年还能复用历史版本随时可以翻出来查演讲稿不再散落在每个人的电脑里。如果有两个人同时改同一份稿子Git会非常清楚地标出冲突位置比最终版v3修正2.pptx这种文件命名规范可靠一万倍。7. 实战中踩过的坑字体、路径、性能与兼容性7.1 图片和静态资源的路径陷阱Slidev里引用图片最保险的方式是放到public/目录。以public/images/logo.png为例在Markdown里写/images/logo.png就能访问。如果图片放在public之外开发模式可能显示正常但构建之后路径就会404这个坑我踩过不止一次。另外要注意构建到子目录部署时根路径要设置成Base路径。比如站点部署在https://example.com/slide/这个子路径下需要在全局配置里加base: /slide/如果不设所有静态资源的/开头地址会指向域名根目录在子路径下全部打不开。7.2 中文字体渲染与特殊字符中文字体是演示文稿最容易露怯的地方。Slidev默认的英文字体对中文的支持并不好中文字符会回退到浏览器默认字体在Windows和macOS上看到的样式会不一样。我的解决方案是全局配置里显式指定Noto Sans SC或Source Han Sans SC这类中文字体字体文件如果本地没有就下载放进public/fonts/里自行引入。特殊字符方面、、这类字符在Markdown转HTML时可能被转义写代码块时问题不大但如果是在普通正文里写dependency这种XML标签我建议用反引号包起来或者转义为lt;dependencygt;否则页面会被浏览器解析成标签导致显示错乱。7.3 大型演示文稿的性能问题Slidev页面多起来之后开发模式可能会有轻微卡顿这主要原因是vite按需编译和代码块的高亮计算。我试过一份接近两百页的团队文档启动时明显比几十页的稿子慢但这通常不是问题因为演示时每页内容是独立加载的。真正要警惕的是单页内容过重。如果你在一个页面里嵌入了十几个高清大图或巨型组件切换时会掉帧。我的建议是图片先压缩再放进去能切成小图就不要一张长图铺满。另外一个实用技巧是把不需要立即出现的资源放在v-if控制的元素里让它们等到点击时才渲染。7.4 版本升级与插件兼容性Slidev的版本迭代不算慢升级大版本时偶尔会遇到主题插件不兼容的情况。如果你有一套用了很久的主题或自定义组件升级前务必先在临时分支里跑一遍pnpm slidev build确认构建产物正常再合并。我的习惯是在package.json里锁住Slidev的次要版本号比如^0.48这种写法避免某天突然拉到不兼容的小版本导致开发模式崩掉。还有一个容易忽略的点Slidev的自动播放和录音功能跟浏览器版本关系很大尤其是录制相关能力依赖浏览器的MediaRecorder接口。如果现场演示需要录制和回放提前用你要用的那台演示电脑完整测一遍不要等到上台前才发现环境不支持。写在最后的个人体会做演示工具这件事我一直觉得不应该被传统编辑器束缚。Slidev把幻灯片从文档变成了代码这看起来只是一个工程上的转变但实际使用下来它对内容组织方式的影响是根本性的——你会自然地用变量、循环、组件去思考演示内容会习惯性地把每一页拆成有明确语义的模块甚至会为了复用而主动维护一套自己的组件库。这套工作流不一定适合所有人但如果你是一位长期需要做技术分享的开发者我非常建议你花一个下午把核心语法过一遍再拿一次真实分享做试验。等你在浏览器里按下全屏键、看着自己用Markdown写出的代码块逐行高亮时你会明白为什么有人愿意把幻灯片写进仓库里。最后分享一个实用小技巧在slides.md的第一页Front Matter里加上hideInToc: true可以让标题页不出现在大纲视图里。这个细节我一开始没注意直到有次演示大纲里出现了两次首页现场切换时才意识到不对劲。希望这些经验能帮你少走一些弯路。