Vite Plugin Uni Pages

Appearance

常见问题 ​

插件启动晚于 uni-app 读取 pages.json ​

@dcloudio/vite-plugin-uni 在 Vite 的 config 钩子里通过 parsePagesJsonOnce 读取 pages.json，本插件在更晚的 configResolved 钩子里才写入。config 早于 configResolved，所以即使本插件设置了 enforce: 'pre'，也无法抢在 uni-app 前面。

读取结果会被 once 缓存，首次读取后不再变化。核心矛盾是时序：必须在 uni-app 进程启动前把 pages.json 生成好。

推荐使用 @uni-helper/unh。它在调用 uni dev 或 uni build 前加载配置、扫描页面并写盘，再启动子进程：

jsonc
// package.json
{
  "scripts": {
    "dev": "unh dev",
    "build": "unh build"
  }
}
ts
// unh.config.ts
import { defineConfig } from '@uni-helper/unh'

export default defineConfig({
  autoGenerate: {
    pages: true,
  },
})

也可以自行编写脚本，在 uni 命令前生成 pages.json 并用 && 或 predev、prebuild 串联。脚本需要复刻完整的加载、扫描和合并流程，维护成本较高。

prepare() 面向的是在工厂函数里读取 pages.json 的下游插件。它是否满足你的启动方式，需要在真实项目中验证。见 prepare()。

definePage is not defined ​

definePage 是构建期宏，插件会在转换阶段删掉调用。出现这个错误通常有两个原因：

  • 宏调用被包在 if、try 等语句块里，插件只查找 script 块的顶层语句
  • 页面文件解析失败，宏没能被识别和移除

把调用移到 script 块顶层，并检查构建输出里的解析警告。

支持 JSX/TSX 吗 ​

不支持。页面文件只支持 .vue、.nvue、.uvue。

文件名可以用多个点吗 ​

不能。index.v1.vue 这类文件名不合法。这是小程序的限制，不是本插件的限制。平台后缀页面（如 index.h5.vue）是例外，只在启用 @uni-helper/vite-plugin-uni-platform 时使用。

如何自动发现分包 ​

subPackages 的字符串和对象 dir 都支持 glob，详见分包。简单的例子：

ts
UniPages({
  subPackages: ['src/packages/*/pages'],
})

monorepo 中 root 出现 .. ​

使用 subPackages 的对象形式指定 root：

ts
UniPages({
  subPackages: [{
    dir: '../../packages/login/src/pages',
    root: 'packages/login/src/pages',
  }],
})

更多细节见分包。

多个终端同时开发 ​

插件用文件锁和 #ifdef 条件编译块让各平台的配置共存。注意 tabBar 顺序和格式化设置的一致性，详见多平台与条件编译。

提示 No home page found ​

插件没有找到首页。检查：

  • homePage 配置是否符合目录布局
  • 页面是否写了 definePage({ type: 'home' })
  • pages.config.ts 的 pages 条目是否包含正确的 path

这个警告不影响生成，但首页顺序可能不是你期望的。

UNI_PLATFORM must be set ​

插件初始化时读取 process.env.UNI_PLATFORM。直接运行 Vite 或独立脚本时，需要先设置平台：

shell
UNI_PLATFORM=h5 vite

pages.json 是占位文件 ​

pages.json 不存在且推导出的输出目录已经存在时，插件会创建一个占位文件。Vite 初始化后会完整生成，覆盖占位内容。

如果目录推导不出来，插件不会创建任何文件。此时检查 root 和 outDir。

pages.json 不可读写 ​

已存在的 pages.json 不是普通文件或缺少权限时，插件会报错并停止。修复权限：

shell
chmod u+w src/pages.json

如果是目录或其他类型，确认不需要后手动删除。

想重置生成标记 ​

不要手动编辑 // GENERATED BY UNI-PAGES, PLATFORM: ...。删除整个 pages.json，下次运行会从零生成。详见多平台与条件编译。

编辑器不认识 definePage 或 virtual:uni-pages ​

引用 /client 类型：

ts
/// <reference types="@uni-helper/vite-plugin-uni-pages/client" />

或者在 tsconfig.json 的 types 中加入 @uni-helper/vite-plugin-uni-pages/client。

修改页面后 pages.json 没更新 ​

按顺序检查：

  • 文件是否在 dir 或 subPackages 的扫描范围内
  • 文件是否被 exclude 排除，H5 开发时是否被 Vite 的 server.watch.ignored 排除
  • 页面内容是否真的改变了元数据，只改模板不会重新生成
  • 终端是否输出了解析或写入错误

页面元数据没变时，插件会跳过生成，这是预期行为。