generateRouter

根据 uni-app 的 pages.json 自动生成路由配置文件和 TypeScript 类型声明，支持多种命名策略、元信息映射、路由修改保留和文件监听。

导入

import { generateRouter } from '@meng-xi/vite-plugin'
// 或子模块导入
import { generateRouter } from '@meng-xi/vite-plugin/plugins/generate/generate-router'

快速开始

import { defineConfig } from 'vite'
import { generateRouter } from '@meng-xi/vite-plugin'

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

配置选项

选项	类型	默认值	说明
pagesJsonPath	string	'src/pages.json'	pages.json 文件路径
outputPath	string	'src/router.config.ts'	输出文件路径
nameStrategy	NameStrategy	'camelCase'	路由名称生成策略
includeSubPackages	boolean	true	包含子包路由
dts	string | boolean	false	路由类型声明文件输出路径
preserveRouteChanges	boolean	true	保留用户对路由配置的修改

继承 BasePluginOptions：enabled、verbose、errorStrategy

高级选项

选项	类型	默认值	说明
outputFormat	'ts' | 'js'	'ts'	输出文件格式
customNameGenerator	(path: string) => string	-	自定义名称生成函数
watch	boolean	true	监听文件变化自动重新生成
metaMapping	Record<string, string>	见下方	style 字段到 meta 的映射
exportTypes	boolean	true	导出类型定义（仅 TS）
headerTemplate	boolean | string	false	文件头部注释模板
customFields	Record<string, string>	{}	自定义字段键值对

路由名称生成策略

策略	说明	示例路径	生成名称
camelCase	驼峰命名	/pages/user/profile	pagesUserProfile
pascalCase	帕斯卡命名	/pages/user/profile	PagesUserProfile
path	路径转下划线	/pages/user/profile	pages_user_profile
custom	自定义函数	-	-

默认 metaMapping

{
  navigationBarTitleText: 'title',
  requireAuth: 'requireAuth'
}

pages.json 中的 name 属性

pages.json 中页面配置对象的 name 字段会直接作为路由名称，且优先级高于 nameStrategy 自动生成。

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

上述配置中，路由名称为 'UserProfile'，而非 nameStrategy 自动生成的 'pagesUserProfile'。

pages.json 中的 meta 对象

pages.json 中页面配置对象的 meta 字段会直接合并到路由的 meta 中，且优先级高于 metaMapping 映射。

{
  "pages": [
    {
      "path": "pages/user/profile",
      "style": { "navigationBarTitleText": "个人中心" },
      "meta": { "requireAuth": true, "customField": "value" }
    }
  ]
}

上述配置中，meta.requireAuth 和 meta.customField 会直接写入路由 meta，style.navigationBarTitleText 通过 metaMapping 映射为 title。当两者存在同名字段时，meta 对象的值优先。

preserveRouteChanges 路由修改保留

开启后，插件重新生成路由配置时会读取已有文件，合并用户对路由的修改，避免覆盖用户手动添加的内容。

合并策略：

字段	行为
path	始终以 pages.json 为准，不可覆盖
name	始终以 pages.json 为准（pageConfig.name 或 nameStrategy 自动生成）
meta	pages.json 生成的字段始终使用新值，用户自定义字段保留
非标准属性	用户添加的 beforeEnter、component 等自定义属性完整保留

示例： 假设 pages.json 中修改了页面标题，且用户在已有路由上添加了 beforeEnter：

// 用户手动修改后的路由配置
export const routes: RouteConfig[] = [
  {
    path: '/pages/index/index',
    name: 'pagesIndexIndex',
    meta: { title: '自定义标题', customField: 'value' },
    beforeEnter: (to, from, next) => { next() }  // 用户添加的守卫
  }
]

重新生成后（pages.json 中 navigationBarTitleText 已改为"首页"）：

export const routes: RouteConfig[] = [
  {
    path: '/pages/index/index',
    name: 'pagesIndexIndex',
    meta: { title: '首页', isTab: true, customField: 'value' },  // title 同步为 pages.json 的值，customField 保留
    beforeEnter: (to, from, next) => { next() }   // 自定义属性保留
  },
  {
    path: '/pages/new/page',                       // 新增页面自动生成
    name: 'pagesNewPage',
    meta: { title: '新页面' }
  }
]

dts 类型声明

