VitePress 学习指南

主题

插件市场 ​

发现并使用 VitePress 社区插件来扩展你的站点功能。

插件生命周期 ​

使用插件涉及以下阶段：发现 → 选型 → 安装 → 配置 → 更新 → 移除

mermaid
graph LR
    A[发现插件] --> B[评估选型]
    B --> C[安装]
    C --> D[配置集成]
    D --> E[版本更新]
    E --> F{兼容?}
    F -->|是| D
    F -->|否| G[排查/回退]
    G --> D
    D --> H[移除插件]

1. 发现插件 ​

渠道说明
npm 搜索搜索 vitepress-plugin 前缀
Awesome VitePress社区精选列表
VitePress 官方文档官方推荐插件
GitHub Topic搜索 topic:vitepress-plugin

2. 选型标准 ​

选择插件时，建议关注以下维度：

维度说明检查方式
维护状态最近 6 个月是否有更新GitHub Commits
兼容性是否支持当前 VitePress 版本peerDependencies
下载量周下载量反映使用规模npm 周下载
问题响应Issue 是否及时处理GitHub Issues
文档质量是否有完整文档和示例官方文档
安全性是否有已知漏洞npm audit
Bundle 体积是否引入过大依赖bundlephobia.com
bash
# 检查插件兼容性
npm view vitepress-plugin-mermaid peerDependencies

# 查看下载量
npm view vitepress-plugin-mermaid versions

# 安全检查
npm audit

# 检查包体积
npx bundlephobia vitepress-plugin-mermaid

3. 安装插件 ​

bash
# 安装插件
npm install vitepress-plugin-mermaid -D

# 安装特定版本
npm install vitepress-plugin-mermaid@1.0.0 -D

# 查看 peerDependencies 确保兼容
npm ls vitepress

4. 配置集成 ​

根据插件类型，配置方式不同：

ts
// docs/.vitepress/config.mts
import { withMermaid } from 'vitepress-plugin-mermaid'

// 方式一：包装函数（VitePress 专用插件）
export default withMermaid({
  // VitePress 配置
  mermaid: { /* 插件选项 */ }
})

// 方式二：Vite 插件
import { myVitePlugin } from 'vitepress-plugin-xxx'

export default defineConfig({
  vite: {
    plugins: [myVitePlugin()]
  }
})

// 方式三：Markdown 插件
import { myMarkdownPlugin } from 'markdown-it-xxx'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(myMarkdownPlugin)
    }
  }
})

5. 更新插件 ​

bash
# 检查过期插件
npm outdated

# 更新单个插件
npm update vitepress-plugin-mermaid

# 更新到最新大版本（谨慎）
npm install vitepress-plugin-mermaid@latest -D

# 更新后验证构建
npm run build

6. 移除插件 ​

bash
# 卸载插件
npm uninstall vitepress-plugin-mermaid

# 清理配置（手动）
# 1. 删除 config.mts 中的插件引用
# 2. 删除 theme/index.ts 中的插件注册
# 3. 删除相关 CSS 和组件
# 4. 运行 npm run build 验证

按功能分类 ​

内容增强 ​

插件说明安装周下载量
vitepress-plugin-mermaidMermaid 图表支持npm i vitepress-plugin-mermaid -D5K+
vitepress-plugin-tabs代码/内容标签页npm i vitepress-plugin-tabs -D3K+
vitepress-plugin-chartChart.js 图表npm i vitepress-plugin-chart chart.js -D1K+
markdown-it-katex数学公式（LaTeX）npm i markdown-it-katex -D10K+
markdown-it-footnote脚注支持npm i markdown-it-footnote -D5K+
markdown-it-task-lists任务列表npm i markdown-it-task-lists -D3K+

搜索增强 ​

插件说明安装周下载量
vitepress-plugin-search增强的本地搜索npm i vitepress-plugin-search -D2K+
vitepress-plugin-flexsearchFlexSearch 高性能搜索npm i vitepress-plugin-flexsearch -D1K+

SEO 优化 ​

