版本：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.tsunbuild→ 打包，版本号作为字符串常量内联到产物中
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 | 运行时版本更新检查，支持多种提示样式和自定义回调 |
八、子路径导出变更
新增
@meng-xi/vite-plugin/plugins/generate-router新增配置选项：fileHeader
移除
- 移除导出类型：
UniAnimationType、NavigationAnimation（改由@meng-xi/uni-router提供）
如果项目使用了上述类型，请从
@meng-xi/uni-router导入替代。