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

华玥作者2026-01-16 12:18

文章目录

前言

在 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。 ✅

相关推荐
m0_748254662 小时前
HTML 文本格式化基础
前端·html
十六年开源服务商2 小时前
WordPress集成GoogleAnalytics最佳实践指南
前端·人工智能·机器学习
狼性书生2 小时前
uniapp+vue3实现的简单吐司通知弹窗组件
前端·uni-app·vue·组件·插件
克里斯蒂亚诺更新2 小时前
使用elementUI的表格报错ResizeObserver loop completed with undelivered notifications.
前端·javascript·elementui
陈随易2 小时前
Vue-Router v5内置文件式路由，告别手写维护的恐惧
前端·后端·程序员
C_心欲无痕2 小时前
移动端 B 站弹幕功能实现
前端·javascript
Amumu121382 小时前
Redux介绍(二)
前端·react.js
菜鸟很沉2 小时前
Vue 3 组件双向绑定完全指南：update:modelValue 与 defineModel
前端·javascript·vue.js
C_心欲无痕2 小时前
使用 FNM (Fast Node Manager) 管理多个 Node.js 版本
前端·node.js
热门推荐
01GitHub 镜像站点02Linux下V2Ray安装配置指南03AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南04Labelme从安装到标注：零基础完整指南05Claude Code Skills 实用使用手册06UV安装并设置国内源07网站改了域名，如何查找？08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09百度网盘偷偷给电脑“降频”？102025年大语言模型技术全景报告