VuePress：Vue 驱动的静态文档生成器

FreeGuideOnline 最新 2026-07-01

什么是 VuePress？

VuePress 是一个基于 Vue.js 的静态站点生成器，专为编写技术文档而设计。它以 Markdown 为中心，内置 Vue 组件支持，能让你在写作时轻松嵌入动态功能。生成的站点是纯静态文件，加载速度快，SEO 友好。VuePress 的默认主题优化了文档的阅读和导航体验，适合制作项目文档、知识库或个人博客。

环境准备

在开始之前，确保你的电脑已安装以下工具：

  • Node.js：推荐使用 v18 或更高版本。可通过 node -v 检查。
  • 包管理器：npm（随 Node.js 安装）或 yarn。

快速上手

1. 创建项目

使用命令行快速创建一个 VuePress 项目：

mkdir my-docs && cd my-docs
npm init -y
npm install -D vuepress@next

在项目根目录创建 docs 文件夹，并在其中新建 README.md：

mkdir docs
echo '# Hello VuePress' > docs/README.md

2. 添加启动脚本

编辑 package.json，在 scripts 中添加：

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

3. 启动开发服务器

运行以下命令，会在 http://localhost:8080 预览站点，支持热重载：

npm run docs:dev

项目结构

一个典型的 VuePress 项目结构如下：

my-docs
├── docs
│   ├── .vuepress         # 配置和自定义目录
│   │   ├── config.ts     # 站点配置文件
│   │   ├── public        # 静态资源目录
│   │   └── theme         # 自定义主题
│   ├── guide             # 指南文件夹
│   │   └── getting-started.md
│   └── README.md         # 首页
└── package.json

Markdown 文件会被自动转换为路由，例如 docs/guide/getting-started.md 对应 /guide/getting-started.html。

核心配置

站点基本信息

在 docs/.vuepress/config.ts 中配置站点标题、描述等：

import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '我的文档',
  description: '这是我的第一个 VuePress 站点',
})

导航栏

通过 theme 配置默认主题的导航栏：

import { defaultTheme } from 'vuepress'

export default defineUserConfig({
  // ...
  theme: defaultTheme({
    navbar: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      {
        text: '了解更多',
        children: [
          { text: 'GitHub', link: 'https://github.com' }
        ]
      }
    ],
  }),
})

侧边栏

侧边栏可自动生成或手动指定。推荐在指南页面使用自动侧边栏：

theme: defaultTheme({
  sidebar: {
    '/guide/': [
      {
        text: '指南',
        children: [
          '/guide/README.md',
          '/guide/getting-started.md',
          '/guide/configuration.md',
        ]
      }
    ],
  }
})

搜索功能

VuePress 内置基于页面的搜索，只需在配置中启用：

theme: defaultTheme({
  search: true,
  searchMaxSuggestions: 10,
})

写作技巧

Markdown 扩展

VuePress 扩展了 Markdown 语法，支持：

  • 代码块：语法高亮，可显示行号 ```ts{1,3-4}
  • 提示容器：使用 ::: 包裹来生成提示块
::: tip 提示
这是一个提示信息
:::
  • Emoji：直接输入 :tada: 呈现 🎉。
  • 自定义容器标题：::: info 自定义标题。

使用 Vue 组件

因为 VuePress 是 Vue 驱动的，你可以在 Markdown 中直接使用 Vue 语法：

当前计数：{{ count }}
<button @click="count++">点击 +1</button>

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

复杂的组件可以放在 .vuepress/components 目录下，然后在 Markdown 中直接使用。组件名会自动基于文件名转换。

部署静态站点

构建生产版本

运行构建命令，生成的文件在 docs/.vuepress/dist 中：

npm run docs:build

部署到 GitHub Pages

  1. 在项目根目录创建 .github/workflows/docs.yml，使用官方部署 Action：
name: docs

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npm run docs:build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vuepress/dist
  1. 在仓库设置中开启 GitHub Pages，选择 gh-pages 分支作为源。

提交代码后，站点将自动部署。

进阶特性

自定义主题

VuePress 支持完全自定义主题。你可以在 .vuepress/theme 中创建一个继承默认主题的主题，或从头设计。主题结构需包含 layouts、components 等目录。可参阅官方文档了解详情。

插件系统

VuePress 拥有丰富的插件生态。在 config.ts 中使用 plugins 选项添加：

import { searchPlugin } from '@vuepress/plugin-search'

export default defineUserConfig({
  plugins: [
    searchPlugin({ /* 配置 */ })
  ]
})

常用插件：@vuepress/plugin-back-to-top、@vuepress/plugin-nprogress、@vuepress/plugin-pwa。

多语言支持

通过 locales 配置实现国际化：

export default defineUserConfig({
  locales: {
    '/': { lang: 'zh-CN', title: '中文站点' },
    '/en/': { lang: 'en-US', title: 'English Site' },
  }
})

对应的文档目录也需按语言分开存放。

总结

VuePress 将 Vue 的灵活性和 Markdown 的简洁性相结合，是构建技术文档的理想选择。通过以上步骤，你已经可以搭建并发布一个专业、可定制的静态文档站点。建议进一步查阅 VuePress 官方文档 探索更多细节和最佳实践。