Vite 1.2.0发布：自动生成pages.json

PedroQue992026-08-26 9:54

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

写在前面

v1.2.0 的主题是：新增 generatePages 插件，让 pages.json 也能自动生成。

此前的 generateRouter 是「读 pages.json → 生成路由配置」，但 pages.json 本身仍需手动维护。v1.2.0 新增第 16 个插件 generatePages，反其道而行------扫描 Vue 文件 + 页面内 <route-config> 自定义块，自动生成 / 更新 pages.json 的 pages / subPackages / tabBar，彻底解放手动配置页面。

同时，本版将 Vite 的 peerDependencies 范围放宽至 <9.0.0，兼容 Vite 8。

本版重点：

能力 一句话说明 你需要做什么
新增 generatePages 插件 扫描 Vue 文件 + <route-config> 块自动生成 pages.json 替换手动维护 pages.json 页面部分
主包 / 分包页面 pagesDir + subPackages 自动扫描生成 pages 与 subPackages 按目录结构约定放置页面文件即可
tabBar 自动归集 isTab 标记 + tabBar 模板自动组装 list 页面内声明 isTab + tab 图标
就近声明配置 <route-config> 自定义块在页面内声明标题 / 样式 / meta / name 配置跟随页面文件，无需集中维护
入口页固定 entryPage 保证启动页为 pages[0] 指定入口页路径
非页面字段保留 仅覆盖页面部分，保留 globalStyle / condition 等 无需额外配置

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

一、5 分钟快速上手

1.1 安装与升级

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

1.2 基础用法

默认扫描 src/pages 为主包、src/pages-sub 为分包，自动生成 src/pages.json：

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

export default defineConfig({
	plugins: [generatePages()]
})

1.3 页面内就近声明配置

在每个页面中通过 <route-config> 自定义块声明标题、meta、tabBar 归属：

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

生成的 pages.json 片段：

json 复制代码 
{
	"pages": [
		{
			"path": "pages/index/index",
			"style": { "navigationBarTitleText": "首页" },
			"meta": { "isTab": true }
		}
	],
	"tabBar": {
		"color": "#999999",
		"list": [
			{
				"pagePath": "pages/index/index",
				"text": "首页",
				"iconPath": "static/tab/home.png",
				"selectedIconPath": "static/tab/home-active.png"
			}
		]
	}
}

1.4 与 generateRouter 组合

generatePages 生成 pages.json，generateRouter 再读取 pages.json 生成路由配置------二者可无缝组合：

typescript 复制代码 
// 注意：generatePages 应置于 generateRouter 之前
;(generatePages({ tabBar: { color: '#999999', selectedColor: '#42b883' } }), generateRouter({ pagesJsonPath: 'src/pages.json' }))

二、generatePages 插件详解

2.1 核心能力

能力 配置 / 用法 说明
主包页面生成 pagesDir: 'src/pages' 递归扫描生成 pages，页面路径稳定排序
分包页面生成 subPackages: [{ root, dir }] 自动扫描生成 subPackages，目录缺失时跳过
tabBar 归集 <route-config> 声明 isTab + tabBar 模板 自动将 tab 页面归集到 tabBar.list
就近声明配置 <route-config> 自定义块 标题 / 样式 / meta / name / tab 在页面内就近声明
入口页固定 entryPage: 'pages/index/index' 保证 pages[0] 为启动页，不被字母序排序改写
tabBar 排序 <route-config>.tab.order 按 order 升序排列 list，仅用于排序、不写入输出
合并策略 自动（无需配置） 仅覆盖页面部分，保留 globalStyle / condition 等
开发监听 watch: true（默认） 页面目录文件变化时自动重新生成

2.2 route-config 自定义块

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

