generatePages

扫描 Vue 文件并动态生成 / 更新 uni-app 的 pages.json 页面相关配置（pages / subPackages / tabBar），配合页面内 <route-config> 自定义块或 defineUniPage 宏彻底解放手动配置页面。

与 generateRouter 的关系

generateRouter 是「读 pages.json → 生成路由配置」，generatePages 则是反向「扫描 Vue 文件 → 生成 pages.json」。二者可配合使用，也可单独使用。

导入

typescript

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

快速开始

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

typescript

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

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

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

vue

<!-- src/pages/index/index.vue -->
<route-config lang="jsonc">
{
  "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" }
    ]
  }
}

配置选项

选项	类型	默认值	说明
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]	主包入口页路径（如 `pages/index/index`），固定为 pages[0]
titleFallback	`'filename' \| 'none'`	`'filename'`	标题缺失时的兜底策略
tabBar	`TabBarTemplate`	-	tabBar 模板（提供后才生成）
includeExtensions	`string[]`	`['.vue']`	页面文件扩展名列表；生成的 `path` 不含扩展名
excludePatterns	`string[]`	`['node_modules']`	排除的路径模式列表
watch	`boolean`	`true`	监听页面目录变化自动重新生成
dts	`string \| false`	`'src/define-uni-page.d.ts'`	`defineUniPage` 宏的全局类型声明输出路径（`false` 关闭）

继承 BasePluginOptions：enabled、verbose、errorStrategy

subPackages 分包

subPackages 的 root 写入 subPackages[].root，dir 为实际源码目录。dir 应与 root 对应的目录结构一致（默认 src/pages-sub ↔ pages-sub），否则 uni-app 将无法找到分包文件。

typescript

generatePages({
  subPackages: [
    { root: 'pages-sub', dir: 'src/pages-sub' },
    { root: 'pages-home', dir: 'src/pages-home' }
  ]
})

defineUniPage 宏

支持在 <script setup> 中通过 defineUniPage 宏声明页面配置，写法更贴近 JS/TS。

优先级：同一页面同时声明宏与 <route-config> 时，以宏为准（顶层字段按宏覆盖自定义块）。

vue

<script setup lang="ts">
defineUniPage({
  title: '详情',
  name: 'DetailPage',
  isTab: true,
  tab: { text: '详情', order: 0 }
})
</script>

宏参数为 JS 对象字面量，支持注释、单引号、尾随逗号与嵌套对象（tab / style / meta）
宏在扫描时被消费，运行时由插件自动移除调用，无需 import
参数需为纯对象字面量（不接受变量 / 表达式），否则静默忽略

TypeScript 声明：插件默认自动生成全局声明 src/define-uni-page.d.ts（dts 选项可自定义路径或 false 关闭），IDE（Vue (Official) / Volar / tsc）无需 import 即可识别宏，并获得类型提示与编译期检查。

route-config 自定义块

页面中也可通过 <route-config> 自定义块声明配置（优先级低于宏），内容为 JSONC（支持注释与尾随逗号，与 lang="jsonc" 的 IDE 高亮语义一致）。建议添加 lang="jsonc" 属性，让 IDE（Vue (Official) / Volar）按 JSONC 语法高亮自定义块内容。

字段	类型	说明
title	`string`	页面标题，映射为 `style.navigationBarTitleText`
name	`string`	页面名称，写入 pages.json 的 `name` 字段
style	`object`	页面样式，原样写入 `style` 字段
meta	`object`	页面元信息，原样写入 `meta` 字段
isTab	`boolean`	是否为 tabBar 页面，自动归集到 `tabBar.list`
tab	`TabBarItemOverride`	tabBar 图标、文本与 `order` 排序权重（`order` 仅排序，不写入输出）

vue

<route-config lang="jsonc">
{
  "title": "详情",
  "name": "DetailPage",
  "meta": { "requireAuth": true }
}
</route-config>

tabBar 生成

提供 tabBar 模板后，插件将所有 isTab: true 的主包页面（tabBar 仅允许主包）自动归集到 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'
      }
    }
  }
})

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

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

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

推荐将图标就近声明在页面内，工厂只需提供全局样式与默认图标：

vue

<!-- src/pages/mine/mine.vue -->
<route-config lang="jsonc">
{
  "title": "我的",
  "isTab": true,
  "tab": {
    "iconPath": "static/tab/mine.png",
    "selectedIconPath": "static/tab/mine-active.png"
  }
}
</route-config>

合并策略

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

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

类型导出

GeneratePagesOptions

插件配置项，见上文「配置选项」。

RouteConfigBlock

defineUniPage 宏与 <route-config> 块共用的页面配置类型（title / name / style / meta / isTab / tab）。

TabBarTemplate

tabBar 模板（整体样式 + 全局图标 + overrides 覆盖）。

TabBarItemOverride

单个 tabBar 项的 text / iconPath / selectedIconPath 覆盖。

SubPackageConfig

分包配置：root（分包标识）+ dir（源码目录）。

示例

使用预设对应目录结构

typescript

generatePages()
// 扫描 src/pages → pages，src/pages-sub → subPackages

自定义分包与 tabBar

typescript

generatePages({
  pagesDir: 'src/pages',
  subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
  tabBar: {
    color: '#999999',
    selectedColor: '#42b883',
    iconPath: 'static/tab.png',
    selectedIconPath: 'static/tab-active.png'
  }
})

注意事项

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

generatePages ​

导入 ​

快速开始 ​

配置选项 ​

subPackages 分包 ​

defineUniPage 宏 ​

route-config 自定义块 ​

tabBar 生成 ​

合并策略 ​

类型导出 ​

GeneratePagesOptions ​

RouteConfigBlock ​

TabBarTemplate ​

TabBarItemOverride ​

SubPackageConfig ​

示例 ​

使用预设对应目录结构 ​

自定义分包与 tabBar ​

注意事项 ​

generatePages

导入

快速开始

配置选项

subPackages 分包

defineUniPage 宏

route-config 自定义块

tabBar 生成

合并策略

类型导出

GeneratePagesOptions

RouteConfigBlock

TabBarTemplate

TabBarItemOverride

SubPackageConfig

示例

使用预设对应目录结构

自定义分包与 tabBar

注意事项