MEMZGBL的博客

1489 字

4 分钟

VitePress 教程：用 Vite 构建极速文档站点

2026-03-22

软件教程

vitepress

/

vue

/

vite

/

文档生成

/

ubuntu

/

前端开发

VitePress 完全指南：用 Vite 构建极速文档站点#

在开发文档、技术博客或项目官网时，我们往往需要一款轻量、快速且易于定制的静态站点生成器。Vue 生态中的 VitePress 应运而生，它基于 Vite 构建，继承了 Vue 3 的响应式能力，让文档写作与页面开发融为一体。

本文将带你从零开始，在 Ubuntu 上搭建一个完整的 VitePress 站点，涵盖初始化、配置、主题定制到部署的全流程，助你打造极致的文档体验。

1. 什么是 VitePress？#

VitePress 是 Vue 驱动的静态站点生成器，由 Vue 核心团队成员开发，专门用于构建文档类网站。它利用 Vite 的高速 HMR（热模块替换）和 Vue 3 的 Composition API，提供了极佳的开发体验和首屏加载性能。

核心优势：

极速开发：基于 Vite，启动毫秒级，HMR 即时生效
Vue 驱动：可在 Markdown 中直接使用 Vue 组件，扩展性极强
开箱即用：内置主题、搜索、导航栏、侧边栏等文档所需功能
静态生成：构建时输出纯静态文件，可部署在任何静态托管服务
SEO 友好：生成标准 HTML，支持自定义元信息

2. 环境准备#

在 Ubuntu 上使用 VitePress，需要先安装 Node.js（版本 >= 18）和 npm 或 pnpm。

2.1 安装 Node.js#

1
# 使用 NodeSource 仓库安装 Node.js 18.x
2
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
3
sudo apt install -y nodejs
4

5
# 验证安装
6
node -v   # v18.x
7
npm -v

2.2 安装 pnpm（可选，推荐）#

VitePress 官方推荐使用 pnpm 作为包管理器，速度更快且节省磁盘空间。

1
sudo npm install -g pnpm

3. 创建 VitePress 项目#

3.1 初始化项目#

创建一个新目录并进入：

1
mkdir my-docs
2
cd my-docs

使用 pnpm 初始化 VitePress：

1
pnpm add -D vitepress

或者使用 npm：

1
npm add -D vitepress

3.2 运行向导#

VitePress 提供了便捷的初始化向导：

1
pnpm vitepress init

根据提示选择：

标题：你的站点标题
描述：站点描述
是否启用 TypeScript：一般选 Yes
是否需要自动安装依赖：Yes

完成后，项目结构如下：

1
my-docs/
2
├── docs/
3
│   ├── .vitepress/
4
│   │   └── config.js      # 配置文件
5
│   ├── index.md           # 首页
6
│   └── guide.md           # 示例页面
7
├── package.json
8
└── node_modules/

3.3 启动开发服务器#

1
pnpm vitepress dev docs

默认访问 http://localhost:5173，即可看到默认主题的文档首页。

4. 目录结构详解#

1
docs/                     # 文档根目录
2
├── .vitepress/           # 配置目录
3
│   ├── config.js         # 站点全局配置
4
│   ├── theme/            # 自定义主题目录（可选）
5
│   └── dist/             # 构建输出目录（自动生成）
6
├── public/               # 静态资源（如图片、favicon）
7
├── index.md              # 首页
8
├── guide/
9
│   ├── index.md          # 指南首页
10
│   └── getting-started.md
11
└── ...

5. 基础配置#

配置文件位于 docs/.vitepress/config.js（或 .ts），导出默认配置对象。

5.1 站点元信息#

1
export default {
2
  title: '我的技术文档',
3
  description: '一个关于前端开发的文档站点',
4
  lang: 'zh-CN',
5
  head: [
6
    ['link', { rel: 'icon', href: '/favicon.ico' }]
7
  ]
8
}

5.2 主题配置#

主题配置控制导航栏、侧边栏、搜索等。

1
export default {
2
  themeConfig: {
3
    siteTitle: '我的文档',
4
    logo: '/logo.png',
5
    nav: [
6
      { text: '指南', link: '/guide/' },
7
      { text: 'API', link: '/api/' },
8
      { text: 'GitHub', link: 'https://github.com/your/repo' }
9
    ],
10
    sidebar: {
11
      '/guide/': [
12
        {
13
          text: '入门',
14
          items: [
15
            { text: '介绍', link: '/guide/' },
16
            { text: '快速开始', link: '/guide/getting-started' }
17
          ]
18
        },
19
        {
20
          text: '进阶',
21
          items: [
22
            { text: '自定义主题', link: '/guide/custom-theme' }
23
          ]
24
        }
25
      ]
26
    },
27
    socialLinks: [
28
      { icon: 'github', link: 'https://github.com/your/repo' }
29
    ],
30
    footer: {
31
      message: '基于 MIT 许可发布',
32
      copyright: 'Copyright © 2024-present'
33
    },
34
    search: {
35
      provider: 'local'   // 本地搜索
36
    }
37
  }
38
}

6. 编写内容#

6.1 Markdown 扩展#

VitePress 支持标准 Markdown，并扩展了以下特性：

YAML Frontmatter：在 Markdown 文件顶部定义页面元信息。
```
1
---
2
title: 指南
3
sidebar: false
4
---
```
代码高亮：自动支持大多数语言，也可通过 language 指定。
```
1
```js
2
console.log('hello')
3
```
```

