Vite 插件开发实战:从 Rollup 插件机制到自定义 Vite 插件

你用过 unplugin-auto-import、vite-plugin-svg-icons，但你有没有想过——自己写一个？

Vite 插件开发门槛其实比你想象的低很多。本文从底层机制讲起，带你一步步写出几个真正有用的 Vite 插件。

一、Vite 插件与 Rollup 插件的关系

Vite 的插件系统 完全兼容 Rollup 插件。在 开发模式（dev server） 下，Vite 使用自己的 esbuild 预构建 + 模块热替换；在 构建模式（build） 下，Vite 直接调用 Rollup 打包。

Vite Plugin├── Rollup 通用钩子（build 阶段 + dev 阶段均触发）│   ├── options、buildStart、resolveId、load│   ├── transform、moduleParsed、buildEnd、closeBundle│   └── generateBundle、writeBundle、closeBundle...└── Vite 专属钩子（仅 dev server 阶段触发）    ├── config、configResolved、configureServer    ├── transformIndexHtml、handleHotUpdate    └── resolveId（虚拟模块扩展）

一个 Vite 插件就是一个返回对象的工厂函数：

importtype { Plugin } from'vite'exportfunctionmyPlugin(): Plugin {return {name: 'vite-plugin-my',   // 插件名称（必填，用于日志/错误追踪）// ...各种钩子  }}

二、插件钩子执行顺序（图解）

Dev Server 启动  ↓config          → 修改 Vite 配置  ↓configResolved  → 获取最终配置（只读）  ↓configureServer → 操作 dev server（添加中间件）  ↓buildStart      → 构建开始  ↓ 每个模块  ├── resolveId  → 解析模块 ID（可返回虚拟路径）  ├── load       → 加载模块内容（可返回虚拟代码）  └── transform  → 转换模块代码  ↓transformIndexHtml → 修改 index.html  ↓generateBundle  → 生成产物（build 阶段）  ↓closeBundle     → 构建结束

钩子执行顺序（enforce）

// enforce: 'pre'  → 在普通插件之前执行// 默认（无 enforce）→ 普通顺序// enforce: 'post' → 在普通插件之后执行exportfunctionmyPlugin(): Plugin {return {name: 'vite-plugin-my',enforce: 'pre',transform(code, id) { /* ... */ }  }}

三、实战一：环境变量注入插件

需求：在构建时，自动把 BUILD_TIME、GIT_COMMIT 等信息注入到全局变量。

// plugins/vite-plugin-build-info.tsimport { execSync } from 'child_process'import type { Plugin } from 'vite'export interface BuildInfoOptions {/** 额外注入的变量 */extra?: Record<string, string>}export function buildInfoPlugin(options: BuildInfoOptions = {}): Plugin {let gitCommit = 'unknown'let gitBranch = 'unknown'try {    gitCommit = execSync('git rev-parse --short HEAD').toString().trim()    gitBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim()  } catch {// 非 git 仓库，忽略  }const buildTime = newDate().toISOString()return {name: 'vite-plugin-build-info',enforce: 'pre',config() {return {define: {'__BUILD_TIME__': JSON.stringify(buildTime),'__GIT_COMMIT__': JSON.stringify(gitCommit),'__GIT_BRANCH__': JSON.stringify(gitBranch),          ...Object.fromEntries(Object.entries(options.extra ?? {}).map(([k, v]) => [`__${k}__`,JSON.stringify(v),            ])          ),        },      }    },  }}

使用：

// vite.config.tsimport { buildInfoPlugin } from'./plugins/vite-plugin-build-info'exportdefaultdefineConfig({plugins: [buildInfoPlugin({extra: { APP_VERSION: '1.2.0' }    }),  ],})

页面中使用：

console.log('构建时间：', __BUILD_TIME__)console.log('Git Commit：', __GIT_COMMIT__)console.log('版本号：', __APP_VERSION__)

TypeScript 需在 env.d.ts 中声明：

declareconst__BUILD_TIME__: stringdeclareconst__GIT_COMMIT__: string

四、实战二：虚拟模块插件

虚拟模块是 Vite/Rollup 最强大的特性之一——你可以在不创建实际文件的情况下，向代码注入任意内容。

约定：虚拟模块 ID 以 virtual: 开头（Rollup 约定用 \0 前缀内部标识）。

// plugins/vite-plugin-virtual-routes.tsimport type { Plugin } from 'vite'import { readdirSync, statSync } from 'fs'import { join, extname, basename } from 'path'const VIRTUAL_ID = 'virtual:auto-routes'const RESOLVED_ID = '\0' + VIRTUAL_IDexport function virtualRoutesPlugin(pagesDir: string): Plugin {function scanPages(dir: string, prefix = '') {const routes: Array<{ path: string; component: string }> = []readdirSync(dir).forEach((file) => {const fullPath = join(dir, file)const stat = statSync(fullPath)if (stat.isDirectory()) {        routes.push(...scanPages(fullPath, `${prefix}/${file}`))      } else if (['.vue', '.tsx', '.jsx'].includes(extname(file))) {const name = basename(file, extname(file))const routePath = name === 'index'          ? prefix || '/'          : `${prefix}/${name}`        routes.push({path: routePath,component: fullPath.replace(/\\/g, '/'),        })      }    })return routes  }return {name: 'vite-plugin-virtual-routes',resolveId(id) {if (id === VIRTUAL_ID) returnRESOLVED_ID    },load(id) {if (id !== RESOLVED_ID) returnconst routes = scanPages(pagesDir)// 生成路由配置代码const imports = routes        .map((r, i) =>`import Page${i} from '${r.component}'`)        .join('\n')const routeList = routes        .map((r, i) =>`{ path: '${r.path}', component: Page${i} }`)        .join(',\n  ')return`${imports}export const routes = [${routeList}]`    },  }}

使用：

// vite.config.tsimport { virtualRoutesPlugin } from'./plugins/vite-plugin-virtual-routes'import { resolve } from'path'exportdefaultdefineConfig({plugins: [virtualRoutesPlugin(resolve(__dirname, 'src/pages')),  ],})

// src/router/index.tsimport { createRouter, createWebHistory } from'vue-router'import { routes } from'virtual:auto-routes'// ✨ 虚拟模块！exportdefaultcreateRouter({history: createWebHistory(),  routes,})

五、实战三：SVG 自动组件化插件

将 *.svg 文件自动转换为 Vue/React 组件，告别 <img src="..."> 的无样式限制。

// plugins/vite-plugin-svg-component.tsimport type { Plugin } from 'vite'import { readFileSync } from 'fs'import { optimize } from 'svgo'export interface SvgComponentOptions {/** 框架类型 */framework?: 'vue' | 'react'}export function svgComponentPlugin(options: SvgComponentOptions = {}): Plugin {const { framework = 'vue' } = optionsreturn {name: 'vite-plugin-svg-component',enforce: 'pre',async transform(code, id) {// 只处理 ?component 后缀的 SVGif (!id.match(/\.svg\?component$/)) returnnullconst filePath = id.replace(/\?component$/, '')const svgCode = readFileSync(filePath, 'utf-8')// 用 SVGO 优化 SVGconst { data: optimizedSvg } = optimize(svgCode, {plugins: ['removeComments','removeEmptyAttrs',          {name: 'removeAttrs',params: { attrs: ['fill', 'stroke'] }, // 移除硬编码颜色，改由 CSS 控制          },        ],      })if (framework === 'vue') {return {code: `<template>${optimizedSvg}</template><script setup>defineOptions({ name: 'SvgIcon' })</script>`,map: null,        }      }if (framework === 'react') {// 将 SVG 转为 JSX（简化版，实际可用 @svgr/core）const jsxSvg = optimizedSvg          .replace(/class=/g, 'className=')          .replace(/([a-z])-([a-z])/g, (_, a, b) => a + b.toUpperCase()) // kebab-case → camelCasereturn {code: `import React from 'react'export default function SvgIcon(props) {  return (${jsxSvg.replace('<svg', '<svg {...props}')})}`,map: null,        }      }    },  }}

Vue 中使用：

<script setup>import StarIcon from '@/assets/icons/star.svg?component'</script><template>  <!-- 直接用 CSS 控制颜色 -->  <StarIcon style="color: #f0c040; width: 24px; height: 24px;" /></template>

六、实战四：开发服务器中间件插件

有时我们需要在 dev server 中加入 mock 数据接口，这时就要用到 configureServer 钩子。

// plugins/vite-plugin-mock.tsimport type { Plugin, ViteDevServer } from 'vite'import { readdirSync } from 'fs'import { join } from 'path'export interface MockRoute {method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'url: stringresponse: unknown | ((params: Record<string, string>, body: unknown) =>unknown)delay?: number}export function mockPlugin(mockDir: string): Plugin {return {name: 'vite-plugin-mock',configureServer(server: ViteDevServer) {// 动态加载所有 mock 文件function loadMocks() {const mocks: MockRoute[] = []try {readdirSync(mockDir)            .filter(f => f.endsWith('.ts') || f.endsWith('.js'))            .forEach(file => {// ⚠️ 生产环境不会加载，此处用 require 仅作演示// 实际项目推荐用 vite-plugin-mock 等成熟方案const mod = require(join(mockDir, file))              mocks.push(...(Array.isArray(mod.default) ? mod.default : [mod.default]))            })        } catch { /* 目录不存在则忽略 */ }return mocks      }      server.middlewares.use(async (req, res, next) => {const mocks = loadMocks()const mock = mocks.find(m => {const method = (m.method ?? 'GET').toUpperCase()return method === req.method?.toUpperCase() && req.url === m.url        })if (!mock) return next()// 模拟延迟if (mock.delay) {await new Promise(r =>setTimeout(r, mock.delay))        }let body = ''if (req.method !== 'GET') {          body = await new Promise<string>(resolve => {let data = ''            req.on('data', chunk => { data += chunk })            req.on('end', () =>resolve(data))          })        }const parsedBody = body ? JSON.parse(body) : {}const urlParams = Object.fromEntries(new URL(req.url!, `http://localhost`).searchParams        )const responseData = typeof mock.response === 'function'          ? mock.response(urlParams, parsedBody)          : mock.response        res.setHeader('Content-Type', 'application/json')        res.setHeader('Access-Control-Allow-Origin', '*')        res.end(JSON.stringify(responseData))      })    },  }}

Mock 文件示例（mock/user.ts）：

// mock/user.tsimport type { MockRoute } from'../plugins/vite-plugin-mock'const routes: MockRoute[] = [  {method: 'GET',url: '/api/user/info',delay: 200,response: {code: 0,data: {id: 1,name: '有头发的帅哥程序员',avatar: 'https://example.com/avatar.png',role: 'admin',      },    },  },  {method: 'POST',url: '/api/user/login',response: (_, body: any) => ({code: body.password === '123456' ? 0 : 401,data: body.password === '123456'        ? { token: 'mock-jwt-token-xxxx' }        : null,message: body.password === '123456' ? 'ok' : '密码错误',    }),  },]export default routes

七、实战五：构建产物分析插件

在 generateBundle 和 writeBundle 钩子中，可以拿到所有打包产物，做统计分析。

// plugins/vite-plugin-bundle-analyzer.tsimport type { Plugin, NormalizedOutputOptions, OutputBundle } from 'rollup'import { writeFileSync } from'fs'export function bundleAnalyzerPlugin(): Plugin {return {name: 'vite-plugin-bundle-analyzer',apply: 'build',   // 仅在 build 时生效generateBundle(options: NormalizedOutputOptions, bundle: OutputBundle) {const stats: Array<{ file: string; size: number; type: string }> = []for (const [fileName, chunk] of Object.entries(bundle)) {if (chunk.type === 'chunk') {          stats.push({file: fileName,size: Buffer.byteLength(chunk.code, 'utf8'),type: chunk.isEntry ? 'entry' : chunk.isDynamicEntry ? 'dynamic' : 'vendor',          })        } else if (chunk.type === 'asset' && chunk.source) {const size = typeof chunk.source === 'string'            ? Buffer.byteLength(chunk.source, 'utf8')            : chunk.source.byteLength          stats.push({ file: fileName, size, type: 'asset' })        }      }// 按大小排序      stats.sort((a, b) => b.size - a.size)// 生成分析报告const total = stats.reduce((sum, s) => sum + s.size, 0)const report = [`# Bundle Analysis Report`,`Total: ${(total / 1024).toFixed(2)} KB`,``,`| File | Size | Type |`,`|------|------|------|`,        ...stats.map(s =>`| ${s.file} | ${(s.size / 1024).toFixed(2)} KB | ${s.type} |`),      ].join('\n')writeFileSync('dist/bundle-report.md', report)console.log('\n📦 Bundle analysis saved to dist/bundle-report.md')// 警告超大文件const WARN_SIZE = 500 * 1024// 500KB      stats        .filter(s => s.size > WARN_SIZE)        .forEach(s => {console.warn(`⚠️  Large chunk: ${s.file} (${(s.size / 1024).toFixed(2)} KB)`)        })    },  }}

八、插件开发最佳实践

8.1 插件选项校验

使用 zod 做选项类型校验，避免用户传错配置：

import { z } from 'zod'const optionsSchema = z.object({include: z.array(z.string()).default(['**/*.ts']),exclude: z.array(z.string()).default(['node_modules/**']),verbose: z.boolean().default(false),})export type PluginOptions = z.input<typeof optionsSchema>export function myPlugin(userOptions: PluginOptions = {}): Plugin {const options = optionsSchema.parse(userOptions) // 校验 + 填充默认值// ...}

8.2 利用 createFilter 筛选文件

Vite 内置了 createFilter 工具函数，专门用于插件文件过滤：

import { createFilter } from 'vite'export function myPlugin(): Plugin {const filter = createFilter(    ['**/*.ts', '**/*.vue'],     // include    ['node_modules/**', '**/*.d.ts']  // exclude  )return {name: 'vite-plugin-my',transform(code, id) {if (!filter(id)) returnnull// 不匹配则跳过// 处理文件...    },  }}

8.3 缓存转换结果

transform 钩子每次文件变化都会触发，加缓存可以显著提升热更新速度：

exportfunction myPlugin(): Plugin {const cache = new Map<string, { code: string; hash: string }>()return {name: 'vite-plugin-my',transform(code, id) {// 用文件内容 hash 作为缓存 keyconst hash = require('crypto')        .createHash('md5')        .update(code)        .digest('hex')const cached = cache.get(id)if (cached?.hash === hash) return cached.codeconst result = expensiveTransform(code)      cache.set(id, { code: result, hash })return result    },  }}

8.4 插件通信：共享状态

多个插件之间需要共享状态时，可以用闭包或外部 Map：

// 在模块顶层创建共享 storeconst store = new Map<string, unknown>()export function pluginA(): Plugin {return {name: 'plugin-a',buildStart() {      store.set('startTime', Date.now())    },  }}export function pluginB(): Plugin {return {name: 'plugin-b',closeBundle() {const start = store.get('startTime') asnumberconsole.log(`Build took: ${Date.now() - start}ms`)    },  }}

8.5 apply 字段：控制插件生效时机

exportfunctionmyPlugin(): Plugin {return {name: 'vite-plugin-my',apply: 'build',         // 仅 build 时生效（'serve' | 'build' | function）// 或者：apply(config, { command }) {// 仅在 build 且非 SSR 时生效return command === 'build' && !config.build?.ssr    },  }}

九、发布你的 Vite 插件到 npm

package.json 配置

{"name":"vite-plugin-my-awesome","version":"1.0.0","description":"一个很棒的 Vite 插件","main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs","types":"./dist/index.d.ts"}},"keywords":["vite","vite-plugin"],"peerDependencies":{"vite":"^4.0.0 || ^5.0.0 || ^6.0.0"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","prepublishOnly":"npm run build"}}

用 tsup 打包

pnpm add -D tsup# tsup.config.tsimport { defineConfig } from 'tsup'export default defineConfig({  entry: ['src/index.ts'],  format: ['cjs', 'esm'],  dts: true,  clean: true,  external: ['vite'],})

十、总结：Vite 插件开发速查

Vite 插件开发的核心思路：找到合适的钩子，拦截你需要的时机，注入/转换你想要的内容。

掌握这套机制，你就能理解绝大多数社区插件的工作原理，遇到 bug 也能自己动手修。

下一篇预告

《pnpm + Workspace 进阶：Monorepo 实战中的包版本管理与发布自动化》

从 changeset 版本管理到 CI/CD 自动发布 npm，彻底搞定多包仓库的发布流程。

如果这篇文章对你有帮助，欢迎关注公众号「有头发的帅哥程序员」，每周持续更新前端硬核干货 🔥