generateUni

组合入口插件：将「扫描页面 → 生成 pages.json」与「读 pages.json → 生成路由配置」编排为一条流水线，一条流水线完成 uni-app 的页面配置与路由配置生成，内存数据直传不重复读盘。

与 generatePages / generateRouter 的关系

generateUni 等价于 generatePages + generateRouter 连用，但两阶段通过内存中的 pages 数据串联，避免「先写盘再读盘」的中间产物往返。原有两个插件保持不变，仍可单独使用。

导入

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

快速开始

顶层配置两阶段共用的 pagesJsonPath 与 watch；pages 子对象为阶段一（页面生成）参数，router 子对象为阶段二（路由生成）参数。

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

export default defineConfig({
  plugins: [
    generateUni({
      pagesJsonPath: 'src/pages.json',
      pages: {
        pagesDir: 'src/pages',
        subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }],
        entryPage: 'pages/index/index',
        tabBar: { color: '#999999', selectedColor: '#42b883' }
      },
      router: {
        outputPath: 'src/router.config.ts',
        nameStrategy: 'camelCase',
        dts: 'src/router.d.ts'
      }
    })
  ]
})

页面配置可通过 defineUniPage 宏或页面内 <route-config> 自定义块就近声明，与 generatePages 完全一致。宏优先级高于 <route-config>，宏的全局类型声明由插件自动生成（pages.dts 可自定义路径），用法与 generatePages 的宏说明 一致：

<!-- src/pages/index/index.vue -->
<script setup lang="ts">
defineUniPage({
  title: '首页',
  isTab: true,
  tab: { order: 0 }
})
</script>

也可使用 <route-config> 自定义块（优先级低于宏，建议添加 lang="jsonc" 获得 IDE 高亮）：

<route-config lang="jsonc">
{
  "title": "首页",
  "isTab": true,
  "tab": { "order": 0 }
}
</route-config>

配置选项

选项	类型	默认值	说明
pagesJsonPath	string	'src/pages.json'	pages.json 文件路径（两阶段共用）
watch	boolean	true	监听页面目录变更自动重新执行整条流水线
pages	GeneratePagesOptions	{ pagesDir: 'src/pages', subPackages: [{ root: 'pages-sub', dir: 'src/pages-sub' }] }	阶段一参数：扫描页面 + <route-config> / defineUniPage 生成 pages.json（pagesDir / subPackages / routeConfigBlock / entryPage / titleFallback / tabBar / includeExtensions / excludePatterns / dts）
router	GenerateRouterOptions	{ outputPath: 'src/router.config.ts' }	阶段二参数：基于 pages.json 生成路由配置（outputPath / outputFormat / nameStrategy / metaMapping / exportTypes / preserveRouteChanges / headerTemplate / customFields / dts / includeSubPackages）

继承 BasePluginOptions：enabled、verbose、errorStrategy

pages / router 两个子对象支持对应独立插件的全部配置项，详细说明分别见 generatePages 与 generateRouter。

流水线说明

generateUni(options)
   │
   ├─ Phase 1（页面阶段）
   │    扫描页面目录 + <route-config> ──► 内存 pages 数据（pages/subPackages/tabBar）
   │    合并现有 pages.json（保留 globalStyle 等非页面字段）─► 写入 pages.json
   │                      │
   │                      └──► 内存 pages 对象（直传，不重新读盘）
   ▼
   ├─ Phase 2（路由阶段）
        parsePagesJson(pages 对象) ──► routes
        mergeRoutes（保留用户修改）──► router.config.ts（+ 可选 dts）

• pages.json 仍会写盘（uni() 与构建流程需要该文件），但路由阶段直接消费内存中的 pages 对象，不再读盘回灌
• 只用一个 watch 监听页面目录，变更时串行重跑「阶段一 + 阶段二」，避免并发读写竞态
• <route-config> 自定义块的虚拟模块请求会被插件拦截为空模块，避免构建时被当作 JavaScript 解析；defineUniPage 宏调用同样会在 transform 阶段被移除，运行时无需 import

从两个插件迁移

原使用 generatePages + generateRouter 的配置，等价替换为 generateUni：

// 之前
generatePages({ pagesDir: 'src/pages', entryPage: 'pages/index/index', tabBar: {...} }),
generateRouter({ outputPath: 'src/router.config.ts', nameStrategy: 'camelCase', dts: true })

// 之后
generateUni({
  pages: { pagesDir: 'src/pages', entryPage: 'pages/index/index', tabBar: {...} },
  router: { outputPath: 'src/router.config.ts', nameStrategy: 'camelCase', dts: true }
})

注意事项

• 顶层 pagesJsonPath / watch 会覆盖 pages 子对象中的同名配置
• 开发模式下监听主包与分包页面目录，新增 / 删除 / 修改页面自动重新生成 pages.json 与路由配置
• 阶段二的路由合并、类型声明等行为与 generateRouter 完全一致（含 preserveRouteChanges 保留用户修改）