VitePress 命令行接口（CLI）完整参考：dev / build / preview / init 命令实战指南

• 前端
• 文档

本篇指南基于 VitePress 官方文档 命令行接口参考 展开，系统讲解vitepress dev、vitepress build、vitepress preview与vitepress init四个核心命令的用法、选项参数与底层实现原理。读完本文，你将掌握本地开发、生产构建、产物预览与项目初始化四条完整工作流，并能结合 src/node/cli.ts 的源码理解每个命令背后的解析与执行逻辑。

VitePress 的所有 CLI 命令都通过bin字段注册为vitepress可执行文件（见 package.json），默认以当前目录作为站点根目录。命令行入口 src/node/cli.ts 使用minimist解析参数，并将形如--force的布尔参数从字符串"true"/"false"归一化为真正的布尔值，再根据第一个位置参数分发到dev、init、build、serve/preview四个分支。

命令总览

其中vitepress与vitepress dev等价：在 src/node/cli.ts 中，当command为空或为dev时都会进入开发服务器启动分支。serve是preview的兼容别名，两者在 src/node/cli.ts 中走同一执行路径。

vitepress dev：启动开发服务器

使用指定目录作为根目录启动 VitePress 开发服务器，默认根目录为当前目录。

用法

# 从当前目录启动，`dev` 可省略 vitepress # 从子目录启动 vitepress dev [root] # 例如 vitepress dev docs

当省略dev直接运行vitepress时，第一个位置参数即被解释为根目录，源码中的对应逻辑为const root = argv._[command ? 1 : 0]（src/node/cli.ts）。

选项

源码实现与快捷键

--force选项在 CLI 入口被转换为optimizeDeps: { force: true }传入 Vite（src/node/cli.ts），用于清除依赖预构建缓存。开发服务器通过 createServer 创建，其内部将srcDir作为 Vite 根目录、把site.base作为 Vite base，并挂载由 createVitePressPlugin 生成的一组插件（rewrites、Vue 编译、web fonts、assetsBase、icons、local search、静态数据与动态路由等）。

vitepress dev启动后支持终端快捷键（由 shortcuts.ts 注册，仅在交互式 TTY 且非 CI 环境下生效）：

配置项（.vitepress/config）或相关依赖文件变更时，服务器会自动重启（见 plugin.ts 的hotUpdate处理）。

vitepress build：构建生产版本

执行生产环境构建，产出可直接部署的静态站点。

用法

vitepress build [root]

选项

构建流程

构建入口 build 的执行步骤为：

1. 设置NODE_ENV = production并解析站点配置；
2. 依次处理--base、--assetsBase、--mpa、--outDir等命令行覆盖项；
3. 并行构建客户端与服务端（SSR）bundle（building client + server bundles）；
4. 逐页渲染 HTML（rendering pages），并清理临时目录；
5. 若配置了sitemap.hostname，最后生成sitemap.xml（见 generateSitemap.ts）。

输出目录由 config.ts 解析：默认outDir为<root>/dist（即.vitepress/dist），静态资源子目录assetsDir默认assets，且assetsDir不允许超出outDir范围。

vitepress preview：本地预览生产版本

在本地启动一个静态服务器预览vitepress build的产物，用于上线前检查最终效果。

用法

vitepress preview [root]

preview与serve是同一命令的两种写法，二者在 src/node/cli.ts 中共同路由到 serve。

选项

实现要点

预览服务器基于polka + sirv实现（src/node/serve/serve.ts），关键行为包括：

• 默认端口为 4173（src/node/serve/serve.ts）；
• 读取outDir下的静态产物，对带指纹的静态资源设置immutable长缓存，对不带指纹的 HTML 等文件设置no-cache强制校验（src/node/serve/serve.ts）；
• 相对 base（isRelativeBase）统一在根路径提供服务，绝对 URL base 则取其 pathname（src/node/serve/serve.ts）；
• 未匹配路径回落到构建产物中的404.html（src/node/serve/serve.ts），可据此验证自定义 404 页面。

vitepress init：交互式安装向导

在当前目录启动交互式向导，快速初始化 VitePress 站点。

用法

vitepress init

向导步骤

向导基于@clack/prompts实现（init.ts），依次询问：

1. 配置初始化目录（默认./）；
2. Markdown 源文件目录（默认与根目录相同）；
3. 站点标题（默认My Awesome Project）；
4. 站点描述（默认A VitePress Site）；
5. 主题类型：
   • Default Theme：开箱即用的默认主题；
   • Default Theme + Customization：额外生成自定义 CSS 与布局插槽；
   • Custom Theme：生成完整自定义主题骨架（含Layout.vue）；
6. 是否使用 TypeScript 编写配置与主题文件；
7. 是否向package.json注入 npm scripts（dev/build/preview）；
8. 是否给脚本添加前缀（默认前缀docs，即生成docs:dev等）。

生成的脚手架文件因主题类型而异（init.ts）：默认主题生成index.md、api-examples.md、markdown-examples.md与.vitepress/config.js；选择自定义主题还会追加.vitepress/theme/index.js、style.css与Layout.vue。若package.json中缺少vue依赖且选择了自定义主题，向导会提示显式安装vue；如果检测到.git目录，还会提醒将.vitepress/dist与.vitepress/cache加入.gitignore（init.ts）。

向导结束后会打印下一步命令，例如npm run docs:dev（注入脚本时）或npx vitepress dev（未注入脚本时）。

常见组合工作流

将上述命令串联起来，便是一条完整的文档站点生命周期：

# 1. 初始化站点（仅首次） vitepress init # 2. 本地开发 vitepress dev docs # 或 npm run docs:dev # 3. 构建生产产物 vitepress build docs # 输出到 docs/.vitepress/dist # 4. 本地验证产物 vitepress preview docs --port 8080 # 5. 部署时指定 base 与输出目录 vitepress build docs --base /my-site/ --outDir ./public

如果构建或启动过程中出现错误，CLI 会通过logErrorAndExit打印错误信息并以非零状态码退出（src/node/cli.ts）；对于未知命令，同样会报错退出（src/node/cli.ts）。

相关文档与源码索引

• 命令官方参考：docs/zh/reference/cli.md（另有 英文版 及 es/fa/ja/ko/pt/ru/zh 多语言版本）
• CLI 入口与命令分发：src/node/cli.ts
• 开发服务器创建：src/node/server.ts
• 生产构建主流程：src/node/build/build.ts
• 预览服务器实现：src/node/serve/serve.ts
• 安装向导实现：src/node/init/init.ts
• 终端快捷键：src/node/shortcuts.ts
• MPA 模式指南：docs/zh/guide/mpa-mode.md
• 快速上手（含安装向导说明）：docs/zh/guide/getting-started.md

• 前端
• 文档