扩展

通过一些示例来满足你的项目需求

钩子按阶段逐个接收参数,不接收上下文对象。参数清单见配置。

排除页面

exclude 无法排除某些页面时,可以用 onAfterScanPages 过滤扫描结果。

该钩子接收两个 Map:主包页面与分包页面。删除 Map 里的键即可排除页面。

import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { scanPageFilter } from './builds/util.js'

export default defineConfig({
  plugins: [
    UniPages({
      onAfterScanPages: (pages, subPages) => {
        scanPageFilter(pages)
        for (const pages of subPages.values())
          scanPageFilter(pages)
      },
    })
  ],
})

路由唯一标识

路由需要唯一标识 name 时,可以用 onAfterMergePageMetaData 自动生成,不用逐页手写。

该钩子接收合并后的主包页面数组与分包数据。

import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { handlePageName } from './builds/util.js'

export default defineConfig({
  plugins: [
    UniPages({
      onAfterMergePageMetaData: (pageMetaData, subPageMetaData) => {
        handlePageName(pageMetaData)
        for (const subPackage of subPageMetaData)
          handlePageName(subPackage.pages)
      },
    })
  ],
})

路径常量化

把页面路径生成常量模块,避免在业务代码里硬编码字符串。

用 onAfterWriteFile 写文件。该钩子接收 filePath 与 content 两个参数,此时 pages.json 已经写好。

import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'
import { writePageConst } from './builds/util.js'

export default defineConfig({
  plugins: [
    UniPages({
      onAfterWriteFile: (_filePath, content) => {
        writePageConst(content)
      },
    })
  ],
})

提前生成 pages.json

UniPages() 返回的插件实例带 prepare()。它等待页面配置与已启用的声明文件生成,然后返回同一个实例。

prepare() 用于下游插件需要读取 pages.json 的场景,例如 vite-plugin-uni-middleware 或 uni-app 自己的启动流程。

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

export default defineConfig({
  plugins: [
    await UniPages().prepare({ platformSuffix: true }),
    Uni(),
  ],
})

prepare() 的选项:

选项类型说明
rootstringVite 项目根目录,相对路径以当前工作目录为基准。默认 process.env.VITE_ROOT_DIR || process.cwd()。
platformSuffixboolean是否采用 vite-plugin-uni-platform 的文件名后缀规则。必须与最终插件列表一致。

几个约束:

  • 使用调用时的 UNI_PLATFORM。根目录、平台与后缀规则必须与 Vite 初始化一致。
  • 相同参数的并发或重复调用共享结果,首次 Vite 接管时复用该结果。
  • Vite 会话关闭后再次调用会重新生成。成功准备过的根目录、平台与后缀约束持续有效。
  • 参数冲突、编译平台缺失、实例正在关闭或生成失败时,返回的 Promise 被拒绝。