CLI 命令

VitePress 提供了一组命令行工具，用于开发、构建和预览站点。

安装

npm install -D vitepress

命令概览

命令	说明
vitepress dev	启动开发服务器
vitepress build	构建生产版本
vitepress preview	预览构建结果

vitepress dev

启动开发服务器，支持热更新。

基础用法

vitepress dev [root]

参数

参数	说明
root	文档根目录，默认当前目录

选项

选项	类型	默认值	说明
--port	number	5173	开发服务器端口
--open	boolean	false	自动打开浏览器
--host	string | boolean	false	指定主机地址
--base	string	/	公共基础路径
--cors	boolean	false	启用 CORS
--strictPort	boolean	false	端口被占用时报错

示例

# 启动开发服务器
vitepress dev docs

# 指定端口
vitepress dev docs --port 3000

# 自动打开浏览器
vitepress dev docs --open

# 监听所有网络接口
vitepress dev docs --host

# 指定主机
vitepress dev docs --host 0.0.0.0

# 组合选项
vitepress dev docs --port 3000 --open --host

开发服务器特性

• 热模块替换 (HMR) - 文件更改即时反映
• TypeScript 支持 - 开箱即用的 TS 支持
• Vue 组件热重载 - Vue 组件热更新
• Markdown 即 Vue - .md 文件作为 Vue 组件处理

vitepress build

构建站点的生产版本。

基础用法

vitepress build [root]

参数

参数	说明
root	文档根目录，默认当前目录

选项

选项	类型	默认值	说明
--outDir	string	.vitepress/dist	输出目录
--base	string	/	公共基础路径
--clean	boolean	false	构建前清理输出目录
--mode	string	production	构建模式
--debug	boolean	false	启用调试模式
--minify	boolean	true	是否压缩

示例

# 构建项目
vitepress build docs

# 指定输出目录
vitepress build docs --outDir public

# 指定基础路径
vitepress build docs --base /docs/

# 调试模式
vitepress build docs --debug

构建输出

docs/.vitepress/dist/
├── index.html
├── assets/
│   ├── index.[hash].js
│   ├── index.[hash].css
│   └── ...
├── guide/
│   └── index.html
└── ...

vitepress preview

启动本地服务器预览构建结果。

基础用法

vitepress preview [root]

参数

参数	说明
root	文档根目录，默认当前目录

选项

选项	类型	默认值	说明
--port	number	4173	预览服务器端口
--host	string | boolean	false	指定主机地址
--open	boolean	false	自动打开浏览器
--outDir	string	.vitepress/dist	预览目录

示例

# 预览构建结果
vitepress preview docs

# 指定端口
vitepress preview docs --port 8080

# 自动打开浏览器
vitepress preview docs --open

package.json 配置

推荐在 package.json 中配置脚本：

{
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "devDependencies": {
    "vitepress": "^1.0.0"
  }
}

常用脚本配置

{
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs",
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    "docs:serve": "vitepress preview docs --port 8080 --host"
  }
}

npx 用法

无需安装即可使用：

# 创建新项目
npx vitepress init

# 开发
npx vitepress dev docs

# 构建
npx vitepress build docs

# 预览
npx vitepress preview docs

环境变量

VitePress 支持通过环境变量配置：

.env 文件

# .env
VITEPRESS_BASE=/docs/

在配置中使用

// .vitepress/config.mts
export default defineConfig({
  base: process.env.VITEPRESS_BASE || '/'
})

Node.js API

也可以通过编程方式调用：

import { build, createServer, serve } from 'vitepress'

// 开发
const server = await createServer('docs')
await server.listen()

// 构建
await build('docs')

// 预览
await serve('docs')

常见问题

端口被占用

# 指定其他端口
vitepress dev docs --port 3000

# 或强制使用指定端口
vitepress dev docs --port 3000 --strictPort

内存不足

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" vitepress build docs

网络访问

# 允许局域网访问
vitepress dev docs --host

参考链接

• 站点配置 - 完整配置选项
• 构建 API - 编程式 API
• VitePress 官方 CLI 文档