uni-app：5 步接入 vite-plugin-uni-pages，用 <route> 自动生成 pages.json

装插件 → vite.config.ts 启用 → pages.config.ts 写全局 → 页面用 写局部 → 运行看到生成物。

@uni-helper/vite-plugin-uni-pages

@uni-helper/vite-plugin-uni-pages 的核心作用是：扫描页面文件 + 解析每个页面里的 <route> 自定义块，再结合 pages.config.ts 的全局配置，自动生成 src/pages.json。

uni-app 会基于 src/pages.json 进一步编译输出各个平台所需的页面配置文件（例如页面对应的 *.json）。

一句话总结：它负责"从 pages.config.ts + 各页面 .vue 的 <route lang="json5"> 汇总生成 src/pages.json"，让页面配置可以就近维护在页面文件里。

---

1）安装依赖

一般安装到开发依赖（devDependencies）：

pnpm add -D @uni-helper/vite-plugin-uni-pages

---

2）在 vite.config.ts 里启用插件（注意顺序）

UniPages() 建议放在 Uni() 之前：

// vite.config.ts

plugins: [

  UniPages({

    routeBlockLang: 'json5',

  }),

  Uni(),

]

• routeBlockLang: 'json5'：表示页面里的 <route lang="json5"> 会按 JSON5 解析（支持注释等）。

---

3）提供全局配置入口：pages.config.ts（推荐）

    用 defineUniPages() 统一维护全局配置（如 globalStyle、tabBar、easycom 等）：

// pages.config.ts

import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({

  globalStyle: {

    backgroundTextStyle: 'light',

    navigationBarBackgroundColor: '#FFDDD3',

    navigationBarTitleText: '',

    navigationBarTextStyle: 'black',

    'mp-weixin': {

      navigationStyle: 'custom',

    },

    'mp-toutiao': {

      transparentTitle: 'always',

    },

  },

  // ... tabBar / easycom ...

})

插件会把这里的全局配置与每个页面 <route> 的页面配置合并，生成 src/pages.json。

---

4）页面里怎么写 <route>

在页面 .vue 顶部写 <route>，通常配置该页的 style：

<route lang="json5" type="home">

{

  style: {

    "enableShareAppMessage": true,

    "enableShareTimeline": true,

  },

}

</route>

• 真正影响小程序行为的是 style 里的配置（例如微信分享开关）。

• type="home" 这类字段更多是你的工程/插件生成用的元信息，不是 uni-app 标准必须项。

---

5）运行查看效果

pnpm dev:mp-weixin

# 或

pnpm dev:mp-toutiao

• 开发时：会生成/更新 src/pages.json

• 构建后：会在 dist/.../<platform>/pages/**/**.json 看到对应页面的配置输出（例如 pages/xxx/xxxx.json）