功能说明方式
sitemap站点地图VitePress 内置
vitepress-plugin-rssRSS 订阅源npm i vitepress-plugin-rss -D
vitepress-plugin-robotsrobots.txt 生成npm i vitepress-plugin-robots -D
vitepress-plugin-canonicalCanonical URLnpm i vitepress-plugin-canonical -D

评论系统 ​

插件说明安装
vitepress-plugin-comment-with-giscusGiscus 评论npm i vitepress-plugin-comment-with-giscus -D
@waline/clientWaline 评论npm i @waline/client

开发工具 ​

插件说明安装
vitepress-plugin-demo代码演示组件npm i vitepress-plugin-demo -D
vitepress-plugin-copy-code代码复制增强npm i vitepress-plugin-copy-code -D
vitepress-plugin-imagemin图片压缩npm i vitepress-plugin-imagemin -D
vitepress-plugin-nprogress页面加载进度条npm i vitepress-plugin-nprogress -D

PWA 支持 ​

插件说明安装
@vite-pwa/vitepressPWA 离线访问npm i @vite-pwa/vitepress -D

热门插件配置示例 ​

Mermaid 图表 ​

支持在 Markdown 中绘制流程图、时序图、甘特图等。

ts
// .vitepress/config.mts
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid({
  // 你的 VitePress 配置
  themeConfig: {
    // ...
  },
  mermaid: {
    // Mermaid 配置
    theme: 'default',
    flowchart: { curve: 'basis' },
    sequence: { actorMargin: 50 }
  }
})

在 Markdown 中使用：

markdown
```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E

详细的 Mermaid 语法和图表类型，请参考 [Mermaid 图表教程](/basics/mermaid)。

::: tip VitePress v2
VitePress v2 原生支持 Mermaid：`markdown.mermaid: true`，无需安装插件。
:::

### FlexSearch 搜索

```ts
// .vitepress/config.mts
import { withFlexSearch } from 'vitepress-plugin-flexsearch'

export default withFlexSearch({
  themeConfig: {
    search: { provider: 'local' }
  },
  flexSearch: {
    encode: 'balance',
    tokenize: 'forward',
    resolution: 9,
    cache: 100
  }
})

完整的搜索方案对比，请参考 搜索服务。

代码复制增强 ​

为代码块添加复制按钮和复制成功提示：

ts
// .vitepress/config.mts
import { copyCodePlugin } from 'vitepress-plugin-copy-code'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(copyCodePlugin, {
        // 配置选项
        selector: '.vp-code-group .tab-item pre',
        duration: 2000
      })
    }
  }
})
ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { useCopyCode } from 'vitepress-plugin-copy-code/theme'

export default {
  extends: DefaultTheme,
  setup() {
    useCopyCode()
  }
}

NProgress 页面进度条 ​

ts
// .vitepress/config.mts
import { withNProgress } from 'vitepress-plugin-nprogress'

export default withNProgress({
  // VitePress 配置
})

// 自定义颜色
export default withNProgress({
  nprogress: {
    color: '#6366f1'
  }
})

PWA 支持 ​

ts
// .vitepress/config.mts
import { withPwa } from '@vite-pwa/vitepress'

export default withPwa({
  pwa: {
    registerType: 'autoUpdate',
    includeAssets: ['favicon.svg', 'logo.svg'],
    manifest: {
      name: 'My VitePress Site',
      short_name: 'MySite',
      theme_color: '#6366f1',
      icons: [
        { src: '/pwa-192x192.png', sizes: '192x192', type: 'image/png' },
        { src: '/pwa-512x512.png', sizes: '512x512', type: 'image/png' }
      ]
    },
    workbox: {
      cleanupOutdatedCaches: true,
      skipWaiting: true,
      clientsClaim: true
    }
  }
})

Vite 插件兼容 ​

VitePress 支持 Vite 生态插件：

ts
// .vitepress/config.mts
export default defineConfig({
  vite: {
    plugins: [
      // Vite 插件
    ]
  }
})

推荐 Vite 插件 ​

