@meng-xi/vite-plugin v0.1.0：开发者升级指南

版本：0.1.0 | 协议：MIT | 依赖：Vite ^5.0.0 || ^6.0.0 || ^7.0.0 

写在前面

如果你正在使用 @meng-xi/vite-plugin@0.0.9，这篇文章将告诉你：v0.1.0 变了什么、为什么变、以及你需要做什么。如果你是第一次接触这个库，这篇文章将从你日常开发中遇到的真实问题出发，展示每个插件如何精准解决它们。

一、v0.0.9 → v0.1.0 迁移指南

1.1 Breaking Changes

只有两处需要修改，改动量极小：

配置项完全兼容，无需修改任何 options。

// v0.0.9 import { injectIco, injectLoading } from '@meng-xi/vite-plugin' // v0.1.0 import { faviconManager, loadingManager } from '@meng-xi/vite-plugin'

1.2 新增能力一览

二、从问题出发：七个真实开发痛点

痛点 1：用户永远不知道应用更新了

场景：你刚修复了一个关键 Bug 并部署上线，但用户浏览器缓存了旧版本，持续使用有问题的代码。你发公告、推通知，用户还是无动于衷。

解法：versionUpdateChecker+ generateVersion

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

工作原理：

构建时 generateVersion → 生成 version.json + 注入 __APP_VERSION__ 运行时 versionUpdateChecker → 定期请求 version.json → 对比版本 → 提示刷新

用户从其他标签页切回时，会立即触发一次检查，不等待定时周期。三种提示样式（modal/banner/toast）覆盖不同紧急程度。

痛点 2：白屏时间太长，用户以为页面挂了

场景：SPA 应用首屏加载慢，用户看到空白页面，以为网站崩溃直接关闭。

解法：loadingManager

import { loadingManager } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded', spinnerType: 'pulse' }) ] })

关键设计：defaultVisible: true时，CSS 和 HTML 直接注入到 ＜head＞ 中，浏览器解析到 ＜head＞ 就渲染 loading，无需等待 JS 执行。defaultVisible: false时，所有代码通过 IIFE 动态注入，避免多余 DOM。

痛点 3：图标管理零散又容易遗漏

场景：favicon.ico、apple-touch-icon.png、android-chrome-192x192.png……不同设备不同尺寸，手动管理极易遗漏。

解法：faviconManager

import { faviconManager } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ faviconManager({ base: '/', icons: [ { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }, { rel: 'apple-touch-icon', href: '/apple-touch-icon.png', sizes: '180x180' } ] }) ] })

双模式注入：配置 icons数组时使用 Vite 原生 HtmlTagDescriptorAPI；配置 link字段时使用字符串替换，满足自定义需求。

痛点 4：构建过程像黑盒，不知道还要等多久

场景：大型项目构建耗时数分钟，终端只显示 building...，不知道进度，不知道是否卡死。

解法：buildProgress

import { buildProgress } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [buildProgress({ format: 'bar' })] })

终端实时显示进度条，构建过程可视化。

痛点 5：静态资源复制效率低

场景：每次构建都全量复制静态资源，即使文件没有变化。大型项目资源文件多，构建时间被拖慢。

解法：copyFile

import { copyFile } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ copyFile({ targets: [{ src: 'public/static', dest: 'dist/static' }] }) ] })

增量复制 + 并发控制，只复制变化的文件。

痛点 6：uni-app 路由配置手动维护容易出错

场景：每次新增页面都要手动修改 pages.json，遗漏配置导致路由失效。

解法：generateRouter

import { generateRouter } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ generateRouter({ pagesJsonPath: 'src/pages.json', preserveRouteChanges: true }) ] })

自动扫描页面目录，生成路由配置。

痛点 7：版本号管理混乱

场景：每次发版手动改 package.json 的 version，容易忘记，也无法在运行时获取。

解法：generateVersion

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

支持 timestamp、datetime、hash、semver四种格式，构建时自动生成并注入。

三、安全设计深度解读

