UniApp路由配置升级：pages.json权威指南

版本：0.2.4 | 协议：MIT | 依赖：Vite >=5.0.0 <8.0.0

写在前面

v0.2.4 的主题是：让 pages.json 成为路由配置的唯一权威来源。

本次更新聚焦两个方面：一是为 UniAppPageConfig 新增 name 属性，支持在 pages.json 中直接配置页面路由名称，优先级高于 nameStrategy 自动生成；二是优化 preserveRouteChanges 合并策略，明确 pages.json

是自动生成字段的唯一来源，name 和 meta 中来自 pages.json 的字段始终使用新值，仅保留用户自定义的额外字段。

本版重点：

能力	一句话说明	你需要做什么
页面级 `name` 字段支持	pages.json 中可直接为页面配置路由名称，优先级高于 `nameStrategy`	在 pages.json 中配置
`preserveRouteChanges` 策略优化	pages.json 是自动生成字段的唯一来源，`name`/`meta` 始终使用新值	自动生效

升级方式 ：修改 devDependencies 中版本号为 ^0.2.4。无 Breaking Changes，完全向后兼容。

一、5 分钟快速上手

1.1 安装与升级

json 复制代码

{
	"devDependencies": {
		"@meng-xi/vite-plugin": "^0.2.4"
	}
}

1.2 在 pages.json 中直接配置 name

json 复制代码

{
	"pages": [
		{
			"path": "pages/index/index",
			"name": "Home",
			"style": {
				"navigationBarTitleText": "首页"
			}
		},
		{
			"path": "pages/user/profile",
			"name": "UserProfile",
			"style": {
				"navigationBarTitleText": "个人中心"
			}
		}
	]
}

生成的路由配置：

typescript 复制代码

import type { RouteConfig } from '@meng-xi/uni-router'

export const routes: RouteConfig[] = [
	{
		path: '/pages/index/index',
		name: 'Home',
		meta: { title: '首页', isTab: true }
	},
	{
		path: '/pages/user/profile',
		name: 'UserProfile',
		meta: { title: '个人中心' }
	}
]

export default routes

二、页面名称 name 字段

2.1 优先级规则

name 字段的取值优先级：

优先级	来源	说明
1（高）	`pageConfig.name`	pages.json 中页面直接配置的 `name` 字段
2（低）	`nameStrategy`	根据 path 和命名策略自动生成

typescript 复制代码

// pages.json
{
	"path": "pages/user/profile",
	"name": "UserProfile",
	"style": { "navigationBarTitleText": "个人中心" }
}

// 生成的路由中 name 为 'UserProfile'，而非 nameStrategy 自动生成的 'pagesUserProfile'

2.2 与 nameStrategy 共存

未配置 name 的页面仍使用 nameStrategy 自动生成：

json 复制代码

{
	"pages": [
		{
			"path": "pages/index/index",
			"name": "Home",
			"style": { "navigationBarTitleText": "首页" }
		},
		{
			"path": "pages/about/about",
			"style": { "navigationBarTitleText": "关于" }
		}
	]
}

typescript 复制代码

// Home 使用 pageConfig.name，about 使用 nameStrategy 自动生成
export const routes: RouteConfig[] = [
	{ path: '/pages/index/index', name: 'Home', meta: { title: '首页' } },
	{ path: '/pages/about/about', name: 'pagesAboutAbout', meta: { title: '关于' } }
]

三、preserveRouteChanges 合并策略优化

3.1 设计原则

pages.json 是自动生成字段的唯一权威来源。 用户不应在 router.config.ts 中手动修改来自 pages.json 的字段值，因为这些值会在下次生成时被覆盖。

3.2 字段合并规则

字段	优化前	优化后
`name`	用户修改的值优先保留	始终以 `pages.json` 为准（`pageConfig.name` 或 `nameStrategy`）
`meta` 自动生成字段	用户修改的值优先保留	`pages.json` 生成的字段始终使用新值
`meta` 用户自定义字段	保留	保留（不变）

3.3 实际场景

typescript 复制代码

// pages.json 中修改了标题
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "新标题" } }

