夜雨聆风你用过
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 插件开发速查
config | |
configResolved | |
configureServer | |
resolveIdload | |
transform | |
transformIndexHtml | |
handleHotUpdate | |
generateBundle | |
closeBundle |
Vite 插件开发的核心思路：找到合适的钩子，拦截你需要的时机，注入/转换你想要的内容。
掌握这套机制，你就能理解绝大多数社区插件的工作原理，遇到 bug 也能自己动手修。
下一篇预告
《pnpm + Workspace 进阶：Monorepo 实战中的包版本管理与发布自动化》
从 changeset 版本管理到 CI/CD 自动发布 npm，彻底搞定多包仓库的发布流程。
如果这篇文章对你有帮助，欢迎关注公众号「有头发的帅哥程序员」，每周持续更新前端硬核干货 🔥