控制是否生成路由类型声明文件（.d.ts），为 @meng-xi/uni-router 模块扩展 RouteNameMap 接口，实现类型安全的路由导航。

值	说明
false	不生成类型声明文件（默认）
true	使用默认路径 src/router.d.ts
string	在指定路径生成类型声明文件

生成的类型声明文件示例：

import '@meng-xi/uni-router'

declare module '@meng-xi/uni-router' {
  interface RouteNameMap {
    /** 首页 */
    pagesIndexIndex: { path: '/pages/index/index'; meta: { title: string; isTab: true } }
    /** 个人中心 */
    pagesUserProfile: { path: '/pages/user/profile'; meta: { title: string; requireAuth: true } }
  }
}

类型导出

RouteMeta

路由附加的元数据，支持通过索引签名扩展自定义字段。

属性	类型	说明
title	string	页面标题，对应 navigationBarTitleText
isTab	boolean	是否为 TabBar 页面，由插件自动推断
requireAuth	boolean	是否需要登录才能访问
[key: any]	any	自定义扩展字段

RouteConfig

单条路由的完整配置。

属性	类型	说明
path	string	路由路径，以 / 开头
name	string	路由名称，由 pageConfig.name 或 nameStrategy 自动生成
meta	RouteMeta	路由元信息
[key: any]	any	用户自定义扩展属性（如 beforeEnter 等）

NameStrategy

路由名称生成策略类型：'path' | 'camelCase' | 'pascalCase' | 'custom'

OutputFormat

输出文件格式类型：'ts' | 'js'

示例

输出 JavaScript 文件

generateRouter({
  outputFormat: 'js',
  outputPath: 'src/router.config.js'
})

自定义路由名称

generateRouter({
  nameStrategy: 'custom',
  customNameGenerator: path => `route_${path.replace(/\//g, '_')}`
})

自定义 meta 映射

generateRouter({
  metaMapping: {
    navigationBarTitleText: 'title',
    requireAuth: 'requireAuth',
    customField: 'custom'
  }
})

生成路由类型声明

generateRouter({ dts: true }) // 使用默认路径 src/router.d.ts

// 或自定义路径
generateRouter({ dts: 'src/types/router.d.ts' })

添加文件注释头

在生成的路由配置文件顶部添加 JSDoc 风格的注释头。每个占位符自动对应一个 JSDoc 标签行，占位符之间的非占位符文本被丢弃。

// 使用默认模板（{name} {date} {version}）
generateRouter({ headerTemplate: true })
// 生成：
/**
 * @plugin generate-router
 * @date 2026-06-23 14:30:00
 * @version 0.2.7
 */

// 自定义日期格式
generateRouter({ headerTemplate: '{name} {date:YYYY-MM-DD} {version}' })
// 生成：
/**
 * @plugin generate-router
 * @date 2026-06-23
 * @version 0.2.7
 */

// 自定义字段
generateRouter({
  headerTemplate: '{name} {custom:author} {date} {version}',
  customFields: { author: 'MengXi Studio' }
})
// 生成：
/**
 * @plugin generate-router
 * @author MengXi Studio
 * @date 2026-06-23 14:30:00
 * @version 0.2.7
 */

占位符与 JSDoc 标签映射：

占位符	JSDoc 标签	替换值	示例
{name}	@plugin	插件名称	generate-router
{date}	@date	生成日期时间（默认格式 YYYY-MM-DD HH:mm:ss）	2026-06-23 14:30:00
{date:格式}	@date	按指定格式输出日期时间	{date:YYYY-MM-DD} → 2026-06-23
{version}	@version	插件版本号	0.2.7
{custom:键名}	@键名	自定义字段，值从 customFields 读取	{custom:author} → MengXi Studio

TIP

若模板完全不包含占位符，则按纯文本原样输出（不做标签转换）。

输出示例

export interface RouteMeta {
  title?: string
  isTab?: boolean
  requireAuth?: boolean
  [key: string]: any
}

export interface RouteConfig {
  path: string
  name?: string
  meta?: RouteMeta
}

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

export default routes

注意事项

• 当 nameStrategy 为 'custom' 时必须提供 customNameGenerator
• TabBar 页面自动添加 isTab: true 到 meta 中
• 支持解析带注释的 pages.json
• 开发模式下 watch: true 会监听 pages.json 变化并自动重新生成
• preserveRouteChanges 通过读取已有路由文件并合并用户修改，确保手动添加的内容不被覆盖