一、核心概念

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 的完整使用流程。立即開始您的技術文檔創作之旅吧！

---