自定义容器：用于提示、警告等信息。

1
::: tip
2
这是一个提示
3
:::
4

5
::: warning
6
小心操作
7
:::
8

9
::: danger
10
危险区域
11
:::

导入代码片段：通过 <<< @/file.js 引入外部文件。

6.2 使用 Vue 组件#

在 Markdown 中可以直接使用 Vue 组件，增强交互性。组件需放置在 docs/.vitepress/theme/components/ 目录下，并在主题入口中注册。

示例：创建一个简单的计数器组件 Counter.vue：

1
<script setup>
2
import { ref } from 'vue'
3
const count = ref(0)
4
</script>
5

6
<template>
7
  <button @click="count++">点击次数：{{ count }}</button>
8
</template>

在 Markdown 中引用：

1
# 组件示例
2

3
<Counter />

7. 主题定制#

7.1 覆盖默认样式#

在 docs/.vitepress/theme/ 下创建 custom.css，然后修改配置：

1
import DefaultTheme from 'vitepress/theme'
2
import './custom.css'
3

4
export default DefaultTheme

custom.css 示例：

1
:root {
2
  --vp-c-brand: #42b883;
3
  --vp-c-brand-light: #4cc78e;
4
}
5

6
.VPNavBar {
7
  border-bottom: 1px solid #eee;
8
}

7.2 自定义布局#

VitePress 允许通过插槽自定义页面布局。例如，创建一个包含首页特殊内容的布局：

在 docs/.vitepress/theme/components/Home.vue 中定义组件
在 index.md 中指定布局：

1
---
2
layout: home
3
---

7.3 扩展主题#

你可以完全自定义主题，但更常见的是在默认主题基础上扩展。例如，添加全局组件：

1
import DefaultTheme from 'vitepress/theme'
2
import MyComponent from './components/MyComponent.vue'
3

4
export default {
5
  extends: DefaultTheme,
6
  enhanceApp({ app }) {
7
    app.component('MyComponent', MyComponent)
8
  }
9
}

8. 部署#

8.1 构建静态文件#

1
pnpm vitepress build docs

构建产物位于 docs/.vitepress/dist。

8.2 部署到 GitHub Pages#

在项目根目录创建 .github/workflows/deploy.yml：

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [ main ]
6

7
jobs:
8
  build-deploy:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12
      - uses: actions/setup-node@v4
13
        with:
14
          node-version: 18
15
      - run: npm install -g pnpm
16
      - run: pnpm install
17
      - run: pnpm vitepress build docs
18
      - uses: peaceiris/actions-gh-pages@v3
19
        with:
20
          github_token: ${{ secrets.GITHUB_TOKEN }}
21
          publish_dir: docs/.vitepress/dist

推送代码到 GitHub，GitHub Actions 自动构建并部署到 gh-pages 分支。
在仓库设置中启用 GitHub Pages，选择 gh-pages 分支作为源。

8.3 部署到其他平台#

Vercel：导入项目，自动识别 VitePress，一键部署
Netlify：同样支持自动部署
云服务器：将 dist 目录上传到服务器，配置 Nginx 即可

9. 高级特性#

9.1 多语言支持#

在配置文件中启用 locales：

1
export default {
2
  locales: {
3
    root: {
4
      label: 'English',
5
      lang: 'en'
6
    },
7
    zh: {
8
      label: '中文',
9
      lang: 'zh-CN',
10
      link: '/zh/'
11
    }
12
  },
13
  themeConfig: {
14
    nav: {
15
      en: [{ text: 'Guide', link: '/guide/' }],
16
      zh: [{ text: '指南', link: '/zh/guide/' }]
17
    }
18
  }
19
}

9.2 本地搜索#

VitePress 内置了基于 minisearch 的本地搜索，只需在配置中开启：

1
export default {
2
  themeConfig: {
3
    search: {
4
      provider: 'local',
5
      options: {
6
        locales: {
7
          zh: {
8
            translations: {
9
              button: {
10
                buttonText: '搜索文档',
11
                buttonAriaLabel: '搜索'
12
              },
13
              modal: {
14
                noResultsText: '无法找到相关结果',
15
                resetButtonTitle: '清除查询条件',
16
                footer: {
17
                  selectText: '选择',
18
                  navigateText: '切换'
19
                }
20
              }
21
            }
22
          }
23
        }
24
      }
25
    }
26
  }
27
}

9.3 自定义 404 页面#

创建 docs/404.md，内容自定义，VitePress 会自动生成 404 页面。

9.4 部署时的基本路径#

如果站点部署在子路径（如 https://username.github.io/my-docs/），需要在配置中设置 base：

1
export default {
2
  base: '/my-docs/'
3
}

10. 常见问题#

问题	解决方法
图片无法显示	使用绝对路径（以 `/` 开头）指向 `public` 目录下的资源；或在 Markdown 中使用相对路径，但需注意构建时路径处理
自定义组件未生效	确保组件在 `enhanceApp` 中已注册，且组件文件路径正确
构建时报内存不足	增加 Node 内存限制：`NODE_OPTIONS="--max-old-space-size=4096" pnpm vitepress build docs`
本地搜索无法搜索中文	确认 `locales` 配置正确，且 `search.options.locales` 包含中文翻译
部署后样式丢失	检查 `base` 路径是否配置正确，若部署在子路径，需设置 `base`