@meng-xi/vite-plugin v1.3.0：generateUni 一键流水线

PedroQue992026-08-27 9:55

版本：1.3.0 | 协议：MIT | 依赖：Vite >=5.0.0 <9.0.0

写在前面

v1.3.0 的主题是：新增 generateUni 组合入口插件，一条流水线完成「扫描页面 → pages.json → 路由配置」。

v1.2.0 引入了 generatePages（扫描 Vue 文件 → 生成 pages.json），与 generateRouter（基于 pages.json → 生成路由配置）配合使用。但两者连用需要各自配置、各自读盘。v1.3.0 新增第 17 个插件 generateUni，将二者编排为一条流水线------内存数据直传不重复读盘，等价于两插件连用，但更简单、更高效。

同时，本版为 standalone 的 generatePages 补齐了 <route-config> 自定义块的虚拟模块拦截，并优化了 proxyManager 在生产构建时的行为。

本版重点：

能力 一句话说明 你需要做什么
新增 generateUni 一键流水线：扫描页面 → pages.json → 路由配置（内存直传） 用 generateUni 替换两插件连用
配置分组 顶层公共项 + pages 子对象 + router 子对象，避免 20+ 平铺 按分组配置，结构清晰
generatePages 增强 补齐 <route-config> 块虚拟模块拦截，生产构建不再报错 无需配置，自动生效
proxyManager 优化 生产构建完全跳过代理规则加载与配置生成 无需配置，自动生效
类型重构 uni-app 通用类型抽离到 generate 公共模块，消除反向依赖 无感知，类型导出保持兼容

升级方式 ：修改 devDependencies 中版本号为 ^1.3.0。无 Breaking Change，1.x 用户可平滑升级。

一、5 分钟快速上手

1.1 安装与升级

json 复制代码 
{
	"devDependencies": {
		"@meng-xi/vite-plugin": "^1.3.0"
	}
}

1.2 一键流水线

generateUni 替代 generatePages + generateRouter 连用：

typescript 复制代码 
// vite.config.ts
import { defineConfig } from 'vite'
import { generateUni } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		generateUni({
			pagesJsonPath: 'src/pages.json', // 顶层：两阶段共用
			pages: {
				// 阶段一：页面生成（generatePages 参数）
				pagesDir: 'src/pages',
				subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
				entryPage: 'pages/index/index',
				tabBar: { color: '#999999', selectedColor: '#42b883' }
			},
			router: {
				// 阶段二：路由生成（generateRouter 参数）
				outputPath: 'src/router.config.ts',
				nameStrategy: 'camelCase',
				dts: 'src/router.d.ts'
			}
		})
	]
})

1.3 从两插件连用迁移

v1.2.0 写法（连用） v1.3.0 写法（generateUni）
generatePages({ pagesDir, subPackages, entryPage, tabBar }) generateUni({ pages: { pagesDir, subPackages, entryPage, tabBar } })
generateRouter({ outputPath, nameStrategy, dts }) generateUni({ router: { outputPath, nameStrategy, dts } })
两插件各自读盘、各自写盘 阶段一内存产出直传阶段二，不重复读盘

二、generateUni 插件详解

2.1 流水线编排

scss 复制代码 
阶段一（页面生成）                   阶段二（路由生成）
扫描 Vue 文件 + <route-config>   →   直接消费内存 pages 对象
      ↓                                    ↓
   内存 pages 数据                    生成路由配置 + 可选 dts
      ↓
   写盘 pages.json（供 uni() 使用）
  • 阶段一 ：扫描页面 + <route-config> 产出内存 pages 数据并写盘 pages.json
  • 阶段二 ：直接消费阶段一的内存 pages 对象生成路由配置文件（+ 可选 dts），不再「先写盘再读盘」

2.2 配置分组

为避免 20+ 平铺选项，generateUni 采用分组配置：