插件说明安装
vite-plugin-compressionGzip/Brotli 压缩npm i vite-plugin-compression -D
vite-plugin-pwaPWA 支持npm i vite-plugin-pwa -D
vite-plugin-imagemin图片压缩npm i vite-plugin-imagemin -D
vite-plugin-svg-iconsSVG 图标npm i vite-plugin-svg-icons -D
vite-plugin-inspect构建检查npm i vite-plugin-inspect -D

Vite 插件配置示例 ​

ts
// .vitepress/config.mts
import { compression } from 'vite-plugin-compression'

export default defineConfig({
  vite: {
    plugins: [
      // Gzip 压缩
      compression({
        algorithm: 'gzip',
        threshold: 10240 // 10KB 以上的文件才压缩
      }),
      // Brotli 压缩（压缩率更高）
      compression({
        algorithm: 'brotliCompress',
        threshold: 10240
      })
    ]
  }
})

Markdown 插件 ​

通过 markdown.config 添加 Markdown-it 插件：

ts
export default defineConfig({
  markdown: {
    config(md) {
      md.use(require('markdown-it-emoji'))
      md.use(require('markdown-it-sub'))
      md.use(require('markdown-it-sup'))
      md.use(require('markdown-it-footnote'))
      md.use(require('markdown-it-task-lists'))
    }
  }
})

常用 Markdown-it 插件 ​

插件说明安装
markdown-it-emojiEmoji 支持npm i markdown-it-emoji -D
markdown-it-mark高亮标记（==text==）npm i markdown-it-mark -D
markdown-it-sub下标（H~2~O）npm i markdown-it-sub -D
markdown-it-sup上标（X^2^）npm i markdown-it-sup -D
markdown-it-footnote脚注npm i markdown-it-footnote -D
markdown-it-task-lists任务列表npm i markdown-it-task-lists -D
markdown-it-plantumlPlantUML 图表npm i markdown-it-plantuml -D
markdown-it-attrs属性语法npm i markdown-it-attrs -D
markdown-it-container自定义容器VitePress 内置

数学公式支持 ​

ts
// .vitepress/config.mts
import katex from 'markdown-it-katex'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(katex)
    }
  },
  head: [
    ['link', { rel: 'stylesheet', href: 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css' }]
  ]
})

使用示例：

markdown
行内公式：$E = mc^2$

块级公式：
$$
\frac{\partial f}{\partial x} = \lim_{\Delta x \to 0} \frac{f(x + \Delta x) - f(x)}{\Delta x}
$$

VitePress v2

VitePress v2 原生支持数学公式：markdown.math: true，无需安装 markdown-it-katex。

开发自定义插件 ​

VitePress 支持三种类型的插件开发：

Vite 插件 ​

适用于构建时的代码转换和优化：

ts
// my-plugin.ts
import type { Plugin } from 'vite'

export function myVitePlugin(): Plugin {
  return {
    name: 'my-vitepress-plugin',
    // 构建开始时
    configResolved(config) {
      console.log('插件已加载，构建目录:', config.root)
    },
    // 转换代码
    transform(code, id) {
      if (id.endsWith('.md')) {
        // 对 Markdown 文件做处理
        return code.replace(/<!--.*?-->/g, '')
      }
      return code
    },
    // 构建结束时
    buildEnd() {
      console.log('构建完成')
    }
  }
}

Markdown-it 插件 ​

适用于扩展 Markdown 语法：

ts
// my-markdown-plugin.ts
import type { PluginSimple } from 'markdown-it'

const myMarkdownPlugin: PluginSimple = (md) => {
  // 添加自定义容器语法
  md.use(require('markdown-it-container'), 'callout', {
    render(tokens, idx) {
      const token = tokens[idx]
      const info = token.info.trim().slice('callout'.length).trim()
      if (token.nesting === 1) {
        return `<div class="callout callout-${info}">`
      }
      return '</div>'
    }
  })

  // 添加自定义内联语法
  md.inline.ruler.after('emphasis', 'my-tag', (state, silent) => {
    // 解析自定义语法
    return false
  })
}

export default myMarkdownPlugin

