VuePress 使用详解
一、核心概念
VuePress 是 Vue.js 团队开发的静态网站生成器，专为技术文档优化，具备以下特性：
- Markdown 优先：原生支持 Markdown 语法扩展
- Vue 驱动：可在 Markdown 中使用 Vue 组件
- 默认主题优化：内置响应式布局、搜索功能、自动生成侧边栏
- SEO 友好：自动生成服务端渲染（SSR）的静态内容
二、快速上手流程
1. 环境准备
- Node.js：要求 ≥ v18.0（推荐 LTS 版本）
- 包管理器：npm（v9.0+）或 yarn
# 验证安装
node -v
npm -v
2. 项目初始化
mkdir vuepress-demo && cd vuepress-demo
npm init -y
3. 安装 VuePress
npm install -D vuepress@next
4. 项目结构
.
├── docs
│ ├── .vuepress
│ │ └── config.js # 配置文件
│ ├── README.md # 首页
│ └── guide
│ └── advanced.md # 其他页面
└── package.json
三、核心配置详解
1. 基础配置 (docs/.vuepress/config.js)
import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'export default defineUserConfig({lang: 'zh-CN',title: '我的知识库',description: 'VuePress 使用指南',theme: defaultTheme({logo: '/images/logo.png',navbar: [{ text: '首页', link: '/' },{ text: '指南', link: '/guide/' }],sidebar: {'/guide/': [{ text: '快速入门', link: '/guide/' },{ text: '进阶配置', link: '/guide/advanced' }]}})
})
2. 首页配置 (docs/README.md)
---
home: true
heroText: VuePress 知识库
tagline: 让文档管理更简单
actions:- text: 快速上手 →link: /guide/
features:- title: 简洁至上details: 基于 Markdown 的极简写作体验- title: Vue 驱动details: 在 Markdown 中使用 Vue 组件- title: 高性能details: 预渲染静态 HTML + SPA 加载
---
四、核心功能实践
1. Markdown 扩展语法
# 代码块高亮
```js
console.log('Hello VuePress!')
自定义容器
::: tip
这是提示信息
:::
### 2. 自动生成侧边栏
在 `config.js` 中配置：
```javascript
sidebar: 'auto' // 根据文档结构自动生成
3. 搜索功能配置
themeConfig: {search: true,searchMaxSuggestions: 10
}
五、高级功能
1. 自定义主题
- 创建主题文件夹：
mkdir docs/.vuepress/theme
- 创建布局组件 (
docs/.vuepress/theme/Layout.vue)：
<template><div><NavBar /><SideBar /><Content /><Footer /></div>
</template>
- 在
config.js中启用：
theme: require.resolve('./theme')
2. 插件系统
安装官方插件示例：
npm install @vuepress/plugin-google-analytics@next
配置使用：
plugins: [['@vuepress/google-analytics', {id: 'G-XXXXXXX'}]
]
推荐插件：
- 代码复制：
vuepress-plugin-nuggets-style-copy - 动态标题：
vuepress-plugin-dynamic-title - 看板娘：
@vuepress-reco/vuepress-plugin-kan-ban-niang
六、部署指南
1. GitHub Pages 部署
- 在
config.js中设置基础路径：
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/.vuepress/dist
2. 本地构建命令
# 本地开发
npx vuepress dev docs# 生产构建
npx vuepress build docs
七、常见问题解决
Q1: 图片资源加载失败
将图片放在 docs/.vuepress/public/ 目录，使用绝对路径引用：
Q2: 样式覆盖技巧
创建 docs/.vuepress/styles/palette.scss：
$accentColor: #ff6464;
Q3: 代码块高亮配置
在 config.js 中添加：
markdown: {extendMarkdown: md => {md.use(require('markdown-it-prism'))}
}
八、学习资源推荐
- VuePress 官方文档
- Vue.js 中文文档
- Markdown 官方教程
通过本文档，您已经掌握了 VuePress 的完整使用流程。立即开始您的技术文档创作之旅吧！
