uni-app + Vite 项目中使用 @uni-helper/vite-plugin-uni-pages 实现自动路由配置（超详细）

文章目录

前言
一、插件简介
- 核心能力
二、适用项目技术栈
三、安装插件
四、项目目录结构推荐
[五、在 Vite 中配置插件](#五、在 Vite 中配置插件)
- [vite.config.ts 示例](#vite.config.ts 示例)
- [:warning: 注意事项](#:warning: 注意事项)
[六、使用 pages.config.ts 管理页面](#六、使用 pages.config.ts 管理页面)
- [:one:创建 pages.config.ts](#:one:创建 pages.config.ts)
- :two:自动扫描页面（推荐方式）
七、分包（subPackages）配置
- [pages.config.ts 示例](#pages.config.ts 示例)
八、页面级配置的两种方式
- [方式一：集中写在 pages.config.ts](#方式一：集中写在 pages.config.ts)
- [方式二：页面内 definePageMeta（强烈推荐）](#方式二：页面内 definePageMeta（强烈推荐）)
九、统一配置所有页面（高频需求）
- 示例：关闭所有页面下拉刷新
十、指定页面配置导航栏按钮
十一、作者在使用安装时候遇到的问题
- [:one: 老项目安装提示`require() of ES Module`](#:one: 老项目安装提示require() of ES Module)
- - :bug:报错内容
  - :interrobang:解释原因
  - [:100:解决方法：在 package.json 里加一行](#:100:解决方法：在 package.json 里加一行)
- [:two: 提示Uni is not a function](#:two: 提示Uni is not a function)
- - :bug:报错内容
  - [:100:解决方法: 使用`@uni-helper/plugin-uni`插件](#:100:解决方法: 使用@uni-helper/plugin-uni插件)
- [:three: 页面路径被生成两次？](#:three: 页面路径被生成两次？)
- 结尾

前言

在 uni-app 项目中，pages.json 一直是一个绕不开但又非常繁琐的配置文件：

新增页面要手动加路径

删除页面容易忘记同步

分包配置复杂、路径容易写错

页面一多，维护成本直线上升

在项目规模逐渐变大之后，这种手工维护路由配置的方式已经明显不适合团队协作。

本文将介绍一款在 uni-app + Vite 技术栈中非常好用的插件：

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

通过它，可以实现：

目录即路由
自动生成 pages.json
支持分包、全局配置、页面级配置
极大降低页面维护成本

一、插件简介

@uni-helper/vite-plugin-uni-pages是 Uni Helper 团队推出的一款基于 Vite 的页面路由自动生成插件，专门为 uni-app 生态设计。

核心能力

🚀 自动扫描 src/pages 目录生成路由
🥚 原生支持 subPackages（分包）
📘 支持 pages.config.ts 集中管理
⛺️ 支持 definePageMeta 页面内配置
💡 TypeScript 友好

一句话总结：

把 pages.json 交给插件，把精力留给业务开发

二、适用项目技术栈

本文示例基于以下环境：

uni-app
Vue 3
TypeScript
Vite
pnpm（npm / yarn 同理）

三、安装插件

bash 复制代码

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

安装完成后无需额外 CLI 操作，直接在 Vite 中配置即可。

四、项目目录结构推荐

txt 复制代码

src/
├─ pages/
│  ├─ index/
│  │  └─ index.vue
│  ├─ login/
│  │  └─ index.vue
│  └─ mine/
│     └─ index.vue
├─ sub-packages/
│  └─ order/
│     ├─ pages/
│     │  └─ detail.vue
│     └─ pages.config.ts
└─ pages.config.ts

说明

pages：主包页面
sub-packages：分包目录
pages.config.ts：替代 pages.json 的配置文件

五、在 Vite 中配置插件

vite.config.ts 示例

ts 复制代码

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'

export default defineConfig({
  plugins: [
    UniPages({
      configPath: 'src/pages.config.ts',
      pagesJsonPath: 'src/pages.json',
      mergePages: true
    }),
    uni()
  ]
})

⚠️ 注意事项

插件必须放在 uni() 之前
pages.json 会自动生成，无需手写

六、使用 pages.config.ts 管理页面

1️⃣创建 pages.config.ts

ts 复制代码

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

export default defineUniPages({
  pages: [
    {
      path: 'pages/index/index',
      style: {
        navigationBarTitleText: '首页'
      }
    }
  ]
})

2️⃣自动扫描页面（推荐方式）

如果你希望完全不写 pages 配置，可以只保留全局样式：

ts 复制代码

export default defineUniPages({
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarBackgroundColor: '#ffffff',
    backgroundColor: '#f8f8f8'
  }
})

插件会自动扫描：

txt 复制代码

src/pages/**/**.vue

并生成对应路由。

七、分包（subPackages）配置

pages.config.ts 示例

ts 复制代码

export default defineUniPages({
  subPackages: [
    {
      root: 'sub-packages/order',
      pages: [
        {
          path: 'pages/detail',
          style: {
            navigationBarTitleText: '订单详情'
          }
        }
      ]
    }
  ]
})

对应目录结构

txt 复制代码

src/sub-packages/order/pages/detail.vue

八、页面级配置的两种方式

方式一：集中写在 pages.config.ts

ts 复制代码

{
  path: 'pages/login/index',
  style: {
    navigationBarTitleText: '登录',
    enablePullDownRefresh: false
  }
}

方式二：页面内 definePageMeta（强烈推荐）

html 复制代码

<script setup lang="ts">
definePageMeta({
  navigationBarTitleText: '个人中心',
  enablePullDownRefresh: false
})
</script>

为什么推荐这种方式？

页面配置与页面代码在一起
删除页面不会残留配置
可维护性更高

九、统一配置所有页面（高频需求）

示例：关闭所有页面下拉刷新

ts 复制代码

export default defineUniPages({
  globalStyle: {
    enablePullDownRefresh: false
  }
})

十、指定页面配置导航栏按钮

1️⃣封装功能方法抽离`userOptions`

ts 复制代码

// composables/useUniPages.ts
import type { PageContext } from '@uni-helper/vite-plugin-uni-pages'

export const useUniPages = {
    exclude: ['**/components/**/**.*'],
    subPackages: ['src/pages-design'],
    onBeforeWriteFile(ctx: PageContext) {
        ctx.subPageMetaData.forEach((item) => {
            if (item.root === 'pages-design') {
                item.pages.forEach((p) => {
                    if (!p.style) p.style = {}
                    p.style.h5 = {
                        titleNView: {
                            buttons: [{ type: 'share', color: '#892FE8' }]
                        }
                    }
                })
            }
        })
    }
}

2️⃣引入

ts 复制代码

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

export default defineConfig({
  plugins: [
    UniPages(useUniPages),
    uni()
  ]
})

以下功能看情况是否封装👇

3️⃣封装公共点击事件处理

ts 复制代码

import { onNavigationBarButtonTap } from '@dcloudio/uni-app'

export function useNavButton() {
    onNavigationBarButtonTap((e: Page.NavigationBarButtonTapOption) => {
        // 执行点击页面方法
    })
}

4️⃣页面调用方法

html 复制代码

<script setup lang="ts">
import { useNavButton} from '@/composables';

useNavButton();
</script>

十一、作者在使用安装时候遇到的问题

1️⃣ 老项目安装提示`require() of ES Module`

🐛报错内容

txt 复制代码

failed to load config from E:\project\my\uniapp\hy-design-uni\vite.config.ts
error when starting dev server:
Error [ERR_REQUIRE_ESM]: require() of ES Module E:\project\my\uniapp\hy-design-uni\node_modules\.pnpm\unconfig@7.4.2\node_modules\unconfig\dist\index.mjs not supported.
Instead change the require of E:\project\my\uniapp\hy-design-uni\node_modules\.pnpm\unconfig@7.4.2\node_modules\unconfig\dist\index.mjs to a dynamic import() which is available in all CommonJS modules.

⁉️解释原因

Vite 在启动时试图用 CommonJS 的 require() 去加载一个纯 ESM 包（unconfig），而 Node 不允许这么做，于是抛出了 ERR_REQUIRE_ESM。

💯解决方法：在 package.json 里加一行

ts 复制代码

"type": "module"

2️⃣ 提示Uni is not a function

🐛报错内容

💯解决方法: 使用`@uni-helper/plugin-uni`插件

下载@uni-helper/plugin-uni

bash 复制代码

pnpm i -D @uni-helper/plugin-uni

ts 复制代码

// 需要把
import uni from '@dcloudio/vite-plugin-uni'
// 改成
import Uni from '@uni-helper/plugin-uni'

⚠️注意：官方插件 @dcloudio/vite-plugin-uni不要卸载，因为这个包是依赖官方插件二次封装的，否则@uni-helper/plugin-uni插件将无法正常工作。

3️⃣ 页面路径被生成两次？

原因：

手写了 pages
同时又开启了自动扫描

建议：

要么全自动
要么集中手写
不要混用

结尾

如果你觉得这篇文章帮你解决了你现在的问题，那就请给我来个三连支持一下 ♥️

➡️ 点赞支持一下

➡️ 收藏以防找不到

➡️ 评论我会回访你！

➡️ 关注不会迷路哦！

你的支持是我持续更新的动力，我们下篇更精彩！🚀🔥

参考github项目地址：hy-design-uni

👉 欢迎大家给华玥组件库star。 ✅

uni-app + Vite 项目中使用 @uni-helper/vite-plugin-uni-pages 实现自动路由配置（超详细）

文章目录

前言

一、插件简介

核心能力

二、适用项目技术栈

三、安装插件

四、项目目录结构推荐

五、在 Vite 中配置插件

vite.config.ts 示例

⚠️ 注意事项

六、使用 pages.config.ts 管理页面

1️⃣创建 pages.config.ts

2️⃣自动扫描页面（推荐方式）

七、分包（subPackages）配置

pages.config.ts 示例

八、页面级配置的两种方式

方式一：集中写在 pages.config.ts

方式二：页面内 definePageMeta（强烈推荐）

九、统一配置所有页面（高频需求）

示例：关闭所有页面下拉刷新

十、指定页面配置导航栏按钮

1️⃣封装功能方法抽离userOptions

2️⃣引入

3️⃣封装公共点击事件处理

4️⃣页面调用方法

十一、作者在使用安装时候遇到的问题

1️⃣ 老项目安装提示require() of ES Module

🐛报错内容

⁉️解释原因

💯解决方法：在 package.json 里加一行

2️⃣ 提示Uni is not a function

🐛报错内容

💯解决方法: 使用@uni-helper/plugin-uni插件

3️⃣ 页面路径被生成两次？

结尾

1️⃣封装功能方法抽离`userOptions`

1️⃣ 老项目安装提示`require() of ES Module`

💯解决方法: 使用`@uni-helper/plugin-uni`插件