更新记录

0.1.6(2026-06-07) 下载此版本

autoImport 支持通配符自动导入,generateRouter 新增路由类型声明生成,Common 工具模块新增多项通用函数,插件代码规范化重构

autoImport(增强)

自动导入插件新增通配符 '*' 支持,可自动导入模块的所有命名导出,无需逐一列举。修复了开发模式下与 uni-app 插件的协同问题,修正了默认文件过滤规则。

新增功能

  • 通配符导入imports 配置支持 '*' 通配符,自动解析模块的所有命名导出。解析策略优先从 .d.ts 类型声明文件提取导出(最准确),回退到运行时入口文件解析
  • Vue SFC 注入:新增 injectIntoScriptSetup 函数,将 import 语句注入到 <script setup> 块内部,解决 enforce: 'pre' 时与 Vue SFC 编译器的协同问题

修复

  • 修复 transform 钩子 enforce: 'post' 导致裸模块标识符无法解析的问题,改回 enforce: 'pre'
  • 修复默认 fileFilter 未排除 node_modules,导致库文件被错误处理并注入错误的 import 语句
  • 修复 resolveWildcardExports 解析 vue 模块时走了运行时入口(仅含 export { compile }),导致 vue: ['*'] 只解析出 compile 一个导出
  • 修复 for (const [mod, items] of moduleMap)items 变量声明后未使用的问题
  • 修复 makeCallback 返回的匿名函数作为函数声明调用时的语法错误,改用 IIFE 形式

配置选项变更

选项 变更前默认值 变更后默认值 说明
imports - - 新增支持 '*' 通配符格式
fileFilter /\.(vue\|jsx\|tsx\|ts\|js\|mjs)$/ /^(?!.*node_modules).*\.(vue\|jsx\|tsx\|ts\|js\|mjs)$/ 默认排除 node_modules 中的文件

通配符用法

autoImport({
    imports: {
        vue: ['*'], // 自动导入 vue 的所有命名导出
        'vue-router': ['*'] // 自动导入 vue-router 的所有命名导出
    }
})

generateRouter(增强)

路由生成插件新增 TypeScript 类型声明文件生成功能,为 @meng-xi/uni-router 模块扩展 RouteNameMap 接口,实现类型安全的路由导航。

新增功能

  • 路由类型声明生成:新增 dts 选项,控制是否生成 router.d.ts 类型声明文件
    • false:不生成类型声明文件(默认)
    • true:使用默认路径 src/router.d.ts
    • string:在指定路径生成类型声明文件
  • 生成的类型声明包含 TSDoc 注释(页面标题)和完整的元信息类型映射

生成的类型声明示例

import '@meng-xi/uni-router'

declare module '@meng-xi/uni-router' {
    interface RouteNameMap {
        /** 首页 */
        pagesIndexIndex: { path: '/pages/index/index'; meta: { title: string; isTab: true } }
        /** 个人中心 */
        pagesUserProfile: { path: '/pages/user/profile'; meta: { title: string; requireAuth: true } }
    }
}

新增配置选项

选项 类型 默认值 描述
dts string | boolean false 路由类型声明文件输出路径,true 使用默认路径

Common 工具模块(增强)

新增多项通用函数,提升工具模块的实用性:

common/format(增强)

新增函数 描述
parseTemplate 替换模板字符串中的 {{key}} 占位符,键名特殊字符自动转义,值中 $ 安全处理
formatDate 使用 {YYYY}{MM} 等占位符格式化日期字符串

common/fs(增强)

新增函数 描述
writeFileSyncSafely 同步写入文件,自动创建不存在的目录,适用于 transform 等同步钩子
shouldUpdateFileContent 对比文件内容是否需要更新,减少不必要的文件 IO 操作

common/html(增强)