层级 说明 对应插件
顶层 两阶段共用：pagesJsonPath / watch -
pages 阶段一专有参数：pagesDir / subPackages / routeConfigBlock / entryPage / titleFallback / tabBar / includeExtensions / excludePatterns generatePages
router 阶段二专有参数：outputPath / outputFormat / nameStrategy / metaMapping / exportTypes / preserveRouteChanges / headerTemplate / customFields / dts / includeSubPackages generateRouter

2.3 串行生成与监听

  • 开发模式下 watch: true（默认）监听主包与分包目录，页面文件变化时串行重跑「阶段一 + 阶段二」，避免并发读写竞态
  • 生成任务经 Promise 队列串行化，即使保存文件高频触发也安全

2.4 route-config 块拦截

generateUni 注册 transform 钩子，将 <route-config> 自定义块产生的虚拟模块请求（如 xxx.vue?vue&type=route-config&index=0）替换为空模块，避免构建时被当作 JavaScript 解析报错。块内容已由阶段一扫描时解析，无需在模块系统中保留。

2.5 保留能力

generateUni 完整继承两插件能力：

  • generatePages 侧 ：tabBar 归集 / 分包 / 合并策略（保留 globalStyle/condition）/ 入口页固定 / tab 排序
  • generateRouter 侧 ：preserveRouteChanges（保留用户对路由的修改）/ metaMapping / headerTemplate / customFields / dts 类型声明

2.6 配置选项

typescript 复制代码 
interface GenerateUniOptions extends BasePluginOptions {
	pagesJsonPath?: string // pages.json 路径，默认 'src/pages.json'
	watch?: boolean // 监听页面目录变化，默认 true
	pages?: GeneratePagesOptions // 阶段一参数（页面生成）
	router?: GenerateRouterOptions // 阶段二参数（路由生成）
}

三、generatePages 增强

为 standalone 的 generatePages 补充 <route-config> 自定义块虚拟模块拦截（与 generateUni 行为一致，此前仅 generateUni 具备）：

  • 注册 transform 钩子，将 xxx.vue?vue&type=route-config&index=0 请求替换为空模块
  • 避免生产构建把块内容当作 JavaScript 解析而报错
  • 无需任何配置，独立使用 generatePages 时同样安全
typescript 复制代码 
// v1.3.0 起，独立使用 generatePages 生产构建不再报错
import { generatePages } from '@meng-xi/vite-plugin'
generatePages({ pagesDir: 'src/pages' })

四、proxyManager 优化

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

变更点 说明
避免无意义加载 build 阶段不再加载 .proxyrc.ts、不再解析 envPrefix 覆盖
消除误导日志 移除 build 时的「已加载 X 条代理规则 (环境: production)」日志
行为不变 开发服务器（dev）下功能、规则、中间件、日志逻辑完全保持不变

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

五、类型重构

uni-app 通用类型（UniAppPageConfig / UniAppTabBarConfig / UniAppPagesJson）从 generateRouter/types.ts 抽离到新的公共模块 generate/types.ts：

  • 消除反向依赖 ：generatePages / generateUni 等不再反向依赖 generateRouter 的类型
  • 子路径兼容 ：generateRouter 转发导出这些类型，原导入路径不受影响
  • 无感升级：所有类型导出保持兼容，用户无需修改任何代码

六、子路径导出变更

新增

  • @meng-xi/vite-plugin/plugins/generate/generate-uni：导出 generateUni 及类型 GenerateUniOptions
  • @meng-xi/vite-plugin/plugins/generate：聚合导出 generateUni 及其类型
typescript 复制代码 
// 按需导入（推荐，利于 Tree-shaking）
import { generateUni } from '@meng-xi/vite-plugin/plugins/generate/generate-uni'
// 或分组聚合导入
import { generateUni } from '@meng-xi/vite-plugin/plugins/generate'

七、插件清单（变更）

插件总数由 16 增至 17，分组由 7 组不变：

分组 插件
generate autoImport、generateUni、generatePages、generateRouter、generateVersion（由 4 增至 5）
analyze buildProgress、bundleAnalyzer
compress compressAssets、imageOptimizer
copy assetManifest、copyFile
guard envGuard
inject faviconManager、htmlInject、loadingManager、versionUpdateChecker
proxy proxyManager

