【Vue】静态站点生成（VitePress）

个人主页：Guiat
归属专栏：Vue

正文

1. VitePress 基础概念

1.1 什么是 VitePress

VitePress 是一个基于 Vite 构建的静态站点生成器(SSG)，专为技术文档而设计，由 Vue.js 团队开发。它使用 Markdown 编写内容，通过 Vue 组件增强功能，并利用 Vite 的快速开发体验。

1.2 与传统文档工具对比

特性	VitePress	VuePress	Docusaurus	GitBook
构建工具	Vite	Webpack	Webpack	自定义
启动速度	极快	中等	中等	慢
热更新	极快	中等	中等	慢
主题定制	Vue组件	Vue组件	React组件	有限
学习曲线	低	中等	中等	低

2. VitePress 项目创建与配置

2.1 项目初始化流程

2.2 安装与项目创建

# 创建并进入项目目录
mkdir my-docs && cd my-docs# 初始化项目
npm init -y# 安装 VitePress
npm install -D vitepress# 创建第一个文档
mkdir docs && echo '# Hello VitePress' > docs/index.md# 添加脚本到 package.json

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

2.3 基本配置文件结构

docs/
├── .vitepress/
│   └── config.js     # 配置文件
├── public/           # 静态资源
│   └── logo.png
├── index.md          # 首页
└── guide/└── getting-started.md  # 指南页面

// docs/.vitepress/config.js
export default {// 站点级配置title: '我的文档',description: '使用VitePress构建的文档站点',// 主题配置themeConfig: {logo: '/logo.png',// 导航栏nav: [{ text: '首页', link: '/' },{ text: '指南', link: '/guide/getting-started' },{ text: 'API', link: '/api/' }],// 侧边栏sidebar: {'/guide/': [{text: '指南',items: [{ text: '快速开始', link: '/guide/getting-started' },{ text: '配置', link: '/guide/configuration' }]}]},// 社交链接socialLinks: [{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }]}
}

3. 内容创作与组织

3.1 Markdown 增强功能

代码示例:

# 标题## 代码高亮```js
function hello() {console.log('Hello VitePress!')
}
```# 自定义容器::: info
这是一个信息容器
:::::: warning
这是一个警告容器
:::::: danger
这是一个危险容器
:::::: details 点击查看更多
这里是详细内容
:::# 使用Vue组件<script setup>
import { ref } from 'vue'const count = ref(0)
</script><button @click="count++">点击了 {{ count }} 次</button>

3.2 文档结构组织

flowchart TDA[文档根目录] --> B1[首页 index.md]A --> B2[指南目录 guide/]A --> B3[API目录 api/]A --> B4[示例目录 examples/]B2 --> C1[getting-started.md]B2 --> C2[configuration.md]B2 --> C3[deployment.md]B3 --> D1[overview.md]B3 --> D2[references.md]B4 --> E1[basic.md]B4 --> E2[advanced.md]

3.3 Frontmatter 配置

---
title: 快速开始
description: VitePress快速入门指南
sidebar: auto
head:- - meta- name: keywordscontent: vitepress, vue, 文档
layout: doc
---# 快速开始这里是页面内容...

4. 主题定制与开发

4.1 主题定制流程

4.2 CSS 变量覆盖

/* docs/.vitepress/theme/custom.css */
:root {--vp-c-brand: #646cff;--vp-c-brand-light: #747bff;--vp-c-brand-dark: #535bf2;--vp-font-family-base: 'Roboto', 'Helvetica Neue', sans-serif;--vp-font-family-mono: 'Fira Code', monospace;
}/* 深色模式变量 */
.dark {--vp-c-bg: #1e1e20;--vp-c-bg-soft: #2c2c30;
}

4.3 扩展默认主题

// docs/.vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
import './custom.css'export default {...DefaultTheme,// 覆盖布局组件Layout: MyLayout,// 注册自定义组件enhanceApp({ app }) {app.component('MyComponent', MyComponent)}
}

<!-- docs/.vitepress/theme/MyLayout.vue -->
<script setup>
import DefaultTheme from 'vitepress/theme'
import CustomFooter from './CustomFooter.vue'const { Layout } = DefaultTheme
</script><template><Layout><!-- 默认插槽内容将传递给默认主题的Layout --><template #footer><CustomFooter /></template></Layout>
</template>

4.4 自定义主题开发

<!-- docs/.vitepress/theme/Layout.vue -->
<script setup>
import { useData } from 'vitepress'
import NavBar from './components/NavBar.vue'
import SideBar from './components/SideBar.vue'
import Page from './components/Page.vue'const { frontmatter } = useData()
</script><template><div class="theme-container"><NavBar /><div class="content-container"><SideBar v-if="frontmatter.sidebar !== false" /><main class="main-content"><Page /></main></div></div>
</template><style>
/* 主题样式 */
</style>

5. 高级功能与集成

5.1 搜索功能实现

// 本地搜索配置
export default {themeConfig: {search: {provider: 'local'}}
}// Algolia搜索配置
export default {themeConfig: {search: {provider: 'algolia',options: {appId: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',indexName: 'YOUR_INDEX_NAME'}}}
}

5.2 国际化支持

docs/
├── .vitepress/
│   └── config.js
├── en/
│   ├── index.md
│   └── guide/
│       └── getting-started.md
└── zh/├── index.md└── guide/└── getting-started.md

// 国际化配置
export default {locales: {root: {label: 'English',lang: 'en'},zh: {label: '简体中文',lang: 'zh-CN',link: '/zh/',themeConfig: {nav: [{ text: '首页', link: '/zh/' },{ text: '指南', link: '/zh/guide/getting-started' }],sidebar: {'/zh/guide/': [{text: '指南',items: [{ text: '快速开始', link: '/zh/guide/getting-started' }]}]}}}}
}

5.3 PWA 支持

# 安装PWA插件
npm install -D @vite-pwa/vitepress

// 配置PWA
import { defineConfig } from 'vitepress'
import { withPwa } from '@vite-pwa/vitepress'export default withPwa(defineConfig({// VitePress配置pwa: {registerType: 'autoUpdate',includeAssets: ['favicon.svg', 'robots.txt', 'safari-pinned-tab.svg'],manifest: {name: '我的文档',short_name: '文档',theme_color: '#ffffff',icons: [{src: 'pwa-192x192.png',sizes: '192x192',type: 'image/png'},{src: 'pwa-512x512.png',sizes: '512x512',type: 'image/png'}]}}
}))

6. 部署与优化

6.1 部署流程

6.2 GitHub Pages 部署

# .github/workflows/deploy.yml
name: Deploy VitePress site to Pageson:push:branches: [main]jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Setup Nodeuses: actions/setup-node@v3with:node-version: 18cache: npm- name: Install dependenciesrun: npm ci- name: Buildrun: npm run docs:build- name: Deployuses: peaceiris/actions-gh-pages@v3with:github_token: ${{ secrets.GITHUB_TOKEN }}publish_dir: docs/.vitepress/dist

6.3 性能优化策略

// vite.config.js 优化配置
import { defineConfig } from 'vite'export default defineConfig({build: {// 启用 gzip 压缩brotliSize: true,// 代码分割策略rollupOptions: {output: {manualChunks: {vue: ['vue'],vitepress: ['vitepress']}}},// 小于此阈值的资源将被内联为base64assetsInlineLimit: 4096,// 启用CSS代码分割cssCodeSplit: true}
})

7. 实际应用案例

7.1 API文档生成流程

/*** 计算两个数字的和* @param {number} a - 第一个数字* @param {number} b - 第二个数字* @returns {number} 两个数字的和* @example* ```js* add(1, 2) // 返回 3* ```*/
export function add(a, b) {return a + b
}

