企业官网建设流程全解析

每次技术分享或者答辩前，我都要跟 PPT 较劲半天：代码块怎么排版才能清晰又不占地方，动画效果怎么加才不显得花哨，配色怎么调才配得上“极客风”。用 PowerPoint 或者 Keynote 给开发者讲东西，总有种穿着西装去修服务器的不对味感。后来我换成了 Slidev，一个基于 Markdown 的演示文稿工具，才终于觉得“对了”。这东西能把幻灯片当成一篇可版本控制的 Markdown 文档来写，代码高亮、Vue 组件、演讲备注、录制视频统统内置，特别适合技术分享、项目汇报、开源项目路演这类场景。如果你也是被模板和格式折腾过的开发者，这篇就聊聊我为什么换掉传统 PPT，以及一套能直接上手复刻的 Slidev 实操流程。

1. 先想清楚：为什么是 Slidev 而不是 PowerPoint

1.1 传统演示工具的“开发者痛点”在哪里

先摊开讲我自己的痛点。PowerPoint 和 Keynote 功能确实强大，但它的核心工作流是“鼠标拖动”：先在画布上摆文本框，再一点一点调对齐、字体、大小，等调完版式，写内容的时间已经耗了一半。到了代码环节更痛苦，从 IDE 往 PPT 里贴代码，格式经常乱掉；字号调小了看不清，调大了又换行；想做一个行高亮，要么手工涂色，要么用插件，整个流程被切得稀碎。最要命的是版本管理，一份 PPT 文件是二进制格式，想在 Git 里看 diff 几乎等于做梦。多人协作时，同事改了哪一页、改了哪些内容，全靠口口相传。

我身边的大部分开发者其实都有类似的感受：不是不会用 PPT，而是觉得这套工具链跟自己的工作方式离得太远。开发者习惯的是“用文本描述结构”，是“一切皆文件”，是“命令式操作”，而不是在画布上一个点一个点地挪元素。Slidev 恰好把演示文稿的生产方式拉回到了开发者最舒服的轨道上：写 Markdown，加载为幻灯片，所有效果用代码控制。

1.2 Slidev 的核心工作逻辑：Markdown 即幻灯片

Slidev 不是又一个“在线模板站”，它本质上是一个基于 Vite 和 Vue 3 的应用，你写的slides.md就是整个演示文稿的源文件。每个 Markdown 中用---分隔的区块，最终会被渲染成一页独立的幻灯片。默认的分隔符是---，全文的 Frontmatter 放在文件开头用 YAML 格式写，页面级的配置则写在每个区块的 Frontmatter 里。

--- theme: seriph title: 我的技术分享 --- # 第一页标题 - 项目背景 - 核心方案 - 效果展示 --- # 第二页标题 这里放第二页的内容

只用记事本就能快速产出一个能跑起来、有动画、有高亮的演示文稿，这是 Slidev 最核心的吸引力。从“拖动元素”到“书写代码”，这种转换看似只是形式变了，实际上改变了创作节奏：你可以先把内容和逻辑写通顺，再来调整样式、动画、布局。这也让幻灯片回归到了“内容为王”的本质。

1.3 横向对比：它跟同类工具有什么区别

市面上基于 Markdown 做幻灯片的工具其实不少，比如 Marp、Reveal.js、Remark。Slidev 的差异化主要有三点：

• 对开发者生态友好：支持安装 npm 主题、导入组件、使用 UnoCSS 任意写原子类样式。相当于所有前端基建都能直接拿进幻灯片里用，写 Vue 组件就等于做了一套可复制的自定义模板。
• 内置开发服务器和热更新：基于 Vite，npm run dev启动后改 Markdown，浏览器里即时生效，旁边还能实时看到演讲者备注和下一页预览。
• 一体化的演示辅助能力：演讲者模式、录制摄像头画面、导出 PDF/PPTX/图片、一键部署到静态托管平台，这些是 Marp 和 Reveal.js 通常需要二次折腾的功能。