// 用户在 router.config.ts 中添加了自定义字段
{
  path: '/pages/index/index',
  name: 'pagesIndexIndex',
  meta: { title: '旧标题', customField: 'value' },
  beforeEnter: (to, from, next) => { next() }
}

// 优化前：meta.title 保留 '旧标题'（用户修改优先）
// 优化后：meta.title 更新为 '新标题'（pages.json 为准），customField 保留
{
  path: '/pages/index/index',
  name: 'pagesIndexIndex',
  meta: { title: '新标题', customField: 'value' },
  beforeEnter: (to, from, next) => { next() }
}

四、完整配置项

typescript 复制代码

interface GenerateRouterOptions extends BasePluginOptions {
	pagesJsonPath?: string // pages.json 路径，默认 'src/pages.json'
	outputPath?: string // 输出文件路径，默认 'src/router.config.ts'
	outputFormat?: 'ts' | 'js' // 输出格式，默认 'ts'
	nameStrategy?: NameStrategy // 命名策略，默认 'camelCase'
	customNameGenerator?: (path: string) => string // 自定义命名函数
	includeSubPackages?: boolean // 包含子包，默认 true
	watch?: boolean // 监听变化，默认 true
	metaMapping?: Record<string, string> // meta 字段映射
	exportTypes?: boolean // 导出类型，默认 true
	preserveRouteChanges?: boolean // 保留用户修改，默认 true
	dts?: string | boolean // 类型声明文件，默认 false
	fileHeader?: boolean // 文件注释头，默认 false
}

五、实战场景

5.1 使用页面名称 + 自定义守卫

typescript 复制代码

// vite.config.ts
import { generateRouter } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [
		generateRouter({
			fileHeader: true,
			preserveRouteChanges: true,
			metaMapping: {
				navigationBarTitleText: 'title'
			},
			dts: true
		})
	]
})

json 复制代码

// pages.json --- 使用 name 字段配置路由名称
{
	"pages": [
		{
			"path": "pages/index/index",
			"name": "Home",
			"style": { "navigationBarTitleText": "首页" }
		},
		{
			"path": "pages/admin/dashboard",
			"name": "AdminDashboard",
			"style": { "navigationBarTitleText": "管理后台" },
			"meta": { "requireAuth": true, "role": "admin" }
		}
	]
}

六、内置插件全景

v0.2.4 共包含 15 个实用插件，覆盖构建优化的各个方面：

插件	enforce	描述
`assetManifest`	post	构建后生成资源映射清单，支持 Vite/Webpack/自定义格式、按入口分组和运行时注入
`autoImport`	pre	自动导入，支持预设映射、通配符（`'*'`）、目录扫描、Vue 模板自动导入和类型声明生成
`buildProgress`	-	终端实时构建进度条，支持 bar / spinner / minimal
`bundleAnalyzer`	post	构建产物体积分析，支持 JSON/HTML 报告、gzip 计算和阈值告警
`compressAssets`	post	构建产物压缩，支持 gzip / brotli / both，并发压缩和统计报告
`copyFile`	post	构建完成后复制文件或目录，支持增量复制
`envGuard`	post	环境变量校验，支持类型检查、范围验证、自定义规则和运行时守卫
`faviconManager`	post	管理网站图标链接注入和文件复制
`generateRouter`	post	根据 pages.json 自动生成路由配置与类型声明（uni-app）
`generateVersion`	post	自动生成版本号，支持文件输出和全局变量注入
`htmlInject`	post	HTML 内容注入，支持多种位置、选择器定位、条件注入和安全过滤
`imageOptimizer`	post	图片优化压缩与格式转换，支持 WebP/AVIF 转换、SVG 优化、并发处理
`loadingManager`	post	全局 Loading 状态管理，支持请求拦截、防抖、过渡动画
`proxyManager`	-	开发代理管理，支持环境切换、规则文件、请求日志、延迟模拟和响应修改
`versionUpdateChecker`	post	运行时版本更新检查，支持多种提示样式和自定义回调

七、子路径导出变更

新增

UniAppPageConfig 类型新增 name 可选字段，支持页面级路由名称配置