Slidev CLI 完全指南：@slidev/cli 的开发、构建、导出与 MCP 命令详解

本文基于 docs/builtin/cli.md 整理，系统讲解 Slidev 命令行工具 @slidev/cli 暴露的 slidev 二进制命令：从启动本地开发服务器、构建可托管的 SPA、导出 PDF/PNG/PPTX，到格式化 Markdown、启动 MCP 服务器以及主题 eject。读完本文，你将掌握每个子命令的完整参数、默认值与底层实现逻辑（对应源码位于 packages/slidev/node/cli.ts），并理解参数如何被 Vite、Playwright 等底层依赖消费。

安装与前置条件

@slidev/cli 包暴露一个名为 slidev 的可执行文件（在 packages/slidev/package.json 中声明为 "bin": { "slidev": "./bin/slidev.mjs" }），用于开发、构建和导出幻灯片。使用前有两种安装方式：

• 全局安装 @slidev/cli；
• 在 Node.js 项目本地安装。通过 npm init slidev 创建的项目已经本地安装了 CLI。

从 packages/slidev/package.json 的 engines 字段可以确认，CLI 要求 Node.js >=20.12.0。

注意：通常 npx slidev 不受支持，因为包名实际上是 @slidev/cli 而不是 slidev。

命令行参数约定

CLI 基于 yargs 构建（见 packages/slidev/node/cli.ts 中的 cli = yargs(...)），命令选项遵循两条约定：

1. 选项值可以跟空格或 = 传递，两者等价：slidev --port 8080 等价于 slidev --port=8080；
2. 布尔选项可以省略 true：slidev --open 等价于 slidev --open true。

如果你通过 npm scripts 运行 Slidev，记得在选项前加 --，把参数透传给 Slidev：

npm run slidev -- --remote --port 8080 --open

slidev [entry]：启动本地开发服务器

缺省命令（不带子命令时）用于启动 Slidev 的本地服务器。入口参数 [entry]（字符串，默认 slides.md）是包含幻灯片的 Markdown 文件路径。

参数一览

参数	类型/默认值	说明
--port, -p	数字，默认 3030	端口号
--base	字符串，默认 /	基础 URL（遵循 Vite 的 base 语义，须以 / 开头和结尾，源码在 printInfo 中会校验并不满足时直接退出）
--open, -o	布尔，默认 false	启动后在浏览器中打开
--remote [password]	字符串	监听公网主机并启用远程控制；若传了密码，则演示者模式变为私密，只有 URL 查询参数 password 携带该密码才能访问
--bind	字符串，默认 0.0.0.0	远程模式下服务器监听的 IP 地址
--log	'error' / 'warn' / 'info' / 'silent'，默认 'warn'	日志级别，直接透传给 Vite 的 logLevel
--force, -f	布尔，默认 false	强制预构建优化器忽略缓存并重新打包
--theme, -t	字符串	覆盖主题（--theme 是所有命令的公共选项，见 commonOptions）

源码级细节：端口分配与主机监听

从 packages/slidev/node/cli.ts 的实现可以确认几处关键行为：

