更新记录

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 形式

配置选项变更：

通配符用法：

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 } }
    }
}

新增配置选项：

Common 工具模块（增强）

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

common/format（增强）：

common/fs（增强）：

common/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 新增导出：parseTemplate、formatDate
• @meng-xi/vite-plugin/common/fs 新增导出：writeFileSyncSafely、shouldUpdateFileContent
• @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 之后）两种位置

配置选项：

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

平台兼容性

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: ['*'] },
            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()
    ]
})

内置插件

插件开发框架

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

子路径导出

License

MIT