如果你只想把 Markdown 快速变成一页页静态 PDF，Marp 就够了；但如果你想在演示过程中使用代码高亮、组件复用、现场录制，Slidev 是更顺手的选择。

2. 核心细节解析：安装、目录结构与第一页幻灯片

2.1 环境准备与项目初始化

Slidev 要求 Node.js 版本在 18 以上。我在不少同学电脑上遇到旧版本跑不起来的情况，所以建议先用node -v确认版本，太老的话直接用 nvm 切到 LTS 版本。

初始化项目有两种方式。第一种是在终端里快速创建一个空目录：

npm create slidev@latest

命令会交互式询问项目名称、是否安装依赖等，按提示选完，进入项目目录执行npm install再npm run dev，浏览器访问http://localhost:3030就能看到默认的第一页幻灯片。

第二种方式是把 Slidev 装进现有前端项目：

npm install @slidev/cli @slidev/theme-default npx slidev

这种方式适合已经在维护某个开源项目，想给 README 或者仓库文档配套一个介绍 slides 的场景。我初期更推荐第一种，目录干净，不会跟其他依赖纠缠。

2.2 理解 slides.md 的分页与 Frontmatter

新建项目的根目录就是入口，默认有一个slides.md。打开它，你会看到最上方有一段被---包裹的内容，这是整份文稿的全局配置：

--- theme: default title: Slidev 分享 info: | ## Slidev 演示文稿 面向开发者的效率工具分享 class: text-center drawings: persist: false transition: slide-left mdc: true ---

常用配置项可以这样理解：theme指定主题包名；title是浏览器标签页和导出文档的标题；info写在备注里，可作为演讲提示；transition控制页面切换动画；class给整页加样式类。如果某页想单独使用不同布局，就在对应页面的---中写页面级 Frontmatter，页面级的优先级高于全局。

分页的本质是 Markdown 的区块拆分。写的时候有一条实用准则：一页只讲一个核心点。不是因为技术受限，而是因为幻灯片本来就是“信息漏斗”，一页塞太多东西，后排观众根本来不及消化。

2.3 第一个可复现的 slides.md 示例

下面这份是我给一次内部技术分享准备的最简版本，覆盖了标题页、列表页、代码页、结束页，可以直接复制到slides.md里体验：

--- theme: seriph title: Slidev 实践分享 info: | 用 Markdown 制作开发者友好的幻灯片 class: text-center --- # Slidev 实践分享 用 Markdown 写幻灯片 简洁 / 可版本管理 / 对开发者友好 <div class="pt-8"> <kbd>空格</kbd> 进入下一屏 </div> --- # 目录 - Slidev 为什么适合开发者 - 核心功能实操 - 常见问题排查 - 部署与导出技巧 --- # 代码高亮示例 ```ts {2-3} function fibonacci(n: number): number { if (n <= 1) return n; return fibonacci(n - 1) + fibonacci(n - 2); }

花括号里的 2-3 表示代码第 2 行到第 3 行会被高亮显示。

小结

• 内容与样式分离
• 像写代码一样做演示文稿
• 导出方便，不怕现场格式错乱

启动后从第一页按空格一直翻到最后一页，你就完成了从 0 到 1 的 Slidev 体验。这里最吸引我的是 `{2-3}` 这种行高亮语法，讲代码时圈重点再也不用截图标红框了。 ## 3. 实操过程与核心环节实现 ### 3.1 布局、主题与组件：让幻灯片不“千篇一律” Slidev 默认提供了几种布局，可以通过 Frontmatter 的 `layout` 字段切换，比如 `cover`、`center`、`two-cols`、`section`。最常用的两个是 `center` 和 `two-cols`。 `two-cols` 讲义式的左右分栏在对比方案时特别好用： ```markdown --- layout: two-cols --- # 左侧内容 - 方案 A - 优点 - 缺点 ::right:: # 右侧内容 - 方案 B - 优点 - 缺点

除了官方自带的布局，Slidev 还支持把任意 Vue 组件直接用进 Markdown。比如我在分享架构设计时，经常需要画一个简单的架构框，我不会再贴一张截图，而是在组件目录里写一个ArchGraph.vue，再在 Markdown 中<ArchGraph />引入。这样架构改动时，只要改组件里的数据，所有页面自动更新，永远不会出现“图跟代码不符”的情况。