• 若未显式指定端口，CLI 用 get-port-please 从 3030 起在 3030–4000 区间寻找空闲端口，并以 strictPort: true 启动 Vite，即找到冲突后不会再自动换端口；
• --remote 未传时服务器只绑定 localhost；一旦启用远程模式，则改为绑定 --bind 指定的地址（默认 0.0.0.0），启动后终端会打印局域网地址、公网 IP（通过 public-ip 解析）以及远程控制 URL（带 ?password= 查询参数）；
• 启动后终端提供快捷键：r 重启、o 打开浏览器、e 用 $EDITOR（默认 code）编辑入口文件、q 退出，远程模式下还有 c 生成远程控制地址的终端二维码（基于 uqr 渲染）；
• 开发服务器会监视各 root 下的 setup/*.ts、uno.config.ts、vite.config.* 等文件（FILES_CHANGE_RESTART 列表），变更后自动重启；检测到 monaco、routerMode、fonts、css、mdc、editor、theme、seoMeta 等配置项（CONFIG_RESTART_FIELDS）变化时同样触发重启，避免热更新覆盖结构性配置。

此外，当前仓库源码中还存在文档未列出的 --tunnel 选项：开启 Cloudflare Quick Tunnel，把 Slidev 暴露到互联网（需配合 --remote），启动后终端会打印隧道 URL。相关细节可参见 远程访问文档。

slidev build [entry]：构建可托管的 SPA

构建一个可托管的单页应用，更多说明见 部署指南。

参数一览

参数	类型/默认值	说明
[entry]	字符串，默认 slides.md	幻灯片 Markdown 文件路径
--out, -o	字符串，默认 dist	输出目录
--base	字符串，默认 /	基础 URL
--download	布尔，默认 false	允许在 SPA 内以 PDF 形式下载幻灯片
--theme, -t	字符串	覆盖主题
--without-notes	布尔，默认 false	从 SPA 中排除演讲者备注

源码级细节：构建产物里还做了什么

从 packages/slidev/node/commands/build.ts 可以看到构建流程在 viteBuild 之后还会完成若干托管向的工作：

• 将 index.html 复制为 404.html，兼容 GitHub Pages 这类子目录部署；
• 生成 Netlify 风格的 _redirects 文件（* /index.html 200），保证 SPA 刷新不 404；
• 若 frontmatter 中配置了 seoMeta.ogImage 为相对路径或 'auto'，会复制现有 og 图或临时启动一个静态服务器、借导出管线渲染第一页生成 og 图；
• 当 download 配置为 true/'auto' 时，构建阶段会直接调用导出管线，把 PDF 一并放进输出目录，使 SPA 内可下载 PDF。

值得注意的是，cli.ts 中 build 命令实际接受 entry..（多个入口）：传入多个入口时，每个入口的输出会被放进 out/<入口名>/ 子目录。另外源码还支持 --router-mode（hash / history / memory），用于覆盖构建产物中的路由模式——hash 适合 GitHub Pages 子目录部署，memory 则把页码从 URL 中隐藏，适合 kiosk/跟随者演示场景。

slidev export [entry]：导出 PDF 及其他格式

将幻灯片导出为 PDF（或其他格式），更多说明见 导出指南。

参数一览

参数	类型/默认值	说明
[entry]	字符串，默认 slides.md	幻灯片 Markdown 入口路径
--output	字符串	输出路径；不传则依次回退到 frontmatter 的 exportFilename 配置，再到 [入口文件名]-export
--format	'pdf' / 'png' / 'pptx' / 'md'，默认 'pdf'	输出格式
--timeout	数字，默认 30000	打印页渲染的超时时间（对应 Playwright page.goto 的 timeout）
--range	字符串	要导出的页码范围，例如 '1,4-5,6'
--dark	布尔，默认 false	以暗色主题导出
--with-clicks, -c	布尔	为每一个 click 动画步骤导出独立页面，参见 click 动画
--theme, -t	字符串	覆盖主题
--omit-background	布尔，默认 false	去除默认浏览器背景（PNG 导出时得到透明背景）

源码级细节：导出管线如何解析参数

导出的实际参数组装在 packages/slidev/node/commands/export.ts 的 getExportOptions 中完成，它把三层来源合并：frontmatter 的 export 配置 < 命令行参数 < 内置默认值。几个值得注意的默认行为：

• waitUntil 默认 'networkidle'（对应 Playwright 的 goto 等待策略），传 'none' 则不等；
• dark 为 false 时，若 frontmatter 中 colorSchema: 'dark' 也自动按暗色导出；
• withClicks 未显式指定时，导出 pptx 格式默认启用（withClicks ?? format === 'pptx'），即 PPTX 天然按 click 步骤展开；
• 画布尺寸取自配置的 canvasWidth 与 aspectRatio，scale 默认 2（图片导出的倍率）。

cli.ts 中的 exportOptions 还定义了文档未列出的若干高级选项：--wait（每页导出前额外等待的毫秒数）、--wait-until（networkidle / load / domcontentloaded / none）、--executable-path（覆盖 Playwright 自带的浏览器可执行文件）、--with-toc（在 PDF 中生成书签大纲）、--per-slide（逐页渲染，更适合全局组件，但会破坏 PDF 内的跨页链接与 TOC）。

导出由 Playwright 驱动。从 export.ts 的 importPlaywright 可以确认解析顺序：用户项目根目录 → 工作区根目录 → 全局 registry → @slidev/cli 自身依赖；都找不到时报错提示通过 npm i -D playwright-chromium 安装。此外 CLI 还支持 slidev export-notes [entry] 命令单独导出演讲者备注 PDF（参数包括 --output、--timeout、--wait），默认输出名为 [入口名]-export-notes。

slidev format [entry]：格式化 Markdown 文件

格式化幻灯片 Markdown 文件。注意：它不会格式化幻灯片的内容正文，只整理 Markdown 文件的组织结构。

实现上非常直接（见 cli.ts）：读取入口文件 → parser.parse → parser.prettify(md) → parser.save(md) 写回，解析器来自 @slidev/parser 包（packages/parser/src/core.ts）。命令同样接受 entry..，可以对多个入口文件依次格式化。

slidev mcp [entry]：启动 MCP 服务器

启动一个基于 stdio 的 MCP（Model Context Protocol）服务器，供 AI Agent 检查与编辑幻灯片，详细说明见 MCP 特性文档。

从实现可以看到其工作方式：

• packages/slidev/node/mcp/stdio.ts 中 startMcpStdioServer 通过 StdioServerTransport 连接 MCP 服务器，并直接操作 Markdown 文件（不需要开发服务器），每次工具调用都会重新从磁盘读取最新数据，容忍外部编辑；
• 工具集定义在 packages/slidev/node/mcp/server.ts，包括 slidev-get-info（概览：入口、标题、页数、Markdown 文件列表）、slidev-list-slides、slidev-get-slide（单页完整源码：frontmatter/内容/备注）、slidev-update-slide（部分字段更新，frontmatter 中传 null 删除某个键）、slidev-insert-slide、slidev-remove-slide、slidev-move-slide；
• 当有运行中的开发服务器时（dev 服务器在 http://localhost:<port>/__mcp 暴露同一套工具，见 cli.ts 中的 URL 打印逻辑），还会额外注册 slidev-goto-slide，可把所有已连接的浏览器实时导航到指定页码，便于 Agent 编辑后可视化验证。

相关的端到端测试见 test/mcp.test.ts。

slidev theme [subcommand]：主题操作

主题相关的操作目前包含一个子命令：

• slidev theme eject [entry]：把当前主题"弹出"到本地文件系统，详细说明见 eject 主题文档。
  • [entry]（字符串，默认 slides.md）：幻灯片 Markdown 入口。
  • --dir（字符串，默认 theme）：输出目录。
  • --theme, -t（字符串）：覆盖主题。

从 cli.ts 的实现可以确认 eject 的完整流程：

1. 解析入口，加载 headmatter，确定主题名（-t > frontmatter 的 theme > 默认 default；theme: null 视为 none 并报错退出，因为无主题可 eject）；
2. 若主题名以 / 或 . 开头、或含路径分隔符，说明已经是本地目录（已 eject 过），直接报错退出；
3. 通过 resolveTheme 定位主题包根目录，用 fs.cp 递归复制到 --dir 目录，过滤掉 node_modules 与 .git；
4. 最后把入口文件第一页的 frontmatter 中 theme 改写为 ./theme（即本地目录），并保存文件。

由此可以推断：eject 之后主题的布局、样式等全部变成项目本地文件，后续修改直接生效，也意味着该主题不再自动跟随上游主题包的更新。

小结与参数速查

命令	用途	核心参数
slidev [entry]	开发服务器	--port / --remote [password] / --open / --base / --log / --force / --theme
slidev build [entry]	构建可托管 SPA	--out / --download / --without-notes / --base / --theme
slidev export [...entry]	导出 PDF/PNG/PPTX/MD	--format / --output / --range / --dark / --with-clicks / --omit-background
slidev format [entry]	整理 Markdown 组织结构	—
slidev mcp [entry]	stdio MCP 服务器	—
slidev theme eject [entry]	主题落到本地	--dir / --theme

所有命令的公共入口参数 [entry] 默认 slides.md，公共选项 --theme, -t 可覆盖 frontmatter 中的主题设置。本文所有实现细节均以当前仓库源码为准，主要参考文件：packages/slidev/node/cli.ts、packages/slidev/node/commands/export.ts、packages/slidev/node/commands/build.ts、packages/slidev/node/commands/serve.ts、packages/slidev/node/mcp/server.ts。