更新记录

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 之后）两种位置

配置选项：

ImportMapping 类型：

ResolvedImport 类型：

ScannedModule 类型：

TransformResult 类型：

Common 工具模块（精简）

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

• 移除 @common/compress — calculateGzipSize 仅在 bundleAnalyzer 中使用，已内联
• 移除 @common/object — deepMerge 仅在 loadingManager 中使用，已内联
• 移除 @common/path — isNodeModule 仅在 bundleAnalyzer 中使用，已内联

保留的 6 个模块：

子路径导出（变更）

• 新增 @meng-xi/vite-plugin/plugins/auto-import 子路径导出
• 新增导出函数：autoImport
• 新增导出类型：AutoImportOptions、ImportMapping、ResolvedImport、ScannedModule、TransformResult
• 移除 @meng-xi/vite-plugin/common/compress 子路径导出
• 移除 @meng-xi/vite-plugin/common/object 子路径导出
• 移除 @meng-xi/vite-plugin/common/path 子路径导出
• @meng-xi/vite-plugin/common 移除导出：calculateGzipSize、deepMerge、isNodeModule、SPINNER_FRAMES、stripAnsi、escapeHtmlAttr、getExtension、padNumber、generateRandomHash、formatDate、parseTemplate、toCamelCase、toPascalCase、stripJsonComments 及相关类型

0.1.4（2026-06-03） 下载此版本

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

envGuard（新增）

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

功能特性：

• 多类型校验：string、number、url、boolean、enum、json、semver、path
• 范围验证：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 在终端输出通过/缺失/失败统计

配置选项：

EnvFieldRule 类型：

EnvValidationResult 类型：

EnvGuardResult 类型：

@common/ui（新增模块）

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

• ANSI — ANSI 转义码工具集，包含光标控制（reset、clearLine、hideCursor、showCursor）和彩色文本包装（green、cyan、gray、bold、red、yellow、magenta）
• 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 新增导出类型：EnvGuardOptions、EnvGuardResult、EnvFailAction、RuntimeGuardMode
• @meng-xi/vite-plugin/plugins 新增导出函数：envGuard
• @meng-xi/vite-plugin/common/ui 新增子路径导出，包含 ANSI、SPINNER_FRAMES、stripAnsi
• @meng-xi/vite-plugin/common 新增导出：ANSI、SPINNER_FRAMES、stripAnsi、EnvType、EnvFieldRule、EnvValidationResult、STRING_LIKE_TYPES、validateType、validateRange、validateLength、validateValue、validateEnvironment

0.1.3（2026-06-01） 下载此版本

新增 bundleAnalyzer 构建产物体积分析插件，新增 @common/compress 和 @common/path 工具模块，@common/format 和 @common/fs 新增通用函数

bundleAnalyzer（新增）

构建产物体积分析插件，在 Vite 构建（writeBundle）完成后自动扫描输出目录，分析构建产物的体积分布、模块依赖、文件类型统计等关键指标，生成 JSON 报告和/或包含可视化图表的 HTML 报告，支持体积阈值告警和与上次构建的对比分析。enforce: 'post'。

功能特性：

• 多格式报告输出：json（JSON 格式）、html（含可视化图表的 HTML）、both（同时生成两种）
• 体积分析：计算原始大小和 gzip 压缩大小，使用最高压缩级别（level: 9）
• 阈值告警：超过 sizeThreshold 的 chunk 自动产生告警，超过 2 倍阈值标记为 critical
• 构建对比：与历史报告对比体积变化趋势，显示增大、减小、新增、移除的模块
• 可视化图表：HTML 报告支持 treemap（树状图）、sunburst（旭日图）和 list（列表）三种视图
• 模块排行：Top N 大模块排行，区分源码和 node_modules
• 文件类型分布：按扩展名统计体积占比
• 自动打开：openAnalyzer 支持跨平台自动在浏览器中打开 HTML 报告
• 分析摘要日志：构建完成后输出 chunk 数量、总体积、gzip 体积、Top 5 模块

配置选项：

BundleAnalysisResult 类型：

ChunkStats 类型：

ModuleStats 类型：

FileTypeDistribution 类型：

SizeWarning 类型：

ComparisonDiff 类型：

@common/compress（新增模块）

• calculateGzipSize(data) — 计算给定数据的 gzip 压缩后大小（异步），使用最高压缩级别（level: 9），用于估算网络传输体积。参数 data 支持 Buffer 和 string 类型

@common/path（新增模块）

• isNodeModule(moduleId) — 判断模块 ID 是否来自 node_modules。检测规则：路径包含 node_modules、以 \0 开头（Rollup 内部虚拟模块）、以 virtual: 开头（虚拟模块前缀）

@common/format（增强）

新增以下工具函数：

• escapeHtmlAttr(str) — 转义 HTML 属性值中的特殊字符，防止 XSS 注入。将 &、"、<、> 分别转义为 &、"、<、>
• formatFileSize(bytes) — 将字节数格式化为人类可读的文件大小字符串。小于 1KB 显示 xB，小于 1MB 显示 x.xKB，大于等于 1MB 显示 x.xxMB
• getExtension(filePath) — 获取文件扩展名，返回小写的扩展名（含点号，如 .js）

@common/fs（增强）

新增以下工具函数和类型：

• scanDirectory(dirPath, options?) — 递归扫描目录，收集所有文件信息，支持按扩展名（includeExtensions）、路径模式（excludePatterns）和自定义过滤函数（filter）进行过滤
• writeJsonReport(filePath, data, indent?) — 将数据对象序列化为 JSON 格式并写入文件，默认缩进 2 个空格
• ScannedFile 类型 — 扫描文件信息接口，包含 filePath、size、extension 字段
• ScanDirectoryOptions 类型 — 目录扫描选项接口，包含 includeExtensions、excludePatterns、filter 字段

子路径导出（增强）

• @meng-xi/vite-plugin/plugins 新增导出类型：BundleAnalyzerOptions、BundleAnalysisResult、BundleOutputFormat、ChunkStats、ModuleStats、FileTypeDistribution、SizeWarning、ComparisonDiff
• @meng-xi/vite-plugin/plugins 新增导出函数：bundleAnalyzer
• @meng-xi/vite-plugin/common/compress 新增子路径导出，包含 calculateGzipSize
• @meng-xi/vite-plugin/common/path 新增子路径导出，包含 isNodeModule
• @meng-xi/vite-plugin/common 新增导出函数：calculateGzipSize、isNodeModule、escapeHtmlAttr、formatFileSize、getExtension、scanDirectory、writeJsonReport
• @meng-xi/vite-plugin/common 新增导出类型：ScannedFile、ScanDirectoryOptions

平台兼容性

uni-app(3.7.9)

uni-app x(3.7.9)

其他

@meng-xi/vite-plugin

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: ['ref', 'reactive', 'computed'] },
            dts: 'auto-imports.d.ts',
            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(),
        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()
    ]
})

内置插件

插件开发框架

本包导出完整的插件开发框架，帮助快速构建符合规范的自定义 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：

Common 工具模块

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

import { formatFileSize } from './uni_modules/vite-plugin/js_sdk/common/format/index.mjs'
import { scanDirectory } from './uni_modules/vite-plugin/js_sdk/common/fs/index.mjs'
import { injectBeforeTag } from './uni_modules/vite-plugin/js_sdk/common/html/index.mjs'

子路径导出

License

MIT