八、实战场景

8.1 uni-app 项目：一条流水线

typescript 复制代码 
// vite.config.ts
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { generateUni } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		uni(),
		// 一条流水线：扫描页面 → pages.json → 路由配置
		generateUni({
			pagesJsonPath: 'src/pages.json',
			watch: true,
			pages: {
				pagesDir: 'src/pages',
				subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
				entryPage: 'pages/index/index',
				titleFallback: 'filename',
				tabBar: {
					color: '#999999',
					selectedColor: '#42b883',
					backgroundColor: '#ffffff'
				}
			},
			router: {
				outputPath: 'src/router.config.ts',
				nameStrategy: 'camelCase',
				headerTemplate: '{name} {date:YYYY-MM-DD} {version}',
				dts: 'src/router.d.ts'
			}
		})
	]
})

页面内就近声明：

vue 复制代码 
<!-- src/pages/mine/mine.vue -->
<route-config>
{
	"title": "我的",
	"isTab": true,
	"tab": {
		"iconPath": "static/tab/mine.png",
		"selectedIconPath": "static/tab/mine-active.png"
	}
}
</route-config>

8.2 保留两插件独立使用

generatePages 与 generateRouter 保持不变，仍可独立使用：

typescript 复制代码 
// 仅生成 pages.json
generatePages({ pagesDir: 'src/pages' })

// 仅生成路由配置（基于已有的 pages.json）
generateRouter({ pagesJsonPath: 'src/pages.json', outputPath: 'src/router.config.ts' })

九、注意事项

  • generateUni 等价于 generatePages + generateRouter 连用，但内存直传不重复读盘，且配置分组更清晰
  • pages / router 子对象分别等价于两个插件的全部选项，缺失时使用默认值
  • 开发模式 watch: true 监听主包与分包目录，串行重跑整条流水线
  • <route-config> 块拦截对 generateUni 与 standalone generatePages 均生效
  • 类型导出完全兼容，原 generateRouter 子路径的 uni-app 类型导入不受影响

写在最后

v1.3.0 将 uni-app 页面与路由的生成链路收敛为一条流水线：generateUni 一个插件、一次配置、一轮执行，完成「扫描页面 → pages.json → 路由配置」全流程。

  • 流水线编排让两插件协作从「手动连用」升级为「自动编排」，且内存直传消除读盘往返
  • 配置分组避免 20+ 平铺选项，顶层 / pages / router 三层结构一目了然
  • 两插件增强 （generatePages 块拦截 + proxyManager 构建跳过）修复了生产构建的潜在报错与无意义开销
  • 零破坏性升级让 1.x 用户可平滑迁移

后续版本将聚焦于：generateUni 更多阶段扩展（如 manifest.json 配置生成）、uni-app 条件编译深度集成。如果你有任何建议或问题，欢迎在 GitHub Issues 反馈。

相关推荐
胡萝卜术1 小时前
权限系统的四道防线：从数据库事务锁到操作级保护规则的完整设计
前端·javascript·面试
IMPYLH1 小时前
HTML 的 ＜legend＞ 元素
java·前端·html
真夜1 小时前
RN热更新安全问题
前端·react native
Zeroplucky1 小时前
Binder 线程池耗尽案例：持锁同步调用 VHAL 导致 SystemUI 卡顿或 ANR
前端
Zeroplucky1 小时前
从 registerContentObserver 剖析 Android Binder 流程
前端
Yinlin1241 小时前
深入悬浮组件实现
前端
yangzheui1 小时前
nvue页面事件穿透到下层元素解决办法
前端
杉氧1 小时前
从 Modifier 到 Flexbox：React Native 布局与样式设计哲学
android·前端·react native
比老马还六1 小时前
Bipes-Blockly项目二次开发/硬件功能-LED灯条（十一）
前端·嵌入式硬件·硬件工程
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04历年考研数学一、数学二、数学三真题试卷及答案PDF05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路08VSCode+CodeX扩展，无法启动09如何新建文件夹？ 电脑新建文件夹的4种方法102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片