Vite插件开发框架:14个实用插件与完整工具包

npm install @meng-xi/vite-plugin

// vite.config.tsimport { assetManifest, autoImport, buildProgress, compressAssets, envGuard, generateVersion, versionUpdateChecker } from '@meng-xi/vite-plugin'export default defineConfig({  plugins: [    buildProgress(),    autoImport({ imports: { vue: ['ref', 'reactive'] } }),    compressAssets({ algorithm: 'both' }),    generateVersion({ format: 'datetime', outputType: 'both' }),    versionUpdateChecker(),    envGuard({      required: { VITE_API_URL: { type: 'url', required: true } }    })  ]})

import { assetManifest } from '@meng-xi/vite-plugin/plugins/asset-manifest'import { formatFileSize } from '@meng-xi/vite-plugin/common/format'import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'

interface BasePluginOptions {enabled?: boolean // 是否启用插件，默认 trueverbose?: boolean // 是否启用日志，默认 trueerrorStrategy?: 'throw' | 'log' | 'ignore' // 错误处理策略，默认 'throw'}

import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'class MyPlugin extends BasePlugin<MyPluginOptions> {protected getPluginName() {return 'my-plugin'}protected getDefaultOptions() {return { myOption: 'default' }}protected validateOptions() {this.validator.field('myOption').string().validate()}protected addPluginHooks(plugin: Plugin) {		plugin.writeBundle = async () => {await this.safeExecute(() => this.doWork(), '执行工作')}}}export const myPlugin = createPluginFactory(MyPlugin)

// 基本用法const myPlugin = createPluginFactory(MyPlugin)// 带标准化器（支持字符串或对象配置）const myPlugin = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))

const plugin = myPlugin({ myOption: 'test' })// 构建完成后访问插件实例const instance = plugin.pluginInstance

import { Logger } from '@meng-xi/vite-plugin/logger'// 创建日志记录器const logger = Logger.create({ name: 'my-plugin', enabled: true })// 创建插件日志代理const pluginLogger = logger.createPluginLogger('my-plugin')pluginLogger.success('操作成功')pluginLogger.info('处理中...')pluginLogger.warn('注意')pluginLogger.error('出错了')// 注销插件日志Logger.unregister('my-plugin')// 销毁单例（测试场景）Logger.destroy()

interface AssetManifestOptions extends BasePluginOptions {outputFormat?: 'vite' | 'webpack' | 'custom' // 清单格式，默认 'vite'outputFile?: string // 输出文件名，默认 'manifest.json'includeExtensions?: string[] // 包含的扩展名publicPath?: string // 公共路径前缀，默认 '/'injectRuntime?: boolean // 注入运行时全局变量，默认 falseruntimeGlobalName?: string // 全局变量名，默认 '__ASSET_MANIFEST__'customFormatter?: CustomFormatter | null // 自定义格式化器groupByEntry?: boolean // 按入口分组，默认 falseexcludeExtensions?: string[] // 排除的扩展名excludePaths?: string[] // 排除的路径}

assetManifest({outputFormat: 'vite',publicPath: 'https://cdn.example.com/',injectRuntime: true,groupByEntry: true})

interface AutoImportOptions extends BasePluginOptions {  imports?: Record<string, string[]> | ImportMapping[] | Array<...>  // 导入映射  dirs?: string[]                           // 扫描目录列表  dts?: string | boolean                    // 类型声明文件路径，默认 'src/auto-imports.d.ts'  vueTemplate?: boolean                     // Vue 模板自动导入，默认 false  ignore?: string[]                         // 忽略的标识符  fileFilter?: RegExp                       // 文件过滤正则  injectAtPosition?: 'top' | 'after-last-import'  // 注入位置，默认 'top'}

autoImport({imports: {vue: ['ref', 'reactive', 'computed', 'watch', 'onMounted'],'vue-router': ['useRouter', 'useRoute']},dirs: ['src/composables', 'src/stores'],dts: 'src/auto-imports.d.ts',vueTemplate: true,injectAtPosition: 'after-last-import'})

config (5%) → resolve (10%) → transform (15%-85%) → bundle (+10%) → write (+5%) → done (100%)

interface BuildProgressOptions extends BasePluginOptions {width?: number // 进度条宽度，默认 30format?: 'bar' | 'spinner' | 'minimal' // 显示格式，默认 'bar'completeChar?: string // 完成填充字符，默认 '█'incompleteChar?: string // 未完成填充字符，默认 '░'clearOnComplete?: boolean // 完成后清除，默认 trueshowModuleName?: boolean // 显示模块名，默认 truetheme?: ProgressTheme // 自定义颜色主题}

// 默认进度条buildProgress()// 旋转动画buildProgress({ format: 'spinner' })// 自定义外观buildProgress({width: 40,completeChar: '■',incompleteChar: '□',clearOnComplete: false})

interface BundleAnalyzerOptions extends BasePluginOptions {outputFormat?: 'json' | 'html' | 'both' // 报告格式，默认 'json'outputFile?: string // 输出文件名，默认 'bundle-analysis'openAnalyzer?: boolean // 自动打开报告，默认 falsesizeThreshold?: number // 体积阈值（KB），默认 100topModules?: number // Top N 数量，默认 20compareWith?: string | null // 对比报告路径gzipSize?: boolean // 计算 gzip 大小，默认 trueexcludeNodeModules?: boolean // 排除 node_modules，默认 falseexcludePatterns?: string[] // 排除的路径模式includeExtensions?: string[] // 包含的扩展名defaultChartType?: 'treemap' | 'sunburst' | 'list' // 图表类型，默认 'treemap'}

bundleAnalyzer({outputFormat: 'both',sizeThreshold: 200,topModules: 30,gzipSize: true,compareWith: 'bundle-analysis-prev.json',defaultChartType: 'treemap'})

interface CompressAssetsOptions extends BasePluginOptions {algorithm?: 'gzip' | 'brotli' | 'both' // 压缩算法，默认 'gzip'threshold?: number // 最小阈值（字节），默认 1024deleteOriginalFile?: boolean // 删除原始文件，默认 falseincludeExtensions?: string[] // 包含的扩展名excludeExtensions?: string[] // 排除的扩展名excludePaths?: string[] // 排除的路径compressionLevel?: number // gzip 级别 1-9，默认 9brotliQuality?: number // brotli 质量 1-11，默认 11reportOutput?: string | false // 报告路径，默认 'compress-report.json'parallelLimit?: number // 并发数，默认 10}

compressAssets({algorithm: 'both',threshold: 2048,compressionLevel: 9,brotliQuality: 11,reportOutput: 'compress-report.json'})

interface CopyFileOptions extends BasePluginOptions {sourceDir: string // 源目录（必填）targetDir: string // 目标目录（必填）overwrite?: boolean // 覆盖同名文件，默认 truerecursive?: boolean // 递归复制，默认 trueincremental?: boolean // 增量复制，默认 true}

copyFile({sourceDir: 'src/assets',targetDir: 'dist/assets',overwrite: false,incremental: true})

interface EnvGuardOptions extends BasePluginOptions {required?: Record<string, EnvFieldRule> // 校验规则映射failAction?: 'error' | 'warn' | 'ignore' // 失败处理，默认 'error'generateTemplate?: boolean // 生成模板，默认 truetemplateOutput?: string // 模板路径，默认 '.env.template'runtimeGuard?: boolean // 运行时守卫，默认 falseruntimeGlobalName?: string // 全局变量名，默认 '__ENV_GUARD__'runtimeGuardMode?: 'console' | 'throw' | 'overlay' // 守卫模式envFiles?: string[] // .env 文件列表autoLoadEnv?: boolean // 自动加载，默认 truereportOutput?: string | false // 报告路径validateBeforeBuild?: boolean // 构建前校验，默认 trueshowSummary?: boolean // 显示摘要，默认 true}

envGuard({required: {VITE_API_BASE_URL: { type: 'url', required: true, message: 'API 地址必须为合法 URL' },VITE_APP_TITLE: { type: 'string', required: true, minLength: 1, maxLength: 50 },VITE_API_TIMEOUT: { type: 'number', minValue: 1000, maxValue: 60000 },VITE_LOG_LEVEL: { type: 'enum', enumValues: ['debug', 'info', 'warn', 'error'] }},failAction: 'error',generateTemplate: true,runtimeGuard: true,runtimeGuardMode: 'console'})

interface FaviconManagerOptions extends BasePluginOptions {base?: string // 基础路径，默认 '/'url?: string // 完整图标 URLlink?: string // 自定义 link 标签 HTMLicons?: Icon[] // 图标数组copyOptions?: {// 文件复制配置sourceDir: stringtargetDir: stringoverwrite?: booleanrecursive?: boolean}}

// 简写faviconManager('/assets')// 完整配置faviconManager({base: '/assets',icons: [{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },{ rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }],copyOptions: {sourceDir: 'src/assets/icons',targetDir: 'dist/assets/icons'}})

interface GenerateRouterOptions extends BasePluginOptions {pagesJsonPath?: string // pages.json 路径，默认 'src/pages.json'outputPath?: string // 输出路径，默认 'src/router.config.ts'outputFormat?: 'ts' | 'js' // 输出格式，默认 'ts'nameStrategy?: NameStrategy // 命名策略，默认 'camelCase'customNameGenerator?: (path: string) => string // 自定义命名函数includeSubPackages?: boolean // 包含子包，默认 truewatch?: boolean // 监听变化，默认 truemetaMapping?: Record<string, string> // 元信息映射exportTypes?: boolean // 导出类型定义，默认 truepreserveRouteChanges?: boolean // 保留用户修改，默认 truedts?: string | boolean // 类型声明文件路径，默认 false}

generateRouter({pagesJsonPath: 'src/pages.json',outputPath: 'src/router.config.ts',nameStrategy: 'camelCase',metaMapping: {navigationBarTitleText: 'title',requireAuth: 'requireAuth'},dts: true})

interface GenerateVersionOptions extends BasePluginOptions {format?: VersionFormat // 版本格式，默认 'timestamp'customFormat?: string // 自定义格式模板semverBase?: string // semver 基础值，默认 '1.0.0'outputType?: 'file' | 'define' | 'both' // 输出类型，默认 'file'outputFile?: string // 输出文件名，默认 'version.json'defineName?: string // 全局变量名，默认 '__APP_VERSION__'hashLength?: number // 哈希长度，默认 8prefix?: string // 前缀suffix?: string // 后缀extra?: Record<string, any> // 附加信息}

// 时间戳格式 + 文件输出generateVersion({ format: 'timestamp' })// semver + 全局变量注入generateVersion({ format: 'semver', semverBase: '2.0.0', prefix: 'v', outputType: 'define' })// 自定义格式 + 双输出generateVersion({format: 'custom',customFormat: '{YYYY}.{MM}.{DD}-{hash}',hashLength: 6,outputType: 'both',extra: { environment: 'production' }})

interface HtmlInjectOptions extends BasePluginOptions {targetFile?: string // 目标 HTML 文件，默认 'index.html'rules: InjectRule[] // 注入规则数组（必填）security?: SecurityConfig // 安全过滤配置templateVars?: Record<string, string> // 全局模板变量logInjection?: boolean // 输出注入日志，默认 true}interface InjectRule {id?: string // 规则标识content: string // 注入内容position: InjectPosition // 注入位置selector?: string // CSS 选择器priority?: number // 优先级condition?: InjectCondition // 条件配置templateVars?: Record<string, string> // 规则级模板变量allowScriptInjection?: boolean // 允许注入 script，默认 false}

htmlInject({rules: [{id: 'meta-description',content: '<meta name="description" content="{{appName}}">',position: 'head-end',templateVars: { appName: 'My Application' }},{id: 'analytics',content: '<script src="/analytics.js"></script>',position: 'body-end',condition: { type: 'env', value: 'PRODUCTION' },allowScriptInjection: true}]})

interface ImageOptimizerOptions extends BasePluginOptions {quality?: FormatQualityOptions // 各格式压缩质量convertToWebp?: Partial<Record<'jpeg' | 'png' | 'gif' | 'tiff', boolean>> // 转 WebPconvertToAvif?: Partial<Record<'jpeg' | 'png' | 'gif' | 'tiff', boolean>> // 转 AVIFconvertMapping?: ConvertMapping // 自定义转换映射（优先级更高）svgo?: SvgoOptions // SVG 优化配置includeExtensions?: string[] // 包含的扩展名excludePaths?: string[] // 排除的路径threshold?: number // 最小阈值（字节），默认 0keepOriginal?: boolean // 保留原文件，默认 truereportOutput?: string | false // 报告路径parallelLimit?: number // 并发数，默认 5maxPixels?: number // 最大像素数，0 不限制}

// 仅压缩imageOptimizer({quality: { jpeg: 80, png: 6, webp: 75 },reportOutput: 'image-optimize-report.json'})// PNG/JPEG → WebP 转换imageOptimizer({convertToWebp: { png: true, jpeg: true },keepOriginal: true,quality: { webp: 75 }})// SVG 优化imageOptimizer({svgo: {plugins: [{ name: 'removeViewBox', active: false },{ name: 'removeEmptyContainers', active: true }],multipass: true}})

interface LoadingManagerOptions extends BasePluginOptions {position?: 'center' | 'top' | 'bottom' // 显示位置，默认 'center'defaultText?: string // 默认文本，默认 '加载中...'spinnerType?: SpinnerType // 图标类型，默认 'spinner'style?: LoadingStyle // 自定义样式transition?: TransitionConfig // 过渡动画minDisplayTime?: MinDisplayTime // 最小显示时间delayShow?: DelayShow // 延迟显示debounceHide?: DebounceHide // 防抖隐藏autoBind?: AutoBindMode // 自动拦截模式，默认 'none'requestFilter?: RequestFilter // 请求过滤globalName?: string // 全局变量名，默认 '__LOADING_MANAGER__'customTemplate?: string // 自定义模板defaultVisible?: boolean // 初始可见，默认 falseautoHideOn?: AutoHideOn // 自动隐藏时机，默认 'DOMContentLoaded'callbacks?: LoadingCallbacks // 生命周期回调}

// 基本使用loadingManager()// 自动拦截 fetchloadingManager({ autoBind: 'fetch' })// 白屏 Loading（SPA 场景）loadingManager({defaultVisible: true,autoHideOn: 'manual'})// 在应用入口：window.__LOADING_MANAGER__.hide()// 自定义样式 + 防抖loadingManager({style: {overlayColor: 'rgba(0, 0, 0, 0.5)',spinnerColor: '#ff6b6b',backdropBlur: true},debounceHide: { enabled: true, duration: 100 }})

const lm = window.__LOADING_MANAGER__lm.show('加载中...') // 显示lm.hide() // 隐藏lm.forceHide() // 强制隐藏lm.updateText('正在处理...') // 更新文本lm.isVisible() // 检查状态lm.getPendingCount() // 挂起请求数lm.destroy() // 销毁

interface VersionUpdateCheckerOptions extends BasePluginOptions {versionSource?: 'define' | 'file' | 'auto' // 版本来源，默认 'auto'defineName?: string // 全局变量名，默认 '__APP_VERSION__'checkUrl?: string // 检查 URL，默认 '/version.json'checkInterval?: number // 检查间隔（ms），默认 300000checkOnVisibilityChange?: boolean // 可见性检查，默认 trueenableInDev?: boolean // 开发模式启用，默认 falsepromptStyle?: 'modal' | 'banner' | 'toast' // 提示样式，默认 'modal'promptMessage?: string // 提示消息refreshButtonText?: string // 刷新按钮文本dismissButtonText?: string // 忽略按钮文本customPromptTemplate?: string // 自定义模板customStyle?: string // 自定义样式onUpdateAvailable?: string // 发现新版本回调onRefresh?: string // 刷新回调onDismiss?: string // 忽略回调}

// 配合 generateVersion 使用;(generateVersion({format: 'datetime',outputType: 'both',defineName: '__APP_VERSION__'}),versionUpdateChecker())// 自定义检查间隔和提示versionUpdateChecker({checkInterval: 60000,promptStyle: 'banner',onUpdateAvailable: 'console.log("新版本:", newVersion); return true;'})

import { compressAssets, imageOptimizer, bundleAnalyzer } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [compressAssets({ algorithm: 'both' }), imageOptimizer({ convertToWebp: { png: true, jpeg: true } }), bundleAnalyzer({ outputFormat: 'html', openAnalyzer: true })]})

import { generateVersion, versionUpdateChecker } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [generateVersion({ format: 'datetime', outputType: 'both' }), versionUpdateChecker({ checkInterval: 60000 })]})

import { autoImport, buildProgress, loadingManager } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [buildProgress({ format: 'spinner' }), autoImport({ imports: { vue: ['ref', 'reactive', 'computed'] }, vueTemplate: true }), loadingManager({ defaultVisible: true, autoHideOn: 'manual' })]})

import { envGuard, assetManifest, htmlInject } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [envGuard({required: { VITE_API_URL: { type: 'url', required: true } },failAction: 'error'}),assetManifest({ outputFormat: 'vite', injectRuntime: true }),htmlInject({rules: [{ content: '<meta name="description" content="My App">', position: 'head-end' }]})]})