v0.1.0 新增的 common/script模块不仅是工具函数，更是一套系统化的安全防护体系。所有涉及用户输入字符串的场景都经过严格校验。

3.1 三层防护模型

用户输入字符串 │ ▼ ┌─────────────────────────────────┐ │ 第一层：XSS 防护 │ │ containsScriptTag() │ │ 检测并拒绝 ＜script＞ 标签注入 │ ├─────────────────────────────────┤ │ 第二层：原型污染防护 │ │ validateIdentifierName() │ │ 拒绝 __proto__、constructor 等 │ ├─────────────────────────────────┤ │ 第三层：运行时安全包装 │ │ makeCallback() │ │ try-catch 包裹，异常不影响主流程 │ └─────────────────────────────────┘

3.2 为什么需要这些防护？

versionUpdateChecker和 loadingManager都接受用户提供的字符串作为运行时代码（回调函数体、自定义模板）。这些字符串在构建时被嵌入到生成的 JS 中，如果包含恶意代码，会在用户浏览器中执行。

// 危险：用户传入包含 script 标签的模板 versionUpdateChecker({ customPromptTemplate: '＜script＞alert("xss")＜/script＞＜div＞更新提示＜/div＞' // → 构建时抛出错误，拒绝此配置 }) // 危险：用户传入 __proto__ 作为全局变量名 versionUpdateChecker({ defineName: '__proto__' // → 构建时抛出错误，拒绝此配置 })

3.3 makeCallback 的设计哲学

Vite 插件在构建时生成运行时代码，无法传递函数引用。makeCallback接受函数体字符串，包装为完整函数并自动添加 try-catch：

// 输入 makeCallback('console.log("版本:", newVersion); return true;', 'onUpdateAvailable', 'newVersion') // 输出 function(newVersion) { try { console.log("版本:", newVersion); return true; } catch(e) { console.error('[onUpdateAvailable] error:', e); } }

即使回调代码抛出异常，也不会影响版本检测的主流程。

四、架构演进：从 v0.0.9 到 v0.1.0

4.1 v0.0.9 的架构问题

v0.0.9 的六个插件各自为战，存在三个结构性问题：

1.代码重复：injectIco和 injectLoading各自实现了 HTML 注入逻辑

2.命名不当：injectIco不只是注入图标，还负责文件复制和格式管理

3.安全缺失：用户输入的字符串没有统一校验机制

4.2 v0.1.0 的架构重组

v0.0.9 v0.1.0 ┌──────────────┐ ┌─────────────────────────────────┐ │ 6 个独立插件 │ │ 应用层（7 个内置插件） │ │ 各自实现注入 │ ──→ │ + versionUpdateChecker（新增） │ │ 各自处理校验 │ ├─────────────────────────────────┤ │ 无公共抽象 │ │ 框架层 │ └──────────────┘ │ BasePlugin · Validator · Logger │ ├─────────────────────────────────┤ │ 工具层（v0.1.0 新增 html/script）│ │ 消除重复，统一安全校验 │ └─────────────────────────────────┘

4.3 工具层详解

injectBeforeTag和 injectHtmlByPriority两个函数统一了 HTML 注入方式，并引入了优雅降级机制——当 ＜/head＞ 不存在时，自动降级到 ＜/body＞ 甚至文件末尾。

五、versionUpdateChecker 配置全解

5.1 最小配置

versionUpdateChecker()

所有选项都有合理默认值，零配置即可工作。默认使用 auto模式，5 分钟检查一次，modal 弹窗提示。

5.2 完整配置

