VuePress 2.x 完全指南

本文将详细介绍VuePress 2.x的安装配置、主题定制、插件使用等完整使用指南。

🚀 什么是VuePress？

VuePress是一个基于Vue的静态网站生成器，特别适合构建技术文档和博客。VuePress 2.x版本带来了许多激动人心的新特性：

  • ⚡ 更快的构建速度 - 基于Vite的构建系统
  • 🎨 更好的开发体验 - 热重载和TypeScript支持
  • 🔧 更灵活的配置 - 改进的插件系统
  • 📱 更好的移动端支持 - 响应式设计优化

📦 安装与配置

环境要求

  • Node.js >= 16.0.0
  • PNPM (推荐) 或 NPM

创建项目

# 使用PNPM创建项目
pnpm create vuepress vuepress-starter
cd vuepress-starter

# 安装依赖
pnpm install

# 启动开发服务器
pnpm docs:dev

基本配置

创建 docs/.vuepress/config.js：

import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '我的VuePress站点',
  description: '这是一个VuePress站点',
  
  theme: defaultTheme({
    navbar: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
    ],
  }),
})

🎨 主题定制

自定义样式

创建 docs/.vuepress/styles/index.scss：

// 自定义CSS变量
:root {
  --c-brand: #42b883;
  --c-brand-light: #42b883;
  
  // 字体
  --font-family: 'Noto Sans SC', sans-serif;
}

// 自定义样式
.navbar {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

布局组件

创建自定义布局组件：

<!-- docs/.vuepress/components/MyLayout.vue -->
<template>
  <div class="my-layout">
    <Header />
    <main class="content">
      <slot />
    </main>
    <Footer />
  </div>
</template>

<script setup>
import Header from './Header.vue'
import Footer from './Footer.vue'
</script>

🔌 插件系统

常用插件配置

import { searchPlugin } from '@vuepress/plugin-search'
import { backToTopPlugin } from '@vuepress/plugin-back-to-top'
import { mediumZoomPlugin } from '@vuepress/plugin-medium-zoom'

export default defineUserConfig({
  plugins: [
    searchPlugin({
      locales: {
        '/': {
          placeholder: '搜索文档',
        },
      },
    }),
    backToTopPlugin(),
    mediumZoomPlugin(),
  ],
})

自定义插件

创建自定义插件：

// docs/.vuepress/plugins/my-plugin/index.js
import { path } from '@vuepress/utils'

export const myPlugin = (options) => ({
  name: 'vuepress-plugin-my-plugin',
  
  clientConfigFile: path.resolve(__dirname, './client.js'),
  
  onPrepared: async (app) => {
    // 构建时执行的逻辑
  },
})

📝 Markdown扩展

代码块

支持语法高亮和行号：

// 这是一个JavaScript示例
function hello(name) {
  console.log(`Hello, ${name}!`)
}

hello('VuePress')

自定义容器

::: tip 提示
这是一个提示信息
:::

::: warning 警告
这是一个警告信息
:::

::: danger 危险
这是一个危险信息
:::

数学公式

使用KaTeX渲染数学公式：

$$
\frac{\partial f}{\partial x} = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}
$$

🚀 部署配置

GitHub Pages

创建 .github/workflows/docs.yml：

name: docs

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
        
      - name: Build VuePress site
        run: pnpm docs:build
        
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          target_branch: gh-pages
          build_dir: docs/.vuepress/dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

🎯 最佳实践

项目结构

docs/
├── .vuepress/
│   ├── components/     # 自定义组件
│   ├── public/         # 静态资源
│   ├── styles/         # 样式文件
│   ├── config.js       # 主配置文件
│   └── client.js       # 客户端配置
├── blog/               # 博客文章
├── docs/               # 文档页面
└── README.md           # 首页

性能优化

  1. 图片优化

    • 使用WebP格式
    • 压缩图片大小
    • 懒加载实现

  2. 代码分割

    • 按路由分割代码
    • 异步加载组件
    • 优化打包体积

  3. 缓存策略

    • 合理设置缓存头
    • 使用Service Worker
    • CDN加速静态资源

🔧 常见问题

Q: 如何自定义主题颜色？

A: 通过修改CSS变量或使用主题提供的配置选项。

Q: 如何添加Google Analytics？

A: 使用@vuepress/plugin-google-analytics插件。

Q: 如何支持多语言？

A: 在config.js中配置locales选项。

Q: 如何优化SEO？

A: 使用@vuepress/plugin-seo插件，配置meta标签和结构化数据。

📚 相关资源

希望这份指南能帮助你快速上手VuePress 2.x！如果有任何问题，欢迎在评论区留言讨论。