配置

插件配置

插件配置写在 vite.config.ts 的 UniPages() 里。所有选项都可选。

vite.config.ts
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniPages({
      dir: 'src/pages',
      dts: true,
    }),
  ],
})

页面扫描

dts

dts
boolean | string
是否为页面路径生成 TypeScript 声明。为 true 时在项目根目录生成 uni-pages.d.ts。为字符串时作为相对项目根目录的输出路径。为 false 时关闭。

configSource

configSource
ConfigSource
页面配置文件的加载来源,基于 unconfig。按来源顺序加载第一个有效配置。支持字符串路径,也支持 unconfig 的 LoadConfigSource 对象或其数组。

homePage

homePage
string | string[]
默认应用入口页面。没有页面用 definePage({ type: 'home' }) 标记为首页时使用。支持多种路径写法,兼容不同的目录布局。

mergePages

mergePages
boolean
是否扫描目录并把页面配置合并进 pages.json。为 false 时只加载用户配置文件,不扫描文件系统。

dir

dir
string
主包页面的搜索目录。支持 glob,例如 'src/{pages,views}'。最终结果由 tinyglobby 解析成匹配到的目录列表。

subPackages

subPackages
(string | SubPackageConfig)[]
uni-app 分包的页面目录。支持字符串或对象形式的目录 glob。开发期间自动发现新增、删除、重命名的目录。对象形式的 root 可以用同步回调,按匹配到的目录计算。monorepo 中页面可能位于项目根目录之外。此时用对象形式指定出现在 pages.json 里的自定义 root,避免生成的 root 路径含 ..。见 issue #271。

outDir

outDir
string
pages.json 所在目录,相对项目根目录。它也是计算页面相对路径的基准。

exclude

exclude
string[]
排除的文件或目录模式。
  • 相对模式基于 Vite root,绝对模式直接匹配对应路径。命中目录时排除整个子树。
  • 主包、分包的扫描与页面事件使用同一套规则。
  • 自定义数组替换默认值。空数组禁用默认的页面排除,空字符串被忽略。
  • 不接受 !foo 这种否定规则,!(keep).vue 这类 extglob 有效。

生成结果

minify

minify
boolean
压缩生成的 pages.json。

insertFinalNewline

insertFinalNewline
boolean
是否在生成的 pages.json 末尾追加换行符。

indent

indent
number | string
生成文件的缩进,接受空格数或字符串(例如 '\t')。minify 为 true 时忽略。

eol

eol
'\n' | '\r\n'
生成文件的换行符。

调试

debug

debug
boolean | DebugType
启用调试日志。为 true 时启用所有分类,为字符串时只启用对应分类。可用分类:hmr、options、pages、subPages、error、cache、declaration、definePage。也可以用环境变量 DEBUG=vite-plugin-uni-pages:* 控制。

生命周期钩子

钩子在各流水线阶段触发。钩子只接收该阶段的输入或输出数据,不接收整个上下文。

钩子参数
onBeforeLoadUserConfig无
onAfterLoadUserConfigpagesGlobConfig: PagesConfig | undefined
onBeforeScanPages无
onAfterScanPagespages: Map<string, Page>, subPages: Map<string, Map<string, Page>>
onBeforeMergePageMetaDatapages: Map<string, Page>, pagesGlobConfig: PagesConfig | undefined
onAfterMergePageMetaDatapageMetaData: InternalPages, subPageMetaData: SubPackages
onBeforeWriteFilefilePath: string
onAfterWriteFilefilePath: string, content: string

提前生成

UniPages() 返回的插件实例带 prepare(),用来在其他插件读取 pages.json 之前先生成文件。详见扩展。

感谢