插件市场

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

插件选择标准

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

维度	说明	检查方式
维护状态	最近 6 个月是否有更新	GitHub Commits
兼容性	是否支持当前 VitePress 版本	`peerDependencies`
下载量	周下载量反映使用规模	npm 周下载
问题响应	Issue 是否及时处理	GitHub Issues
文档质量	是否有完整文档和示例	官方文档
安全性	是否有已知漏洞	`npm audit`

bash

# 检查插件兼容性
npm view vitepress-plugin-mermaid peerDependencies

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

# 安全检查
npm audit

按功能分类

内容增强

插件	说明	安装	周下载量
vitepress-plugin-mermaid	Mermaid 图表支持	`npm i vitepress-plugin-mermaid -D`	5K+
vitepress-plugin-tabs	代码/内容标签页	`npm i vitepress-plugin-tabs -D`	3K+
vitepress-plugin-chart	Chart.js 图表	`npm i vitepress-plugin-chart chart.js -D`	1K+
markdown-it-katex	数学公式（LaTeX）	`npm i markdown-it-katex -D`	10K+
markdown-it-footnote	脚注支持	`npm i markdown-it-footnote -D`	5K+
markdown-it-task-lists	任务列表	`npm i markdown-it-task-lists -D`	3K+

搜索增强

插件	说明	安装	周下载量
vitepress-plugin-search	增强的本地搜索	`npm i vitepress-plugin-search -D`	2K+
vitepress-plugin-flexsearch	FlexSearch 高性能搜索	`npm i vitepress-plugin-flexsearch -D`	1K+

SEO 优化

功能	说明	方式
sitemap	站点地图	VitePress 内置
vitepress-plugin-rss	RSS 订阅源	`npm i vitepress-plugin-rss -D`
vitepress-plugin-robots	robots.txt 生成	`npm i vitepress-plugin-robots -D`
vitepress-plugin-canonical	Canonical URL	`npm i vitepress-plugin-canonical -D`

评论系统

插件	说明	安装
vitepress-plugin-comment-with-giscus	Giscus 评论	`npm i vitepress-plugin-comment-with-giscus -D`
@waline/client	Waline 评论	`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/vitepress	PWA 离线访问	`npm i @vite-pwa/vitepress -D`

热门插件配置示例

Mermaid 图表

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

// .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)。

### 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
  }
})

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

代码复制增强

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

// .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
      })
    }
  }
})

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { useCopyCode } from 'vitepress-plugin-copy-code/theme'

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

NProgress 页面进度条

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

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

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

PWA 支持

// .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 生态插件：

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

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

Vite 插件配置示例

// .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 插件：

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-emoji	Emoji 支持	`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-plantuml	PlantUML 图表	`npm i markdown-it-plantuml -D`
markdown-it-attrs	属性语法	`npm i markdown-it-attrs -D`
markdown-it-container	自定义容器	VitePress 内置

数学公式支持

// .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 支持三种类型的插件开发：

Vite 插件

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

// 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 语法：

// 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

完整插件开发

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

插件冲突排查

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

排查步骤

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

常见冲突场景

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

调试技巧

// 在 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

插件市场

插件选择标准

按功能分类

内容增强

搜索增强

SEO 优化

评论系统

开发工具

PWA 支持

热门插件配置示例

Mermaid 图表

代码复制增强

NProgress 页面进度条

PWA 支持

Vite 插件兼容

推荐 Vite 插件

Vite 插件配置示例

Markdown 插件

常用 Markdown-it 插件

数学公式支持

开发自定义插件

Vite 插件

Markdown-it 插件

完整插件开发

插件冲突排查

排查步骤

常见冲突场景

调试技巧

参考链接

贡献者

插件市场 ​

插件选择标准 ​

按功能分类 ​

内容增强 ​

搜索增强 ​

SEO 优化 ​

评论系统 ​

开发工具 ​

PWA 支持 ​

热门插件配置示例 ​

Mermaid 图表 ​

代码复制增强 ​

NProgress 页面进度条 ​

PWA 支持 ​

Vite 插件兼容 ​

推荐 Vite 插件 ​

Vite 插件配置示例 ​

Markdown 插件 ​

常用 Markdown-it 插件 ​

数学公式支持 ​

开发自定义插件 ​

Vite 插件 ​

Markdown-it 插件 ​

完整插件开发 ​

插件冲突排查 ​

排查步骤 ​

常见冲突场景 ​

调试技巧 ​

参考链接 ​

贡献者

插件市场

插件选择标准

按功能分类

内容增强

搜索增强

SEO 优化

评论系统

开发工具

PWA 支持

热门插件配置示例

Mermaid 图表

代码复制增强

NProgress 页面进度条

PWA 支持

Vite 插件兼容

推荐 Vite 插件

Vite 插件配置示例

Markdown 插件

常用 Markdown-it 插件

数学公式支持

开发自定义插件

Vite 插件

Markdown-it 插件

完整插件开发

插件冲突排查

排查步骤

常见冲突场景

调试技巧

参考链接