uni-router 0.2.1发布：路由配置更可读更可靠-尧图网络科技

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

写在前面

v0.2.1 的主题是：让生成的路由配置更可读、更可靠。

generateRouter 是面向 uni-app 项目的路由自动生成插件，从 pages.json 读取页面配置并输出 router.config.ts。v0.2.0 及之前版本存在两个体验问题：一是生成的路由对象为单行紧凑格式，多字段时难以阅读；二是
preserveRouteChanges 合并策略存在 meta 字段丢失和函数属性解析失败的缺陷。v0.2.1 针对这些问题进行了全面修复和增强，同时新增文件注释头功能，让生成的文件更具归属感。

本版重点：

能力	一句话说明	你需要做什么
`fileHeader` 文件注释头	生成文件顶部添加含插件名、日期时间、版本号的注释	新增配置 `fileHeader: true`
多行格式输出	路由对象从单行改为多行，每个属性独占一行	自动生效，无需配置
类型外部导入	移除内联类型定义，改为 `import type` 从 `@meng-xi/uni-router` 导入	自动生效，需确保安装 `@meng-xi/uni-router`
`preserveRouteChanges` meta 合并修复	meta 从整体替换改为逐字段合并，用户自定义字段不再丢失	自动生效
函数属性合并修复	含 `beforeEnter` 等函数的单条路由不再导致全部合并失败	自动生效

Breaking Changes：

移除 UniAnimationType 类型导出，改由 @meng-xi/uni-router 提供
移除 NavigationAnimation 类型导出，改由 @meng-xi/uni-router 提供
移除 RouteMeta.animation 字段，改由 @meng-xi/uni-router 提供

升级方式：修改 devDependencies 中版本号为 ^0.2.1。除上述类型导出变更外，完全向后兼容。

一、5 分钟快速上手

1.1 安装与升级

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

1.2 开启文件注释头

import { generateRouter } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [generateRouter({ fileHeader: true })]
})

生成的文件顶部：

/*** @plugin generate-router* @date 2026-06-21 10:30:00* @version 0.2.1*/import type { RouteConfig } from '@meng-xi/uni-router'/*** 路由配置列表* @description 由 pages.json 自动生成*/
export const routes: RouteConfig[] = [{path: '/pages/index/index',name: 'pagesIndexIndex',meta: { title: '首页', isTab: true }}
]export default routes

1.3 立刻看到效果

升级后无需任何配置变更，重新生成即可看到多行格式输出：

// 0.2.0 单行格式
{ path: '/pages/index/index', name: 'pagesIndexIndex', meta: { title: '首页', isTab: true } }// 0.2.1 多行格式
{path: '/pages/index/index',name: 'pagesIndexIndex',meta: { title: '首页', isTab: true }
}

二、核心能力：fileHeader 文件注释头

2.1 功能说明

开启 fileHeader 后，生成的路由配置文件顶部会添加标准化 JSDoc 注释头，包含三个标签：

标签	内容	示例
`@plugin`	插件名称	`generate-router`
`@date`	生成日期时间（精确到秒）	`2026-06-21 10:30:00`
`@version`	插件版本号（随 npm 包自动更新）	`0.2.1`

2.2 版本号自动同步

版本号通过构建脚本 scripts/generate-exports.ts 在 npm run build 时自动从 package.json 同步到源码中，无需手动维护：

// generator.ts 中的版本号常量
const PLUGIN_VERSION = '0.2.1' // 构建时自动替换

构建流程：

tsx scripts/generate-exports.ts → 读取 package.json 版本号，写入 generator.ts
unbuild → 打包，版本号作为字符串常量内联到产物中

2.3 配置项

选项	类型	默认值	描述
`fileHeader`	`boolean`	`false`	是否在生成文件顶部添加注释头

三、输出格式优化

3.1 多行格式

路由对象从单行紧凑格式改为多行展开格式，每个属性独占一行：

// 之前：单行格式，字段多时难以阅读
{ path: '/pages/user/profile', name: 'pagesUserProfile', meta: { title: '个人中心', requireAuth: true } }// 现在：多行格式，清晰可读
{path: '/pages/user/profile',name: 'pagesUserProfile',meta: { title: '个人中心', requireAuth: true }
}