vue 复制代码 
<route-config>
{
	"title": "详情",
	"name": "DetailPage",
	"meta": { "requireAuth": true },
	"isTab": true,
	"tab": { "text": "详情", "iconPath": "static/tab/detail.png", "order": 1 }
}
</route-config>
字段 类型 说明
title string 页面标题，映射为 style.navigationBarTitleText
name string 页面名称，写入 name 字段
style object 原样写入 style 字段
meta object 原样写入 meta 字段
isTab boolean 是否为 tabBar 页面，自动归集到 tabBar.list
tab TabBarItemOverride tabBar 图标 / 文本 / order 排序权重

注意：tabBar 页面仅允许在主包，分包中的 isTab 标记会被忽略。

2.3 入口页固定

uni-app 以 pages[0] 为启动页。若直接按路径排序，入口页会随字母序漂移（例如默认入口 pages/index/index 可能被 pages/about/about 取代）。entryPage 保证入口页始终固定在首位：

typescript 复制代码 
generatePages({
	entryPage: 'pages/index/index' // 未配置时继承现有 pages.json 的 pages[0]
})

2.4 tabBar 模板与优先级

提供 tabBar 模板后，插件将所有 isTab: true 的主包页面自动归集到 list：

typescript 复制代码 
generatePages({
	tabBar: {
		color: '#999999',
		selectedColor: '#42b883',
		iconPath: 'static/tab/home.png', // 全局默认图标，所有 tab 项继承
		selectedIconPath: 'static/tab/home-active.png',
		overrides: {
			// 按页面路径逐项覆盖（可选）
			'pages/about/about': {
				text: '关于我们',
				iconPath: 'static/tab/about.png',
				selectedIconPath: 'static/tab/about-active.png'
			}
		}
	}
})

图标与文本优先级（从高到低）：

  1. 页面内 <route-config>.tab 声明
  2. tabBar.overrides[pagePath]
  3. tabBar.iconPath / selectedIconPath（全局模板）
  4. 页面标题 / 文件名（作为 text 兜底）

list 排序： 按每项 tab.order 升序排列（越小越靠前），未声明 order 的项排在已声明之后、保持原相对顺序；order 仅用于排序，不会写入生成的 tabBar.list。

2.5 合并策略

插件「仅生成页面部分，其余保留」：

  • 始终覆盖 ：pages（主包页面）
  • 有分包时覆盖 ：subPackages；否则保留现有
  • 提供模板时覆盖 ：tabBar；否则保留现有
  • 原样保留 ：globalStyle、condition、easycom 等非页面字段

2.6 开发监听

开发模式下 watch: true（默认）会监听主包与分包目录，新增 / 删除 / 修改页面自动重新生成。生成任务经串行队列处理，避免变更高频触发时并发读改写竞态。

三、配置选项

选项 类型 默认值 说明
pagesJsonPath string 'src/pages.json' pages.json 文件路径
pagesDir string 'src/pages' 主包页面目录
subPackages SubPackageConfig[] [{ root:'pages-sub', dir:'src/pages-sub' }] 分包配置列表（目录缺失时跳过）
routeConfigBlock string 'route-config' 页面配置自定义块名称
entryPage string 现有 pages[0] 主包入口页路径，固定为 pages0
titleFallback `'filename' 'none'` 'filename'
tabBar TabBarTemplate - tabBar 模板（提供后才生成）
includeExtensions string[] ['.vue'] 页面文件扩展名列表
excludePatterns string[] ['node_modules'] 排除的路径模式列表
watch boolean true 监听页面目录变化自动重新生成

继承 BasePluginOptions：enabled、logLevel、errorStrategy。

类型导出

  • GeneratePagesOptions --- 插件配置项
  • RouteConfigBlock --- <route-config> 块中可声明的页面配置
  • SubPackageConfig --- 分包配置（root + dir）
  • TabBarTemplate --- tabBar 模板（整体样式 + 全局图标 + overrides）
  • TabBarItemOverride --- 单个 tabBar 项的 text / iconPath / selectedIconPath / order
  • ScannedPage --- 扫描得到的页面信息

四、子路径导出变更

新增

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

依赖范围

  • peerDependencies.vite：由 >=5.0.0 <8.0.0 放宽为 >=5.0.0 <9.0.0，兼容 Vite 8