新增函数 描述
escapeHtmlAttr 转义 HTML 属性值中的特殊字符(&"'<>),防止属性注入攻击

插件代码规范化重构

按照 autoImport/common 目录规范,将各插件中不属于插件核心逻辑的函数、常量等提取到 common/ 子目录,通过 common/index.ts 聚合导出:

  • buildProgress/common — 提取常量和工具函数
  • generateRouter/common — 提取路由工具函数和类型声明生成逻辑(dts.ts
  • envGuard/common — 提取运行时守卫、模板生成、校验逻辑
  • faviconManager/common — 提取类型定义
  • htmlInject/common — 提取代码生成器和校验器
  • loadingManager/common — 提取常量、函数体生成器、代码生成器和校验器
  • versionUpdateChecker/common — 提取代码生成器和校验器

子路径导出(变更)

  • @meng-xi/vite-plugin/common/format 新增导出:parseTemplateformatDate
  • @meng-xi/vite-plugin/common/fs 新增导出:writeFileSyncSafelyshouldUpdateFileContent
  • @meng-xi/vite-plugin/common/html 新增导出:escapeHtmlAttr

0.1.5(2026-06-06) 下载此版本

新增 autoImport 自动导入插件,精简 Common 工具模块(移除 compress、object、path),修复 dts 类型声明文件在开发模式下不生成的问题

autoImport(新增)

自动导入插件,在 Vite 构建过程中自动检测代码中使用的标识符,并将对应的 import 语句注入到文件顶部,无需手动编写 import 声明。enforce: 'post'

功能特性

  • 预设映射:通过 imports 配置常用库的自动导入规则,支持简写格式(Record<string, string[]>)和完整格式(ImportMapping[],支持默认导入)
  • 目录扫描:通过 dirs 配置自动扫描指定目录下的模块导出,递归扫描子目录,跳过 node_modules 和隐藏目录
  • Vue 模板支持:vueTemplate 开启后,Vue SFC <template> 中使用的 API 也会被自动导入
  • 类型声明生成:dts 选项自动生成 .d.ts 类型声明文件,提供 IDE 类型提示
  • 标识符忽略:ignore 选项排除不需要自动导入的标识符
  • 文件过滤:fileFilter 正则控制需要处理的文件范围
  • 注入位置:injectAtPosition 支持 'top'(文件顶部)和 'after-last-import'(最后一个 import 之后)两种位置

配置选项

选项 类型 默认值 描述
imports Record<string, string[]> | ImportMapping[] | Array<...> {} 导入映射配置
dirs string[] [] 需要扫描的目录列表
dts string | boolean 'auto-imports.d.ts' 类型声明文件输出路径,false 不生成
vueTemplate boolean false 是否为 Vue 模板启用自动导入
ignore string[] [] 需要忽略的标识符列表
fileFilter RegExp /\.(vue\|jsx\|tsx\|ts\|js\|mjs)$/ 文件过滤正则表达式
injectAtPosition 'top' | 'after-last-import' 'top' import 语句注入位置

ImportMapping 类型

属性 类型 描述
module string 模块路径
names string[] 要导入的名称列表
defaultImport boolean 是否为默认导入,默认 false

ResolvedImport 类型

属性 类型 描述
module string 模块路径
name string 导入标识符名称
isDefault boolean 是否为默认导入

ScannedModule 类型

属性 类型 描述
filePath string 模块文件的绝对路径
exports string[] 命名导出名称列表
defaultExport string | null 默认导出名称,无则为 null

TransformResult 类型

属性 类型 描述
code string 转换后的代码字符串
map any Source map 信息(可选)

Common 工具模块(精简)

移除使用次数不足 2 次的工具模块,仅保留在多处被复用的核心工具:

  • 移除 @common/compresscalculateGzipSize 仅在 bundleAnalyzer 中使用,已内联
  • 移除 @common/objectdeepMerge 仅在 loadingManager 中使用,已内联
  • 移除 @common/pathisNodeModule 仅在 bundleAnalyzer 中使用,已内联

保留的 6 个模块:

子路径 描述 导出内容
common/format 格式化工具 getDateFormatParamsformatFileSizeDateFormatOptions
common/fs 文件系统工具 checkSourceExistscopySourceToTargetwriteFileContentscanDirectorywriteJsonReport 及相关类型
common/html HTML 注入工具 injectBeforeTaginjectHeadAndBodysanitizeContent 及相关类型
common/script 脚本生成工具 makeCallback
common/ui 终端 UI 工具 ANSI
common/validation 参数验证工具 ValidatorvalidateGlobalNamevalidateNoScriptInTemplatevalidateCallbackFields

子路径导出(变更)

  • 新增 @meng-xi/vite-plugin/plugins/auto-import 子路径导出
  • 新增导出函数:autoImport
  • 新增导出类型:AutoImportOptionsImportMappingResolvedImportScannedModuleTransformResult
  • 移除 @meng-xi/vite-plugin/common/compress 子路径导出
  • 移除 @meng-xi/vite-plugin/common/object 子路径导出
  • 移除 @meng-xi/vite-plugin/common/path 子路径导出
  • @meng-xi/vite-plugin/common 移除导出:calculateGzipSizedeepMergeisNodeModuleSPINNER_FRAMESstripAnsiescapeHtmlAttrgetExtensionpadNumbergenerateRandomHashformatDateparseTemplatetoCamelCasetoPascalCasestripJsonComments 及相关类型

0.1.4(2026-06-03) 下载此版本

新增 envGuard 环境变量校验插件,新增 @common/ui 终端 UI 工具模块

envGuard(新增)

环境变量校验插件,在 Vite 构建前校验环境变量的存在性和合法性,支持多种值类型校验、正则匹配、自定义校验函数、范围约束和长度约束,可选生成 .env 模板文件和注入运行时守卫代码。enforce: 'post'(运行时守卫注入)。

功能特性

  • 多类型校验:stringnumberurlbooleanenumjsonsemverpath
  • 范围验证:minValue / maxValue 数值范围约束(number 类型)
  • 长度验证:minLength / maxLength 字符串长度约束(字符串类类型)
  • 正则匹配:pattern 正则表达式校验
  • 自定义校验:validator 函数,返回 true 或错误消息字符串
  • 失败处理:failAction 支持 error(中断构建)、warn(警告继续)、ignore(静默忽略)
  • .env 模板生成:generateTemplate 自动生成含注释、分组、敏感标记的模板文件
  • 运行时守卫:runtimeGuard 注入 JavaScript 代码到 HTML,支持 console(控制台警告)、throw(抛出错误)、overlay(页面横幅)三种模式
  • 自动加载 .env:autoLoadEnv 按配置路径自动加载环境变量到 process.env
  • 校验报告:reportOutput 生成 JSON 格式的校验结果报告
  • 校验摘要:showSummary 在终端输出通过/缺失/失败统计

配置选项

选项 类型 默认值 描述
required Record<string, EnvFieldRule> {} 环境变量校验规则映射
failAction 'error' | 'warn' | 'ignore' 'error' 校验失败时的处理动作
generateTemplate boolean true 是否自动生成 .env 模板文件
templateOutput string '.env.template' .env 模板文件的输出路径
runtimeGuard boolean false 是否注入运行时环境变量守卫代码
runtimeGlobalName string '__ENV_GUARD__' 运行时守卫的全局变量名
runtimeGuardMode 'console' | 'throw' | 'overlay' 'console' 运行时守卫的行为模式
envFiles string[] ['.env', '.env.local', '.env.production', '.env.development'] 需要加载的 .env 文件路径列表
autoLoadEnv boolean true 是否自动加载 .env 文件到 process.env
reportOutput string | false false 校验报告输出路径,false 不生成
validateBeforeBuild boolean true 是否在构建前执行校验
showSummary boolean true 是否输出校验摘要日志

EnvFieldRule 类型

属性 类型 描述
type EnvType 值类型,默认 'string'
required boolean 是否为必需字段,默认 true
pattern RegExp 正则表达式,值必须匹配此模式
validator (value: string) => boolean \| string 自定义验证函数
message string 自定义错误消息
default string 当值为空时使用的默认值
enumValues string[] 枚举值列表(仅 enum 类型)
minValue number 数值最小值(仅 number 类型)
maxValue number 数值最大值(仅 number 类型)
minLength number 字符串最小长度(仅字符串类类型)
maxLength number 字符串最大长度(仅字符串类类型)
group string 变量分组名称,用于模板生成时的分组显示
description string 变量描述信息,用于模板生成时的说明文本
sensitive boolean 是否为敏感变量,模板中会隐藏实际值

EnvValidationResult 类型

属性 类型 描述
key string 环境变量名
status 'pass' | 'missing' | 'type_error' | 'custom_error' | 'enum_mismatch' | 'range_error' | 'length_error' 验证状态
message string 验证消息
value string | undefined 环境变量的有效值
rule EnvFieldRule 应用的校验规则

EnvGuardResult 类型

属性 类型 描述
timestamp string 校验时间戳(ISO 格式)
total number 校验的环境变量总数
passed number 校验通过的变量数量
missing number 缺失的必需变量数量
invalid number 校验失败的变量数量
results EnvValidationResult[] 所有变量的详细校验结果列表
allPassed boolean 是否所有变量均校验通过

@common/ui(新增模块)

终端 UI 工具模块,提供 ANSI 转义码处理、Spinner 动画帧和字符串清理等工具函数。

  • ANSI — ANSI 转义码工具集,包含光标控制(resetclearLinehideCursorshowCursor)和彩色文本包装(greencyangrayboldredyellowmagenta
  • SPINNER_FRAMES — Spinner 动画帧序列,Windows 平台使用 ASCII 字符 |///-/\,其他平台使用 Unicode Braille 字符 -
  • stripAnsi(str) — 移除字符串中的所有 ANSI 转义码,用于计算文本实际显示宽度或将彩色输出转为纯文本

@common/validation(增强)

新增环境变量验证相关类型和函数:

  • EnvType 类型 — 环境变量值类型,支持 'string' | 'number' | 'url' | 'boolean' | 'enum' | 'json' | 'semver' | 'path'
  • EnvFieldRule 接口 — 环境变量字段校验规则,包含类型约束、范围限制、自定义验证函数和元数据信息
  • EnvValidationResult 接口 — 环境变量验证结果,包含验证状态、错误消息和有效值
  • STRING_LIKE_TYPES 常量 — 字符串类类型集合,用于长度验证时判断是否需要检查 minLength/maxLength
  • validateType(value, rule) — 验证环境变量值的类型
  • validateRange(value, rule) — 验证数值范围(仅 number 类型)
  • validateLength(value, rule) — 验证字符串长度(仅字符串类类型)
  • validateValue(key, value, rule) — 验证单个环境变量值(按顺序执行缺失检查、类型验证、范围验证、长度验证、正则验证、自定义验证)
  • validateEnvironment(env, rules) — 批量验证环境变量

子路径导出(增强)

  • @meng-xi/vite-plugin/plugins 新增导出类型:EnvGuardOptionsEnvGuardResultEnvFailActionRuntimeGuardMode
  • @meng-xi/vite-plugin/plugins 新增导出函数:envGuard
  • @meng-xi/vite-plugin/common/ui 新增子路径导出,包含 ANSISPINNER_FRAMESstripAnsi
  • @meng-xi/vite-plugin/common 新增导出:ANSISPINNER_FRAMESstripAnsiEnvTypeEnvFieldRuleEnvValidationResultSTRING_LIKE_TYPESvalidateTypevalidateRangevalidateLengthvalidateValuevalidateEnvironment
查看更多

平台兼容性

uni-app(3.7.9)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟

uni-app x(3.7.9)

Chrome Safari Android iOS 鸿蒙 微信小程序

其他

多语言 暗黑模式 宽屏模式

@meng-xi/vite-plugin

license npm npm

Vite 实用插件集与插件开发框架(uni-app 版本)。


特性

  • 开箱即用 - 12 个实用插件,覆盖构建进度、产物分析与压缩、文件复制、环境变量校验、路由生成、版本管理、HTML 注入、图标管理、全局 Loading、自动导入等场景
  • 插件开发框架 - 导出 BasePlugin、Logger、Validator 等核心组件,快速构建自定义 Vite 插件
  • 通用工具库 - 内置 Common 工具模块,支持按需子路径导入
  • 类型安全 - 完整 TypeScript 类型定义与配置验证器
  • uni-app 适配 - 通过 uni_modules 方式集成,无需 npm 安装

📖 完整文档:https://mengxi-studio.github.io/vite-plugin/

安装

uni_modules(推荐)

vite-plugin 目录复制到项目的 uni_modules 目录下:

src/
  └── uni_modules/
        └── vite-plugin/
              └── js_sdk/
                    └── index.mjs

npm

pnpm add @meng-xi/vite-plugin -D

npm 方式需将导入路径改为 @meng-xi/vite-plugin

快速开始

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import {
    buildProgress,
    bundleAnalyzer,
    compressAssets,
    copyFile,
    envGuard,
    generateRouter,
    generateVersion,
    htmlInject,
    faviconManager,
    loadingManager,
    versionUpdateChecker,
    autoImport
} from './uni_modules/vite-plugin/js_sdk/index.mjs'

export default defineConfig({
    plugins: [
        uni(),
        autoImport({
            imports: { vue: ['*'] },
            dts: true,
            vueTemplate: true
        }),
        buildProgress(),
        bundleAnalyzer({ outputFormat: 'json' }),
        compressAssets({ algorithm: 'both' }),
        copyFile({ sourceDir: 'src/assets', targetDir: 'dist/assets' }),
        envGuard({ required: { VITE_API_URL: { type: 'url', required: true } } }),
        generateRouter({ dts: true }),
        generateVersion({ format: 'datetime', outputType: 'both' }),
        htmlInject({ rules: [{ id: 'meta', content: '<meta name="description" content="My App">', position: 'head-end' }] }),
        faviconManager('/assets'),
        loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' }),
        versionUpdateChecker()
    ]
})

内置插件

插件 说明
autoImport 自动导入,支持预设映射、通配符('*')、目录扫描、Vue 模板自动导入和类型声明生成
buildProgress 终端实时构建进度条,支持 bar / spinner / minimal
bundleAnalyzer 构建产物体积分析,支持 JSON/HTML 报告、gzip 计算、阈值告警和构建对比
compressAssets 构建产物压缩,支持 gzip / brotli / both,并发压缩和统计报告
copyFile 构建完成后复制文件或目录,支持增量复制
envGuard 环境变量校验,支持类型检查、范围验证、自定义规则和运行时守卫
faviconManager 管理网站图标链接注入和文件复制,支持字符串简写配置
generateRouter 根据 pages.json 自动生成路由配置与类型声明(uni-app)
generateVersion 自动生成版本号,支持文件输出和全局变量注入
htmlInject HTML 内容注入,支持多种位置、选择器定位、条件注入、模板变量和安全过滤
loadingManager 全局 Loading 状态管理,支持请求拦截、防抖、过渡动画和白屏 Loading
versionUpdateChecker 运行时版本更新检查,支持多种提示样式和自定义回调

插件开发框架

本包导出完整的插件开发框架,帮助快速构建符合规范的自定义 Vite 插件。

import { BasePlugin, createPluginFactory } from './uni_modules/vite-plugin/js_sdk/index.mjs'
import type { Plugin } from 'vite'

interface MyPluginOptions {
    prefix?: string
}

class MyPlugin extends BasePlugin<MyPluginOptions> {
    protected getPluginName() {
        return 'my-plugin'
    }

    protected getDefaultOptions() {
        return { prefix: '[app]' }
    }

    protected validateOptions() {
        this.validator.field('prefix').string().notEmpty().validate()
    }

    protected addPluginHooks(plugin: Plugin) {
        plugin.writeBundle = {
            order: 'post',
            handler: async () => {
                await this.safeExecute(async () => {
                    this.logger.info('插件执行中...')
                }, '执行自定义逻辑')
            }
        }
    }
}

export const myPlugin = createPluginFactory(MyPlugin)

核心 API:

API 说明
BasePlugin 插件基类,提供配置管理、日志、错误处理和生命周期
createPluginFactory 将 BasePlugin 子类转换为 Vite 插件函数
Logger 全局单例日志管理器,为每个插件提供独立日志代理
Validator 链式配置验证器,校验插件配置参数

Common 工具模块

内置通用工具函数库,按功能模块组织,支持子路径按需导入。

import { formatFileSize, parseTemplate, formatDate } from './uni_modules/vite-plugin/js_sdk/common/format/index.mjs'
import { scanDirectory, writeFileSyncSafely, shouldUpdateFileContent } from './uni_modules/vite-plugin/js_sdk/common/fs/index.mjs'
import { injectBeforeTag, escapeHtmlAttr } from './uni_modules/vite-plugin/js_sdk/common/html/index.mjs'
子路径 描述
common/format 日期参数提取、模板变量替换 {{key}}、日期格式化 {YYYY}、文件大小格式化
common/fs 文件/目录复制、目录扫描、同步安全写入、文件变更检测
common/html HTML 标签注入、双区域注入、内容安全消毒、HTML 属性值转义
common/script 回调函数体包装为安全的函数表达式(含 try-catch)
common/ui 终端 ANSI 颜色码常量
common/validation 链式配置验证器、全局名称校验、脚本检测、回调字段校验

子路径导出

子路径 描述
./uni_modules/vite-plugin/js_sdk/index.mjs 主入口(所有插件+框架)
./uni_modules/vite-plugin/js_sdk/factory/index.mjs 插件开发框架
./uni_modules/vite-plugin/js_sdk/logger/index.mjs 日志管理器
./uni_modules/vite-plugin/js_sdk/plugins/index.mjs 所有插件
./uni_modules/vite-plugin/js_sdk/common/index.mjs 所有工具函数
./uni_modules/vite-plugin/js_sdk/common/*/index.mjs 各工具子模块
./uni_modules/vite-plugin/js_sdk/plugins/auto-import/index.mjs autoImport 插件
./uni_modules/vite-plugin/js_sdk/plugins/build-progress/index.mjs buildProgress 插件
./uni_modules/vite-plugin/js_sdk/plugins/bundle-analyzer/index.mjs bundleAnalyzer 插件
./uni_modules/vite-plugin/js_sdk/plugins/compress-assets/index.mjs compressAssets 插件
./uni_modules/vite-plugin/js_sdk/plugins/copy-file/index.mjs copyFile 插件
./uni_modules/vite-plugin/js_sdk/plugins/env-guard/index.mjs envGuard 插件
./uni_modules/vite-plugin/js_sdk/plugins/favicon-manager/index.mjs faviconManager 插件
./uni_modules/vite-plugin/js_sdk/plugins/generate-router/index.mjs generateRouter 插件
./uni_modules/vite-plugin/js_sdk/plugins/generate-version/index.mjs generateVersion 插件
./uni_modules/vite-plugin/js_sdk/plugins/html-inject/index.mjs htmlInject 插件
./uni_modules/vite-plugin/js_sdk/plugins/loading-manager/index.mjs loadingManager 插件
./uni_modules/vite-plugin/js_sdk/plugins/version-update-checker/index.mjs versionUpdateChecker 插件

License

MIT

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

MIT协议