VuePress：基于 Vue.js 的静态站点生成器（SSG），主打 Markdown 写文档

一、VuePress是什么

VuePress：基于 Vue.js 的静态站点生成器（SSG），主打 Markdown 写文档，最初由尤雨溪创建，用来搭建 Vue 生态官方文档。
简单理解：
你写 .md 文档 → VuePress 编译 → 输出纯静态 HTML；页面首次加载是预渲染静态页面（利于 SEO），跳转时变成 SPA 单页应用。

官网：https://vuepress.vuejs.org/zh/

二、核心特性

1. Markdown 增强
   Markdown 文件里可以直接写 Vue 组件，轻松嵌入交互 Demo、表单、组件示例。
2. 开箱即用文档主题
   默认主题自带导航栏、侧边栏、目录、代码复制、搜索、上下页跳转，适合技术文档。
3. 插件与主题体系
   支持自定义主题；插件可实现：PWA、全文搜索、国际化、Git 贡献信息、代码演示等。
4. 预渲染 + SPA
   Build 阶段生成静态 HTML（搜索引擎友好）；浏览器内路由无刷新跳转。
5. 部署简单
   打包产出 dist 静态文件夹，可部署到：GitHub Pages、Vercel、Netlify、Nginx、OSS。

三、两大版本区分（重点！）

VuePress v1（Vue2，已停止维护）

• 底层：Vue2 + Webpack（固定）
• 配置：CommonJS
• 生态成熟，但不再更新新项目，新项目不推荐

VuePress v2（Vue3，当前社区维护版本）

• 底层：Vue3，支持 Vite / Webpack 两种打包器
• 原生 TS 支持，配置支持 .ts
• API 全部重构，v1 主题 / 插件无法直接兼容

⚠️ 容易混淆：VitePress ≠ VuePress v2

• VitePress：Vue 官方团队维护，极简、只绑定 Vite，追求极致速度
• VuePress v2：社区接手，同时支持 Vite+Webpack，扩展性更强、生态插件更多

四、快速上手（VuePress v2）

1. 初始化项目

# 脚手架一键创建
npx create-vuepress-site my-docs
cd my-docs
npm install

# 本地开发
npm run dev
# 打包静态文件（输出 dist）
npm run build

2. 最简手动目录结构

docs/
├── README.md                # 首页
├── guide/
│   └── intro.md             # 文档页面
└── .vuepress/
    ├── config.js            # 站点配置
    ├── public/              # 图片等静态资源
    └── components/          # 自定义Vue组件

3. docs/.vuepress/config.js 最小示例

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'

export default {
  title: 'VuePress 文档',
  description: '使用VuePress搭建知识库',
  bundler: viteBundler(),
  theme: defaultTheme({
    navbar: [
      { text: '指南', link: '/guide/intro' }
    ],
    sidebar: {
      '/guide/': ['intro']
    }
  })
}

五、适合 / 不适合场景

✅ 适合

• 开源项目技术文档、组件库文档
• 个人知识库、笔记网站、小型博客
• 需要在文档中嵌入 Vue 交互演示

❌ 不太适合

• 大型图文资讯博客（相比 Hexo、Nuxt 生态偏弱）
• 完全不懂 Vue、不想碰前端配置（优先选 MkDocs）

六、同类工具横向对比

七、常见社区热门拓展

• vuepress-theme-hope：功能极强的增强主题（博客、评论、目录、暗黑模式）
• 全文搜索插件、PWA 离线、Git 提交信息、代码块运行插件