更新记录

1.4.0（2026-08-28） 下载此版本

新增 defineUniPage 宏与页面生成架构重构：扫描页面 → pages.json → 路由配置一条流水线，配套公共 DirectoryWatcher / TaskQueue 统一监听与串行生成，插件总数增至 17 个

页面配置：defineUniPage 宏（新增）

新增 defineUniPage 宏：在 <script setup>（或 <script> 顶层）中调用，功能与 <route-config> 自定义块一致，写法更贴近 JS/TS。

使用示例：

defineUniPage({
    title: '首页',
    isTab: true,
    tab: { order: 0 }
})

<route-config> 自定义块同步增强：解析支持 JSONC 尾随逗号（与 lang="jsonc" 的 IDE 高亮语义一致）。

generatePages / generateUni（重构）

• 抽取公共 producePages() 流水线：扫描页面 + <route-config> / defineUniPage → 组装 → 合并，内存产出完整 pages 对象（不写盘）
• generatePages 直接写盘，generateUni 内存直传阶段二，消除「先写盘再读盘」的往返
• 删除 generateUni 内部重复实现，统一复用 generatePages 公共逻辑

公共模块（新增）

监听与串行化统一

• generatePages / generateUni / generateRouter 三者统一使用 TaskQueue 串行生成，避免高频变更时并发读改写竞态
• generatePages / generateUni 统一使用 DirectoryWatcher 管理页面目录监听（此前为各自私有的 fs.watch 循环）
• generateRouter 监听 pages.json 变更时同样走串行队列（此前直接 await 重新生成）

factory（增强）

• 新增 FunctionHookMap 类型：registerHook / registerOrderedHook 的钩子名泛型约束收紧为仅限函数型钩子（排除 name / enforce / apply 等非函数属性）
• 新增可重写的 getBaseDefaults() 方法，便于子类覆盖基础默认配置（enabled / verbose / errorStrategy）

细节修复

• generatePages / generateUni 的 <route-config> 虚拟模块请求匹配由 id.includes('vue') 收紧为 id.includes('?vue')，避免误拦截
• <route-config> 解析支持 JSONC 尾随逗号，与 lang="jsonc" 的 IDE 高亮语义一致

1.3.0（2026-08-26） 下载此版本

新增 generateUni 组合入口插件，一条流水线完成「扫描页面 → pages.json → 路由配置」，插件总数增至 17 个

generateUni（新增）

新增第 17 个插件：将 generatePages（扫描页面 → 生成 pages.json）与 generateRouter（基于 pages.json → 生成路由配置）编排为一条流水线，内存数据直传不重复读盘，等价于两插件连用。原有两个插件保持不变，仍可独立使用。

核心能力：

使用示例：

generateUni({
    pagesJsonPath: 'src/pages.json',
    pages: {
        pagesDir: 'src/pages',
        subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
        entryPage: 'pages/index/index',
        tabBar: { color: '#999999', selectedColor: '#42b883' }
    },
    router: {
        outputPath: 'src/router.config.ts',
        nameStrategy: 'camelCase',
        dts: 'src/router.d.ts'
    }
})

迁移：原 generatePages({...}) + generateRouter({...}) 连用等价替换为 generateUni({ pages: {...}, router: {...} })。

generatePages（增强）

为 standalone 的 generatePages 补充 <route-config> 自定义块虚拟模块拦截：注册 transform 钩子，将 xxx.vue?vue&type=route-config&index=0 请求替换为空模块，避免生产构建把块内容当作 JavaScript 解析而报错（与 generateUni 行为一致，此前仅 generateUni 具备）。

proxyManager（优化）

生产构建优化：config 钩子新增 env.command === 'build' 拦截，构建时完全跳过代理规则加载与配置生成。

背景：config 钩子在 serve 与 build 两个阶段都会执行，而代理配置与中间件仅对开发服务器有效，此前打包时会白白加载规则并输出误导性日志。

插件清单（变更）

• 插件总数由 16 增至 17，分组由 7 组不变
• generate 分组由 4 增至 5：autoImport、generateUni、generatePages、generateRouter、generateVersion

子路径导出（新增）

• @meng-xi/vite-plugin/plugins/generate/generate-uni 新增导出：generateUni 及类型 GenerateUniOptions
• @meng-xi/vite-plugin/plugins/generate 聚合导出 generateUni 及其类型

1.2.0（2026-08-25） 下载此版本

新增 generatePages 插件，扫描 Vue 文件 + <route-config> 自定义块动态生成 pages.json，插件总数增至 16 个

generatePages（新增）

新增第 16 个插件：扫描通过页面目录与页面内 <route-config> 自定义块，自动生成 / 更新 uni-app 的 pages.json 页面相关配置（pages / subPackages / tabBar），彻底解放手动配置页面。