完整插件开发 ​

更详细的插件开发指南，请参考 插件开发指南。

插件版本策略 ​

语义化版本与兼容性 ​

版本变化风险更新策略
Patch（1.0.1→1.0.2）低可自动更新
Minor（1.0→1.1）中阅读更新日志后更新
Major（1.0→2.0）高必须阅读迁移指南

版本锁定建议 ​

json
{
  "devDependencies": {
    // 稳定的核心插件：允许 minor 更新
    "vitepress-plugin-mermaid": "^1.0.0",

    // 新插件/不稳定插件：锁定 patch
    "vitepress-plugin-new-feature": "~1.0.0",

    // 有 breaking changes 风险：精确锁定
    "vitepress-plugin-risky": "1.2.3"
  }
}

升级前检查清单 ​

  • [ ] 阅读 CHANGELOG / Release Notes
  • [ ] 检查 peerDependencies 是否与当前 VitePress 版本兼容
  • [ ] 在测试分支中升级
  • [ ] 运行 npm run build 验证构建
  • [ ] 运行 npm run dev 验证开发体验
  • [ ] 检查插件是否有安全漏洞（npm audit）

插件维护指南 ​

如果你是插件作者，以下最佳实践有助于维护插件：

命名规范 ​

规则示例
VitePress 专用插件vitepress-plugin-xxx
Vite 通用插件vite-plugin-xxx
Markdown-it 插件markdown-it-xxx

peerDependencies 声明 ​

json
{
  "peerDependencies": {
    "vitepress": ">=1.0.0",
    "vue": "^3.0.0"
  }
}

重要

插件必须将 VitePress 声明为 peerDependencies 而非 dependencies，避免重复安装导致运行时错误。

变更日志维护 ​

markdown
# Changelog

## 2.0.0 (2026-05-01)

### Breaking Changes
- 最低支持 VitePress v1.0.0
- 配置项 `oldOption` 改为 `newOption`

### Features
- 新增 `featureA` 选项

### Bug Fixes
- 修复暗色模式下的样式问题 (#123)

CI 自动化测试 ​

yaml
# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        vitepress: ['1.0.0', '1.x', '2.x']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm install vitepress@${{ matrix.vitepress }} -D
      - run: npm test
      - run: npm run build

插件冲突排查 ​

当多个插件导致构建异常时：

排查步骤 ​

  1. 逐个排查：禁用所有插件后逐个启用
  2. 检查版本：确保插件与当前 VitePress 版本兼容
  3. 查看日志：构建错误信息通常指向冲突插件
  4. 检查顺序：Vite 插件执行顺序可能影响结果

常见冲突场景 ​

冲突类型症状解决方案
Markdown-it 插件冲突解析错误或渲染异常调整插件注册顺序
Vite 插件冲突构建失败或输出异常检查 enforce 配置
版本不兼容运行时报错检查 peerDependencies
CSS 冲突样式错乱使用 scoped 样式
多个搜索插件冲突搜索不工作只保留一个搜索方案

调试技巧 ​

ts
// 在 Vite 插件中调试
export function debugPlugin(): Plugin {
  return {
    name: 'debug-plugin',
    transform(code, id) {
      if (id.includes('target-file')) {
        console.log('处理文件:', id)
        console.log('代码长度:', code.length)
      }
      return code
    }
  }
}
bash
# 使用调试模式构建
DEBUG=vitepress:* npm run docs:build

# 只看特定插件的日志
DEBUG=my-plugin:* npm run docs:build

插件发布清单 ​

步骤说明
1. 类型定义提供完整的 TypeScript 类型
2. 文档README 包含安装、配置、示例
3. 代码格式ESLint + Prettier
4. 测试单元测试 + 集成测试
5. 构建产物ESM + CJS 双格式
6. peerDependencies声明 VitePress 和 Vue
7. keywords添加 vitepress 关键词
8. LICENSE添加开源许可证
9. CI/CD自动化测试和发布
10. 发布npm publish

详细的插件开发流程，请参考 插件开发指南。

参考链接 ​

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南