versionUpdateChecker({ // 版本来源 versionSource: 'auto', // 'define' | 'file' | 'auto' defineName: '__APP_VERSION__', // define 模式的全局变量名 checkUrl: '/version.json', // file 模式的版本文件路径 // 检测策略 checkInterval: 300000, // 检查间隔（毫秒），默认 5 分钟 checkOnVisibilityChange: true, // 标签页切回时立即检查 enableInDev: false, // 开发环境是否启用 // 提示样式 promptStyle: 'modal', // 'modal' | 'banner' | 'toast' promptMessage: '发现新版本，是否立即刷新获取最新内容？', refreshButtonText: '立即刷新', dismissButtonText: '稍后再说', // 自定义 UI customPromptTemplate: undefined, // 自定义提示 HTML 模板 customStyle: undefined, // 自定义 CSS // 回调 onUpdateAvailable: undefined, // 发现新版本时的回调（函数体字符串） onRefresh: undefined, // 用户选择刷新时的回调 onDismiss: undefined // 用户选择忽略时的回调 })

5.3 版本来源选择指南

5.4 提示样式选择指南

六、自定义插件开发实战

v0.1.0 的框架层已足够稳定，你可以基于 BasePlugin构建自有插件。以下是一个完整的自定义插件示例——在 HTML 中注入自定义代码片段：

import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory' import { injectBeforeTag, makeCallback } from '@meng-xi/vite-plugin/common' import type { Plugin } from 'vite' interface InjectSnippetOptions { targetTag: string // 在哪个标签前注入 snippet: string // 注入的代码内容 onInjected?: string // 注入成功后的回调（函数体字符串） } class InjectSnippetPlugin extends BasePlugin＜InjectSnippetOptions＞ { protected getPluginName(): string { return 'inject-snippet' } protected getDefaultOptions() { return { targetTag: '＜/body＞' } } protected validateOptions() { this.validator .field('targetTag').required().string() .field('snippet').required().string() .validate() } protected addPluginHooks(plugin: Plugin): void { plugin.transformIndexHtml = { order: 'post', handler: (html: string) =＞ { const result = injectBeforeTag(html, this.options.targetTag, this.options.snippet) if (result.injected) { this.logger.success('代码注入成功') if (this.options.onInjected) { const fn = makeCallback(this.options.onInjected, 'inject-snippet') fn() } return result.html } this.logger.warn('未找到目标标签，注入失败') return html } } } } export const injectSnippet = createPluginFactory(InjectSnippetPlugin)

你自动获得的能力：

·Validator：配置项自动校验，类型安全

·Logger：统一日志格式，带插件名前缀

·BasePlugin：标准化的插件生命周期管理

·common/*：复用所有工具函数，无需重复实现

七、场景化配置模板

7.1 Web 应用标准配置

import { buildProgress, faviconManager, generateVersion, loadingManager, versionUpdateChecker } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ buildProgress({ format: 'bar' }), faviconManager({ base: '/', icons: [ { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }, { rel: 'apple-touch-icon', href: '/apple-touch-icon.png', sizes: '180x180' } ] }), generateVersion({ format: 'datetime', outputType: 'both' }), loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded', spinnerType: 'pulse' }), versionUpdateChecker({ checkInterval: 300000, promptStyle: 'modal', checkOnVisibilityChange: true }) ] })

7.2 uni-app 工程化配置

import { buildProgress, generateRouter, generateVersion, loadingManager } from '@meng-xi/vite-plugin' export default defineConfig({ plugins: [ buildProgress({ format: 'bar' }), generateRouter({ pagesJsonPath: 'src/pages.json', preserveRouteChanges: true, metaMapping: { navigationBarTitleText: 'title', requireAuth: 'requireAuth' } }), generateVersion({ format: 'datetime', outputType: 'both' }), loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded', autoBind: 'all', requestFilter: { excludeUrlPrefixes: ['/static/'] } }) ] })

7.3 最小化配置（只需版本检测）

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

九、路线图

短期

·插件配置预设（web-app、uni-app、ssr）

·插件间事件总线

·versionUpdateChecker更多内置 UI 样式

中期

·社区插件市场

·可视化配置生成器

·构建性能分析

长期

成为 Vite 插件开发的标准框架——定义最佳实践，让社区以统一方式构建、分享和组合插件。

本文基于 @meng-xi/vite-plugin@0.1.0版本撰写，所有代码示例均来自实际源码。