快速开始

前置要求

开始之前，确保你的电脑上装了：

• Node.js 20 或更高版本
• 一个终端（Windows 用 PowerShell 或 CMD，macOS/Linux 用终端）
• 一个编辑器（推荐 VS Code + Vue 扩展）

打开终端，输入以下命令检查 Node.js 是否装好：

node -v   # 应该输出 v20.x.x 或更高
npm -v    # 应该输出 10.x.x 或更高

安装 VitePress

进入你的项目文件夹，安装 VitePress：

npm

npm add -D vitepress

pnpm

pnpm add -D vitepress

yarn

yarn add -D vitepress

bun

bun add -D vitepress

注意

VitePress 是纯 ESM 包，不能用 require() 导入。确保 package.json 里有 "type": "module"，或者配置文件用 .mts / .mjs 后缀。

初始化项目

安装完成后运行初始化向导：

npm

npx vitepress init

pnpm

pnpm vitepress init

yarn

yarn vitepress init

bun

bun vitepress init

向导会问你几个问题：

1. 站点根目录 — 默认 ./，推荐 ./docs 或 ./src
2. 站点标题 — 就是浏览器标签页显示的名字
3. 站点描述 — SEO 用的描述文字
4. 主题颜色 — 选你喜欢的，后面可以改
5. 是否使用 TypeScript — 推荐选 Yes

完成后会生成以下文件：

.
├─ .vitepress/
│  └─ config.mts         ← 配置文件（所有设置在这里）
├─ index.md               ← 首页
├─ 运行时API示例.md        ← 示例页面
├─ Markdown扩展示例.md   ← 示例页面
└─ package.json

同时 package.json 里会多出三个脚本：

{
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
  }
}

理解文件结构

两个核心概念

VitePress 有两个重要的目录概念，搞懂了就不容易踩坑：

项目根目录（Project Root）：.vitepress 目录所在的地方。运行 vitepress dev docs 时，docs 就是根目录。

源目录（Source Directory）：Markdown 源文件所在的地方，默认和根目录相同。可以通过 srcDir 选项更改。

比如你把源文件放在 src/ 里：

export default defineConfig({
  srcDir: 'src',  // 源文件在 src/ 下
})

目录结构变成：

.
├─ .vitepress/           ← 配置目录
└─ src/                  ← 源目录
   ├─ index.md
   └─ ...

各目录/文件的作用

路径	作用
.vitepress/config.mts	核心配置文件，顶栏、侧边栏、主题等所有设置
.vitepress/theme/	自定义主题目录，改颜色、字体、布局
.vitepress/cache/	开发服务器缓存，可加到 .gitignore
.vitepress/dist/	构建输出目录，也要加到 .gitignore
源目录下的 .md 文件	网站的每个页面，自动按文件路径映射 URL
源目录下的 public/	静态资源，直接复制到网站根目录

配置文件结构

配置文件长这样：

export default defineConfig({
  // ═══ 站点级配置 ═══
  title: '站点名称',          // 浏览器标签页标题
  description: '站点描述',     // SEO 描述
  lang: 'zh-CN',              // 语言
  srcDir: 'src',              // 源文件目录

  // ═══ 主题配置 ═══
  themeConfig: {
    nav: [...],               // 顶栏导航
    sidebar: [...],           // 侧边栏
    // ...更多 UI 设置
  },

  // ═══ Markdown 配置 ═══
  markdown: {
    breaks: true,             // 允许单行换行
    math: true,               // 数学公式
    // ...更多 Markdown 设置
  }
})

记住这个三层结构：站点级 → themeConfig → markdown。后面所有配置都是在这三层里填。

启动开发服务器

npm run docs:dev

浏览器会自动打开 http://localhost:5173（如果端口被占用会自动换一个）。此时：

• 修改任何 .md 文件 → 页面秒级热更新，不用手动刷新
• 修改配置文件 → 自动重启服务器
• 按 h 可以显示帮助菜单

构建生产版本

npm run docs:build    # 构建 → .vitepress/dist/
npm run docs:preview  # 本地预览构建结果 → http://localhost:4173

preview 命令启动的是静态文件服务器，和最终上线效果完全一致。可以用来检查生产版本有没有问题。

下一步

• 了解 顶栏和侧边栏 怎么配
• 了解 主题配置 怎么改外观
• 了解 Markdown 功能 能干什么