五、实战场景

5.1 uni-app 项目：全自动页面配置

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

export default defineConfig({
	plugins: [
		uni(),
		// 1. 生成 pages.json（必须在 generateRouter 之前）
		generatePages({
			pagesDir: 'src/pages',
			subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
			entryPage: 'pages/index/index',
			tabBar: {
				color: '#999999',
				selectedColor: '#42b883',
				backgroundColor: '#ffffff'
			}
		}),
		// 2. 基于 pages.json 生成路由配置
		generateRouter({ pagesJsonPath: 'src/pages.json' })
	]
})

页面内就近声明：

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>

5.2 多分包 + 命名空间

typescript 复制代码 
generatePages({
	pagesDir: 'src/pages',
	subPackages: [
		{ root: 'pages-sub', dir: 'src/pages-sub' },
		{ root: 'pages-home', dir: 'src/pages-home' }
	],
	// 注意：分包 dir 应与 root 对应的目录结构一致，否则 uni-app 无法找到分包文件
	excludePatterns: ['node_modules']
})

5.3 零配置体验

不传任何参数，默认即可覆盖大多数场景：

typescript 复制代码 
generatePages()
// 扫描 src/pages → pages，src/pages-sub → subPackages，自动生成 src/pages.json

六、插件清单（变更）

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

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

七、注意事项

  • 主包页面路径相对 pages.json 所在目录；分包页面路径相对分包目录，且分包 dir 应与 root 目录结构一致
  • tabBar 页面仅允许在主包，分包中的 isTab 标记会被忽略
  • 开发模式下 watch: true 会监听主包与分包目录，新增 / 删除 / 修改页面自动重新生成
  • 生成结果按页面路径稳定排序，保证 pages.json 顺序在不同文件系统下一致
  • 首次生成会自动创建 pages.json 所在目录
  • generatePages 与 generateRouter 组合使用时，generatePages 应置于 generateRouter 之前

写在最后

v1.2.0 补齐了 uni-app 开发链路中「页面配置」这一环：generatePages 负责生成 pages.json，generateRouter 负责基于 pages.json 生成路由配置与类型声明，两者形成完整的「页面文件 → 页面配置 → 路由配置」自动化闭环。

  • 就近声明让页面配置跟随文件本身，集中维护的历史一去不返
  • tabBar 自动归集 + 入口页固定解决了两大手动维护痛点
  • 零破坏性升级让 1.x 用户可平滑迁移

后续版本将聚焦于：更多 uni-app 场景的自动化（如 manifest.json 配置生成）、generatePages 与 uni-app 条件编译的深度集成。如果你有任何建议或问题，欢迎在 GitHub Issues 反馈。

相关推荐
ly76891 小时前
React 19 从入门到工程实践：核心原理、新特性与项目实战
前端·react.js·前端框架
tedcloud1231 小时前
diagram-design 怎么安装？用 AI 自动生成更专业的架构图、流程图
linux·运维·前端·人工智能·开源·流程图
何智超1 小时前
React 18 并发更新：高优先级先渲染，为什么最终状态不会算错？
前端
前端小万1 小时前
两个半月的时间如何赚到 3000 块钱。
前端
YIAN1 小时前
端侧大模型：DeepSeek-R1 WebGPU 推理全流程源码深度解析
前端·typescript·deepseek
请你吃div1 小时前
个人 Nuxt4 博客 SEO 优化实战教程
前端·nuxt.js·seo
网安蟹佬霸1 小时前
Android安全攻防实战：从APK逆向到Frida动态Hook全流程详解（附脚本）
android·前端·安全·web安全·逆向·csrf·网安
计算机魔术师1 小时前
芯片不跌反涨？两家公司的赌局正在重塑全球算力格局
前端
IT_陈寒1 小时前
Python多进程池的坑：子进程竟然不会退出
前端·人工智能·后端
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费06历年考研数学一、数学二、数学三真题试卷及答案PDF07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法