7.2 组件库文档示例

<!-- docs/components/button.md -->
---
title: Button 按钮
---# Button 按钮常用的操作按钮。## 基础用法基础的按钮用法。<preview><my-button>默认按钮</my-button><my-button type="primary">主要按钮</my-button><my-button type="success">成功按钮</my-button><my-button type="warning">警告按钮</my-button><my-button type="danger">危险按钮</my-button>
</preview>```vue
<my-button>默认按钮</my-button>
<my-button type="primary">主要按钮</my-button>
<my-button type="success">成功按钮</my-button>
<my-button type="warning">警告按钮</my-button>
<my-button type="danger">危险按钮</my-button>

8. 常见问题与解决方案

8.1 内容组织问题

8.2 自定义组件集成

<!-- docs/.vitepress/theme/components/CodeDemo.vue -->
<script setup>
import { ref, onMounted } from 'vue'const props = defineProps({code: String,title: String
})const showCode = ref(false)
const toggleCode = () => {showCode.value = !showCode.value
}
</script><template><div class="code-demo"><div class="demo-header"><h3 v-if="title">{{ title }}</h3><button @click="toggleCode">{{ showCode ? '隐藏代码' : '查看代码' }}</button></div><div class="demo-content"><slot></slot></div><div v-if="showCode" class="demo-code"><pre><code>{{ code }}</code></pre></div></div>
</template><style>
.code-demo {border: 1px solid #ddd;border-radius: 8px;margin: 16px 0;overflow: hidden;
}.demo-header {display: flex;justify-content: space-between;align-items: center;padding: 8px 16px;background-color: #f5f5f5;
}.demo-content {padding: 16px;
}.demo-code {border-top: 1px solid #ddd;padding: 16px;background-color: #f8f8f8;
}
</style>

8.3 SEO 优化策略

// docs/.vitepress/config.js
export default {// 站点级SEOtitle: '我的文档站点',description: '全面的技术文档和教程',head: [['meta', { name: 'keywords', content: 'vitepress, vue, documentation' }],['meta', { name: 'author', content: '作者名称' }],['meta', { property: 'og:title', content: '我的文档站点' }],['meta', { property: 'og:description', content: '全面的技术文档和教程' }],['meta', { property: 'og:image', content: 'https://example.com/og-image.jpg' }],['link', { rel: 'canonical', href: 'https://example.com' }]],// 生成sitemapsitemap: {hostname: 'https://example.com'}
}

结语
感谢您的阅读！期待您的一键三连！欢迎指正！