VitePress 使用详解 -静态页面生成器
一、核心概念
VitePress 是 Vue.js 团队开发的下一代静态网站生成器，基于 Vite 构建，专为技术文档优化，具备以下特性：
- Vite 驱动：继承 Vite 的极速开发体验，如即时服务器启动和闪电般的热更新
- Markdown 优先：原生支持 Markdown 语法扩展，如自定义容器、代码块高亮
- Vue 集成：可在 Markdown 中直接使用 Vue 组件（包括单文件组件 SFC）
- 性能卓越：静态 HTML 预渲染 + SPA 导航的混合架构，首屏加载速度极快
二、快速上手流程
1. 环境准备
- Node.js：要求 ≥ v20.19（推荐 LTS 版本）
- 包管理器：npm（v9.0+）、yarn 或 pnpm
# 验证安装
node -v
npm -v
2. 项目初始化
npm create vite@latest my-vitepress-project -- --template vanilla
cd my-vitepress-project
npm install
3. 安装 VitePress
npm install -D vitepress
4. 项目结构
.
├── docs
│ ├── .vitepress
│ │ └── config.js # 配置文件
│ ├── README.md # 首页
│ └── guide
│ └── advanced.md # 其他页面
└── package.json
三、核心配置详解
1. 基础配置 (docs/.vitepress/config.js)
import { defineConfig } from 'vitepress'export default defineConfig({lang: 'zh-CN',title: '我的知识库',description: 'VitePress 使用指南',themeConfig: {logo: '/images/logo.png',nav: [{ text: '首页', link: '/' },{ text: '指南', link: '/guide/' }],sidebar: {'/guide/': [{ text: '快速入门', link: '/guide/' },{ text: '进阶配置', link: '/guide/advanced' }]}}
})
2. 首页配置 (docs/README.md)
---
home: true
heroText: VitePress 知识库
tagline: 让文档管理更简单
actions:- text: 快速上手 →link: /guide/
features:- title: 简洁至上details: 基于 Markdown 的极简写作体验- title: Vite 驱动details: 享受极速开发体验- title: 高性能details: 预渲染静态 HTML + SPA 加载
---
四、核心功能实践
1. Markdown 扩展语法
# 代码块高亮
```js
console.log('Hello VitePress!')
自定义容器
::: tip
这是提示信息
:::
Vue 组件集成
```2. 自动生成侧边栏
在 config.js 中配置：
sidebar: 'auto' // 根据文档结构自动生成
3. 搜索功能配置
themeConfig: {search: {provider: 'local', // 或 'algolia'options: {// 本地搜索配置}}
}
五、高级功能
1. 自定义主题
- 创建主题文件夹：
mkdir docs/.vitepress/theme
- 创建布局组件 (
docs/.vitepress/theme/Layout.vue)：
<template><div><NavBar /><SideBar /><Content /><Footer /></div>
</template>
- 在
config.js中启用：
export default defineConfig({theme: require.resolve('./theme')
})
2. 插件系统
安装官方插件示例：
npm install vitepress-demo-plugin
配置使用：
import { demoPlugin } from 'vitepress-demo-plugin'export default defineConfig({plugins: [demoPlugin({// 插件配置})]
})
推荐插件：
- 代码演示：
vitepress-demo-plugin - 动态标题：
vitepress-plugin-dynamic-title - 看板娘：
@vitepress-reco/vuepress-plugin-kan-ban-niang
六、部署指南
1. GitHub Pages 部署
- 在
config.js中设置基础路径：
export default defineConfig({base: '/repository-name/',
})
- 创建
.github/workflows/deploy.yml：
name: Deploy
on:push:branches:- main
jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- run: npm install- run: npm run docs:build- name: Deploy to GitHub Pagesuses: peaceiris/actions-gh-pages@v3with:github_token: ${{ secrets.GITHUB_TOKEN }}publish_dir: ./docs/.vitepress/dist
2. 本地构建命令
# 本地开发
npx vitepress dev docs# 生产构建
npx vitepress build docs
七、常见问题解决
Q1: 图片资源加载失败
将图片放在 docs/.vitepress/public/ 目录，使用绝对路径引用：
Q2: 样式覆盖技巧
创建 docs/.vitepress/theme/styles/vars.css：
:root {--vp-c-brand: #ff6464;
}
Q3: 代码块高亮配置
在 config.js 中添加：
markdown: {lineNumbers: true
}
八、学习资源推荐
- VitePress 官方文档
- Vite 官方文档
- Markdown 官方教程
通过本文档，您已经掌握了 VitePress 的完整使用流程。立即开始您的技术文档创作之旅吧！
Hugo 详解-静态网站生成器的全面指南