核心能力：

route-config 自定义块：

在页面内就近声明配置（内容为 JSON，支持注释）：

<route-config>
{
  "title": "首页",
  "name": "HomePage",
  "meta": { "requireAuth": false },
  "isTab": true,
  "tab": { "text": "首页", "iconPath": "static/tab/home.png", "order": 0 }
}
</route-config>

配置选项：

类型完善：

• TabBarItemOverride 复用为 overrides 元素类型，与页面内 tab 保持一致
• 页面排序 orderMainPages 移入 helpers 目录，保持主插件文件聚焦

与 generateRouter 的关系：

generateRouter 是「读 pages.json → 生成路由配置」，generatePages 反向「扫描 Vue 文件 → 生成 pages.json」。二者可组合使用（generatePages 应置于 generateRouter 之前）。

插件清单（变更）

• 插件总数由 15 增至 16，分组由 7 组不变
• generate 分组由 3 增至 4：autoImport、generatePages、generateRouter、generateVersion

子路径导出（新增）

• @meng-xi/vite-plugin/plugins/generate/generate-pages 新增导出：generatePages 及类型 GeneratePagesOptions、RouteConfigBlock、SubPackageConfig、TabBarTemplate、TabBarItemOverride、ScannedPage
• @meng-xi/vite-plugin/plugins/generate 聚合导出 generatePages 及其关键类型

平台兼容性

uni-app(3.8.2)

uni-app x(3.8.2)

其他

@meng-xi/vite-plugin

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

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

特性

• 开箱即用 - 17 个实用插件，覆盖构建、产物、路由、版本、HTML、代理等场景
• 插件开发框架 - 导出 BasePlugin、Logger、Validator，快速构建自定义插件
• 通用工具库 - 内置 14 大 Common 工具模块，支持子路径按需导入
• uni-app 适配 - 通过 uni_modules 集成，无需 npm 安装

安装

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 {
    assetManifest,
    autoImport,
    buildProgress,
    compressAssets,
    copyFile,
    envGuard,
    faviconManager,
    generateUni,
    generateVersion,
    htmlInject,
    imageOptimizer,
    loadingManager,
    proxyManager,
    versionUpdateChecker
} from './uni_modules/vite-plugin/js_sdk/index.mjs'

export default defineConfig({
    plugins: [
        uni(),
        // 按需启用插件
        autoImport({ imports: ['vue'], vueTemplate: true }),
        generateUni({
            pages: { pagesDir: 'pages', entryPage: 'pages/index/index' },
            router: { dts: true }
        }),
        generateVersion({ format: 'datetime', outputType: 'both' }),
        envGuard({ required: { VITE_API_URL: { type: 'url', required: true } } }),
        loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' }),
        proxyManager({ rules: [{ context: '/api', target: 'https://api.example.com', changeOrigin: true }] })
    ]
})

页面配置：<route-config> 与 defineUniPage 宏

使用 generatePages / generateUni 时，页面配置可在 .vue 文件中就近声明，支持两种方式：

defineUniPage 宏（优先级更高）：在 <script setup>（或 <script> 顶层）中调用，写法更贴近 JS/TS，参数为对象字面量，支持注释、单引号与尾随逗号：

<script setup lang="ts">
defineUniPage({
  title: '首页',
  isTab: true,
  tab: { order: 0 }
})
</script>

同一页面同时声明宏与 <route-config> 时，以宏为准（顶层字段按宏覆盖）。插件默认自动生成全局类型声明 src/define-uni-page.d.ts（pages.dts 可自定义路径或 false 关闭），IDE 无需 import 即可识别宏，并获得类型提示与编译期检查。

<route-config> 自定义块（优先级低于宏）：内容为 JSONC（支持注释与尾随逗号），建议添加 lang="jsonc" 属性，让 IDE（Vue (Official) / Volar）按 JSONC 语法高亮：

<route-config lang="jsonc">
{
  "title": "首页",
  "isTab": true,
  "tab": { "order": 0 }
}
</route-config>

内置插件

各插件详细配置与 API 请查阅 官网插件文档。

插件开发框架

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

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

class MyPlugin extends BasePlugin<{ prefix?: string }> {
    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： BasePlugin（插件基类）、createPluginFactory（转换为 Vite 插件函数）、Logger（日志管理器）、Validator（链式配置验证器）。

详细 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 { deepMerge } from './uni_modules/vite-plugin/js_sdk/common/object/index.mjs'
import { normalizePath } from './uni_modules/vite-plugin/js_sdk/common/path/index.mjs'

各工具函数详细 API 请查阅 官网工具文档。

子路径导出

License

MIT