一、核心概念

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. 自定义主题

1. 创建主题文件夹：

mkdir docs/.vuepress/theme

2. 创建布局组件 (docs/.vuepress/theme/Layout.vue)：

<template><div><NavBar /><SideBar /><Content /><Footer /></div>
</template>

3. 在 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 部署

1. 在 config.js 中设置基础路径：

base: '/repository-name/',

2. 创建 .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/ 目录，使用绝对路径引用：

![img](/image.png)

Q2: 样式覆盖技巧
创建 docs/.vuepress/styles/palette.scss：

$accentColor: #ff6464;

Q3: 代码块高亮配置
在 config.js 中添加：

markdown: {extendMarkdown: md => {md.use(require('markdown-it-prism'))}
}

八、学习资源推荐

1. VuePress 官方文档
2. Vue.js 中文文档
3. Markdown 官方教程

通过本文档，您已经掌握了 VuePress 的完整使用流程。立即开始您的技术文档创作之旅吧！

---