主题方面，官方有@slidev/theme-default、@slidev/theme-seriph，社区也有大量主题，比如@slidev/theme-apple-basic。如果你对设计有自己的偏好，也可以直接在全局样式文件里覆盖 CSS 变量，Slidev 里很多颜色都是通过 CSS 变量控制的，改起来比从头写样式快得多。

3.2 代码高亮与“讲代码”的专属姿势

给开发者做演示，代码是屎山里的硬骨头。Slidev 内置了基于 Shiki 的代码高亮，支持的语言非常多，从 JavaScript、Python、Rust 到 Go 都能识别。常用语法有这么几种：

# 高亮第 2 行 ```js {2} # 高亮第 2 行到第 4 行 ```js {2-4} # 高亮第 2 行和第 5 行 ```js {2,5} # 带行号显示，从 10 开始编号 ```js {lines: true, startLine: 10}

startLine这个参数很实用，比如你只需要讲一个 200 行文件里的其中 10 行，可以用它把起始行号设为真实代码的对应行数，观众不会觉得“这里的i是哪来的，为什么从 1 开始”。

对于更复杂的交互式演示，<CodeBlock>组件还能配合editable属性做成可编辑代码块，观众现场提需求，你直接在幻灯片上改代码并重新运行（如果接入了前端演示工具链）。我一般不用这个功能，因为现场容易翻车，但如果是录屏教程，它非常好使。

3.3 绘图、图标与 MDC 语法

MDC（Markdown Component）语法是 Slidev 的一个增强特性，需要在slides.md的全局配置里开启mdc: true。它允许你在普通 Markdown 文本中直接使用 Vue 组件和快捷样式，比如：

::block{} # 一级标题可以这样写 :br 这里用 `::block{}` 包裹了一个块级容器，适合做局部样式隔离。

图标方面，Slidev 内置了carbon和ph两套常用图标库，格式是<carbon:rocket />或<ph:rocket-duotone />。写类型说明、标注流程箭头时，图标能大大减轻纯文字带来的沉闷感。

