Vite 插件生态集成

VitePress 基于 Vite 构建，因此可以直接使用 Vite 丰富的插件生态来扩展站点功能。

VitePress 与 Vite 的关系

graph TB
    VP[VitePress] --> Vite[Vite]
    Vite --> Rollup[Rollup]
    
    VP --> |使用| MD[Markdown-it]
    VP --> |使用| Vue[Vue 3 SSR]
    Vite --> |插件系统| Plugins[Vite 插件]
    Rollup --> |插件兼容| RollupPlugins[Rollup 插件]

配置入口

VitePress 通过 vite 字段将配置传递给 Vite：

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    // 所有 Vite 配置选项
    plugins: [],
    resolve: { alias: {} },
    build: {},
    server: {}
  }
})

常用插件集成

1. 组件自动导入

使用 unplugin-vue-components 自动注册 Vue 组件：

npm install -D unplugin-vue-components

// .vitepress/config.mts
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  vite: {
    plugins: [
      Components({
        // 自动导入 .vitepress/theme/components 下的组件
        dirs: ['.vitepress/theme/components'],
        include: [/\.vue$/, /\.md$/],
        dts: '.vitepress/components.d.ts'
      })
    ]
  }
})

2. 自动导入 API

使用 unplugin-auto-import 自动导入 Vue 和 VueUse API：

npm install -D unplugin-auto-import

import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  vite: {
    plugins: [
      AutoImport({
        imports: ['vue', 'vue-router'],
        dts: '.vitepress/auto-imports.d.ts'
      })
    ]
  }
})

3. PWA 支持

使用 vite-plugin-pwa 为站点添加离线支持：

npm install -D vite-plugin-pwa

import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  vite: {
    plugins: [
      VitePWA({
        registerType: 'autoUpdate',
        manifest: {
          name: '我的文档站',
          short_name: '文档',
          theme_color: '#646cff'
        },
        workbox: {
          globPatterns: ['**/*.{css,js,html,svg,png,ico,txt,woff2}']
        }
      })
    ]
  }
})

4. 图片压缩

使用 vite-plugin-imagemin 自动压缩图片：

npm install -D vite-plugin-imagemin

import viteImagemin from 'vite-plugin-imagemin'

export default defineConfig({
  vite: {
    plugins: [
      viteImagemin({
        gifsicle: { optimizationLevel: 7 },
        optipng: { optimizationLevel: 7 },
        mozjpeg: { quality: 80 },
        pngquant: { quality: [0.65, 0.8] },
        svgo: { plugins: [{ name: 'removeViewBox' }] }
      })
    ]
  }
})

5. Markdown 增强

数学公式（KaTeX）

npm install -D markdown-it-katex

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

脚注

npm install -D markdown-it-footnote

export default defineConfig({
  markdown: {
    config(md) {
      md.use(require('markdown-it-footnote'))
    }
  }
})

6. 构建分析

使用 rollup-plugin-visualizer 分析包体积：

npm install -D rollup-plugin-visualizer

import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  vite: {
    plugins: process.env.ANALYZE
      ? [visualizer({ filename: 'stats.html', open: true })]
      : []
  }
})

ANALYZE=true npm run build

SSR 兼容性

插件 SSR 支持

由于 VitePress 使用 SSR，插件必须兼容 SSR：

export default defineConfig({
  vite: {
    plugins: [
      SomePlugin({
        // 如果插件不支持 SSR，可以禁用
        ssr: false
      })
    ],
    // SSR 外部化依赖
    ssr: {
      external: ['some-module'],
      noExternal: ['vue', 'vue-router']
    }
  }
})

常见 SSR 问题

问题	原因	解决方案
window is not defined	插件在 Node.js 端执行	使用 defineClientComponent 或条件导入
document is not defined	DOM API 不可用	延迟到客户端执行
样式闪烁	SSR 和客户端不一致	确保样式在两端一致

defineClientComponent

对于仅在客户端渲染的组件：

<script setup lang="ts">
import { defineClientComponent } from 'vitepress/client'

// 仅在客户端加载和渲染
const Chart = defineClientComponent(() => {
  return import('./Chart.vue')
})
</script>

<template>
  <Chart />
</template>

Vite 配置技巧

路径别名

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        '@': '/.vitepress/theme',
        '@components': '/.vitepress/theme/components',
        '@composables': '/.vitepress/theme/composables'
      }
    }
  }
})

依赖预构建

export default defineConfig({
  vite: {
    optimizeDeps: {
      include: ['vue', '@vueuse/core'],
      exclude: ['vitepress']
    }
  }
})

构建优化

export default defineConfig({
  vite: {
    build: {
      chunkSizeWarningLimit: 1500,
      rollupOptions: {
        output: {
          manualChunks: {
            'vue-vendor': ['vue', 'vue-router'],
            'utils': ['@vueuse/core']
          }
        }
      }
    }
  }
})

插件开发

VitePress 专属 Vite 插件

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

export function myVitePressPlugin(): Plugin {
  return {
    name: 'my-vitepress-plugin',
    
    // 仅在构建时执行
    apply: 'build',
    
    // 转换 HTML
    transformIndexHtml(html) {
      return html.replace(
        '</head>',
        '<meta name="generator" content="MyPlugin" />\n</head>'
      )
    },
    
    // 转换模块
    transform(code, id) {
      if (id.endsWith('.md')) {
        // 处理 Markdown 文件
        return code
      }
    }
  }
}

推荐插件列表

插件	用途	SSR 兼容
unplugin-vue-components	组件自动导入	✅
unplugin-auto-import	API 自动导入	✅
vite-plugin-pwa	PWA 支持	✅
vite-plugin-imagemin	图片压缩	✅
markdown-it-footnote	脚注	✅
markdown-it-katex	数学公式	✅
rollup-plugin-visualizer	构建分析	✅
vite-plugin-svg-icons	SVG 图标	⚠️ 需配置

相关链接

• Vite 官方文档 — Vite 配置和插件开发
• SSR 兼容性 — SSR 注意事项
• 构建优化 — 生产构建优化
• 插件开发指南 — VitePress 插件开发