VitePress 完整指南

VitePress 是一个静态站点生成器，专为构建快速、以内容为中心的网站而设计。它基于 Vite 和 Vue，提供了出色的开发体验和性能。

什么是 VitePress？

VitePress 是 VuePress 的精神继承者，由 Vue.js 团队开发。它利用 Vite 的快速构建能力和 Vue 3 的现代特性，为技术文档和静态网站提供了理想的解决方案。

核心特性

• ⚡ 极快的开发体验 - 基于 Vite 的即时热重载
• 🎨 Vue 驱动 - 使用 Vue 3 组件和 Composition API
• 📝 Markdown 增强 - 支持 Vue 组件和自定义容器
• 🔍 内置搜索 - 客户端搜索，无需服务器
• 🌍 国际化 - 内置多语言支持
• 📱 响应式设计 - 移动端友好的默认主题

安装和设置

前置要求

• Node.js 18+
• 包管理器：npm、yarn 或 pnpm

创建新项目

# 使用 npm
npm create vitepress@latest my-docs

# 使用 yarn
yarn create vitepress my-docs

# 使用 pnpm
pnpm create vitepress my-docs

项目结构

my-docs/
├── docs/
│   ├── .vitepress/
│   │   ├── config.ts        # 配置文件
│   │   └── theme/           # 自定义主题
│   ├── index.md             # 首页
│   └── guide/               # 文档目录
└── package.json

配置详解

基础配置

在 .vitepress/config.ts 中配置站点：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的文档站点',
  description: '基于 VitePress 构建的文档',
  
  // 主题配置
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
})

多语言配置

export default defineConfig({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN',
      title: '我的文档',
      description: '中文描述'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      title: 'My Docs',
      description: 'English description',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' }
        ]
      }
    }
  }
})

Markdown 增强功能

自定义容器

::: info 信息
这是一个信息提示框
:::

::: tip 提示
这是一个提示框
:::

::: warning 警告
这是一个警告框
:::

::: danger 危险
这是一个危险警告框
:::

代码组

::: code-group

```js [config.js]
export default {
  name: 'config'
}

export default {
  name: 'config'
} as const

:::

### 在 Markdown 中使用 Vue

```markdown
<!-- 我的页面 -->

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

当前计数：{{ count }}

<button @click="count++">增加</button>

自定义主题

扩展默认主题

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // 注册全局组件
  }
}

自定义样式

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
}

.VPHero .name {
  background: linear-gradient(120deg, #bd34fe 30%, #41d1ff);
  background-clip: text;
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

部署

构建

npm run build

部署到 GitHub Pages

# File: .github/workflows/deploy.yml
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build
      - uses: actions/deploy-pages@v2
        with:
          path: docs/.vitepress/dist

最佳实践

文档结构组织

docs/
├── guide/           # 指南
├── api/            # API 文档
├── examples/       # 示例
├── faq/           # 常见问题
└── changelog/     # 更新日志

SEO 优化

export default defineConfig({
  head: [
    ['meta', { name: 'keywords', content: 'vitepress, vue, documentation' }],
    ['meta', { property: 'og:title', content: '我的文档站点' }],
    ['meta', { property: 'og:description', content: '站点描述' }]
  ]
})

性能优化

• 使用图片懒加载
• 合理拆分文档页面
• 启用 gzip 压缩
• 使用 CDN 加速

常见问题

如何添加自定义组件？

在 .vitepress/theme/index.ts 中注册全局组件：

import MyComponent from './components/MyComponent.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

如何自定义 404 页面？

创建 .vitepress/theme/NotFound.vue 文件：

<template>
  <div class="not-found">
    <h1>页面未找到</h1>
    <p>抱歉，您访问的页面不存在。</p>
  </div>
</template>

如何添加评论系统？

可以集成 Giscus、Gitalk 等评论系统：

<template>
  <div class="giscus"></div>
</template>

<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  // 初始化 Giscus
})
</script>

总结

VitePress 是构建现代文档站点的优秀选择，它结合了 Vite 的快速构建和 Vue 的强大功能。通过合理的配置和优化，您可以创建出既美观又高性能的文档网站。

---

更多详细信息请参考 VitePress 官方文档。