绘图的话，如果你想画架构图，默认支持 Mermaid 语法（```mermaid代码块直接渲染成图）和 PlantUML。不过我自己很少在演示文稿里用 Mermaid，因为太复杂的图会喧宾夺主。大部分架构图我选择用two-cols加左右对照，观众注意力更集中。

3.4 演讲者模式、快捷键与远程协作

进入演示模式后按p可以打开演讲者模式，演讲稿、当前时间、下一页预览都会显示出来；按f可以切换全屏；按s打开“演讲者窗口”，你可以把演示窗口投到前台大屏，把演讲者窗口留给自己。b是黑屏键，临时让大家讨论问题时特别好用。

Slidev 还支持按左右方向键翻页，上下方向键可以“步进式”浏览一页里的动画元素。有些演示文稿我故意不把所有内容一次性展示，而是用v-click指令逐条出现，这样观众的注意力始终跟着我走。v-click的用法非常直接：

- 第一条内容 <v-click> - 第二条内容 <v-click>

点击一下显示第一条，再点显示第二条，不需要额外配置动画曲线，就能形成自然的递进效果。

3.5 导出与部署：PDF、PPTX 和 GitHub Pages

Slidev 的导出能力是我敢把它用在正式场合的重要原因。导出 PDF 的命令如下：

npx slidev export

它会自动用无头浏览器逐页渲染后生成 PDF。如果某一页有复杂动画，导出时会保留最终状态，这个要提前检查。导出 PPTX 则需要额外安装@slidev/export-pptx插件：

npm install @slidev/export-pptx npx slidev export --format pptx

导出 PPTX 的主要意义是方便传给那些非要一份.pptx文件的协作方，但里面部分复杂组件可能无法完美还原成原生 PPT 元素，只能算“可用”。因此我默认还是优先交付 PDF。

部署到 GitHub Pages 时，构建静态文件就用：

npx slidev build

构建产物在dist/目录，可以整体推到任意静态托管平台。如果遇到图片路径 404 的情况，多半是因为在slides.md里用了相对路径，而构建后的站点目录层级变了，建议把图片放到public/目录下，并用绝对路径引用，比如/screenshot.png。

4. 常见问题与排查技巧实录

4.1 安装和启动阶段的问题

端口被占用：默认端口是3030，如果本地已有一个服务占用，启动会报错。解决办法是用--port参数换一个端口：

npx slidev --port 8080

Node 版本太低：项目推荐 Node 18 及以上。如果npm install时报语法错误或依赖装不上，先用nvm install 18或nvm use 18切到高版本。

依赖安装缓慢或失败：国内网络环境访问 npm 官方源确实慢，有些人会换源，但我更建议用npm install --registry=https://registry.npmmirror.com只给当前项目换源，避免污染全局配置。

4.2 内容渲染和样式问题

代码块不换行且溢出：长代码默认容易溢出屏幕，解决办法是开启代码块横向滚动，或者手动换行并利用{lines: true}显示行号，让观众明确知道换行后的归属。

图片不显示：优先把图片放入public/目录，再用/images/xxx.png引用。如果在本地能看到、部署后看不到，那必然是在 build 后的路径不一致，这时先检查base配置。GitHub Pages 部署需要特别注意仓库名路径，通常需要在构建命令里加参数：

npx slidev build --base /repo-name/

动画不生效：检查是否在slides.md中启用了transition，以及v-click是否正确闭合。某些旧版本的浏览器对 Web Animations API 支持不好，更新浏览器或禁用复杂过渡可以解决。

4.3 导出和演示现场问题

导出 PDF 时字体被替换或中文乱码：Slidev 导出的底层无头浏览器不会自动安装你本机的中文字体，需要在系统里安装好需要的中文字体，比如思源黑体。否则 PDF 里的中文可能变成方框。推荐在全局样式中显式指定字体族：

html, body, #app { font-family: 'Source Han Sans CN', 'PingFang SC', 'Microsoft YaHei', sans-serif; }

导出时图片模糊或布局溢出：npx slidev export默认使用视口大小导出，如果页面内容超过了视口，PDF 里就会溢出。先用浏览器打开演示文稿，按F11全屏预览一遍，确认所有页面没有横向滚动条再导出。

现场投影比例不对：在slides.md中设置aspectRatio: '16/9'或aspectRatio: '4/3'，投影仪如果突然不支持 16:9，只能临时在浏览器里缩放，或者提前导出 PDF 当后备方案。我遇到过几次现场 HDMI 输出异常，这时 PDF 就是救命稻草。

4.4 几个很容易被忽略的实用技巧

• 备注区：在每页 Markdown 的末尾用<!-- 这里是备注 -->写备注，演讲者模式里才会显示，观众看不到。这是一个练习演讲和埋梗的好地方。
• 本地录制：Slidev 支持录制演讲者摄像头画面，命令是npx slidev record，它会输出一个视频文件，可以直接作为线上分享的回放素材。
• 用---做垂直分隔：同一个页面内部想制造切换动画，可以使用---加上v-click，这种“同一页多屏展示”的方式适合一个模块内部的递进讲解。
• 主题覆盖：与其从零写主题，不如npm view @slidev/theme-*搜一下现有的主题，选一个接近的风格再微调。

5. 我最后想分享的一点体会

用了大半年 Slidev 之后，我再也没法心安理得地打开 PowerPoint 排模板。最直观的变化不是“做幻灯片变快了”，而是我敢随时改幻灯片了。以前改 PPT 要重新导出、重新传群文件，现在直接在slides.md里改一行文字，保存浏览器就刷新，分享出去的链接也同步更新。如果你要负责一次技术分享、项目复盘或者开源路演，我建议花两个小时把 Slidev 跑通。别急着堆功能，先写七八页 Markdown，把标题、列表、代码高亮、演讲者模式用熟，你会发现做演示文稿这件事，终于不需要离开终端了。