3.2 类型外部导入

移除内联类型定义，改为从 @meng-xi/uni-router 统一导入：

// 之前：内联类型定义
interface RouteMeta { ... }
interface RouteConfig { ... }// 现在：外部导入
import type { RouteConfig } from '@meng-xi/uni-router'

四、Bug 修复

4.1 preserveRouteChanges 用户自定义 meta 字段丢失

问题：开启 preserveRouteChanges 后，用户在路由中自定义的 meta 字段（如 requireAuth、自定义标记等）在重新生成时被整体替换丢失。

原因：合并策略使用 Object.assign 整体覆盖 meta 对象，新生成的 meta 会覆盖用户添加的自定义字段。

修复：meta 合并从整体替换改为逐字段更新。新 meta 中的字段会添加或更新，但不会删除用户自定义的 meta 字段。

// 修复前：整体替换，用户自定义字段丢失
meta: { title: '首页', isTab: true }  // 用户添加的 requireAuth 丢失// 修复后：逐字段合并，用户自定义字段保留
meta: { title: '首页', isTab: true, requireAuth: true }  // requireAuth 保留

4.2 含函数属性时合并全部失败

问题：当用户在某条路由中添加了 beforeEnter 等函数属性时，JSON.parse 无法解析该路由对象，导致所有路由的合并操作全部跳过。

原因：原始实现使用 JSON.parse 解析整个路由数组，单条路由解析失败会中断整个解析流程。

修复：改为逐条路由解析，单条路由解析失败时仅跳过该条，其余路由正常合并。

场景	修复前	修复后
用户修改 `meta.title`	可能丢失	保留
用户添加自定义 meta 字段	丢失（整体替换）	保留（逐字段合并）
用户添加 `beforeEnter` 函数	保留	保留
某条路由有函数导致解析失败	所有路由合并跳过	仅该条跳过，其余正常合并

五、完整配置项

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 // 包含子包，默认 truewatch?: boolean // 监听变化，默认 truemetaMapping?: Record<string, string> // meta 字段映射exportTypes?: boolean // 导出类型，默认 truepreserveRouteChanges?: boolean // 保留用户修改，默认 truedts?: string | boolean // 类型声明文件，默认 falsefileHeader?: boolean // 文件注释头，默认 false（v0.2.1 新增）
}

六、实战场景

6.1 带注释头的完整配置

import { generateRouter } from '@meng-xi/vite-plugin'export default defineConfig({plugins: [generateRouter({fileHeader: true,pagesJsonPath: 'src/pages.json',outputPath: 'src/router.config.ts',nameStrategy: 'camelCase',includeSubPackages: true,metaMapping: {navigationBarTitleText: 'title',requireAuth: 'requireAuth'},dts: true})]
})

6.2 保留用户修改 + 自定义守卫

// 用户在 router.config.ts 中添加了 beforeEnter 守卫
export const routes: RouteConfig[] = [{path: '/pages/user/profile',name: 'pagesUserProfile',meta: { title: '个人中心', requireAuth: true },beforeEnter: (to, from, next) => {if (!isLoggedIn()) next('/pages/login/index')else next()}}
]// pages.json 新增页面后重新生成，beforeEnter 和自定义 meta 保留
export const routes: RouteConfig[] = [{path: '/pages/user/profile',name: 'pagesUserProfile',meta: { title: '个人中心', requireAuth: true },beforeEnter: (to, from, next) => {if (!isLoggedIn()) next('/pages/login/index')else next()}},{path: '/pages/settings/index', // 新增页面自动生成name: 'pagesSettingsIndex',meta: { title: '设置' }}
]

6.3 类型声明文件生成

generateRouter({dts: 'src/types/router.d.ts',fileHeader: true
})// 生成的 router.d.ts 为 @meng-xi/uni-router 扩展 RouteNameMap 接口
// 提供路由名称到路径和元信息的类型映射，实现类型安全的路由导航

七、内置插件全景

v0.2.1 共包含 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	运行时版本更新检查，支持多种提示样式和自定义回调