vite-plugin-uni-pages

vite-plugin-uni-pages#

平台概述#

vite-plugin-uni-pages 是 uni-helper 社区组织维护的开源 Vite 插件，为 uni-app 项目提供基于文件系统的自动路由（File System Based Routing）能力。

核心价值：在 uni-app 开发中，pages.json 是路由配置的核心文件，需要手动维护页面路径、导航栏样式、tabBar 配置等。随着项目规模增长，pages.json 变得冗长且易错。本插件通过文件系统结构自动生成 pages.json，开发者只需按约定创建页面文件即可。

项目数据（2026-07-25 核实）：

GitHub：204⭐ / 34 forks / MIT License
npm：@uni-helper/vite-plugin-uni-pages v0.4.7，79 个版本（2022-11 至今）
最近活跃：2026-07-21（持续维护）
官方文档：uni-helper.js.org/vite-plugin-uni-pages
AI 辅助文档：支持 DeepWiki 和 Zread 问答

设计规范#

文件路由约定#

文件路径	生成路由
`src/pages/index.vue`	`/pages/index/index`
`src/pages/about.vue`	`/pages/about/about`
`src/pages/user/[id].vue`	`/pages/user/index`（动态参数 `id`）
`src/pages/blog/[...all].vue`	`/pages/blog/index`（catch-all 路由）

页面元信息配置#

通过 <route> 代码块在 SFC 中直接声明页面配置：

code

<route lang="json">
{
  "style": {
    "navigationBarTitleText": "首页"
  },
  "needLogin": true
}
</route>

也可使用 route.config.ts 文件进行 TypeScript 类型安全的配置。

分包支持#

通过目录约定自动识别分包：

src/pages-sub/package-a/ 下的页面自动生成为分包
支持自定义分包根路径配置

审核规范#

不涉及（构建工具，不影响审核流程）。

开发指南#

快速上手#

code

# 安装
pnpm i -D @uni-helper/vite-plugin-uni-pages

code

// vite.config.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(), // 必须在 Uni() 之前调用
    Uni(),
  ],
})

code

// pages.config.ts（可选，全局配置）
import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({
  pages: [],
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarTitleText: 'My App',
  },
  tabBar: {
    list: [
      { pagePath: 'pages/index/index', text: '首页' },
      { pagePath: 'pages/about/about', text: '关于' },
    ],
  },
})

TypeScript 支持#

插件内置 TypeScript 类型定义，pages.config.ts 和 <route lang="json"> 均支持类型提示。可通过 UniPages.pageMeta 获取当前页面元信息。

常见陷阱#

插件顺序：UniPages() 必须在 Uni() 之前调用，否则路由生成不生效
pages.json 被覆盖：插件会自动生成 pages.json，不要手动编辑（会被覆盖），使用 pages.config.ts 做全局配置
HBuilderX 项目不适用：本插件仅适用于 Vite 驱动的 uni-app 项目（Vue 3），不支持 HBuilderX 创建的 CLI 项目
动态路由参数：[id].vue 中的 id 参数通过 onLoad(options) 获取，不是 Vue Router 的 useRoute()

与 uni-app 原生路由的区别#

特性	uni-app 原生	vite-plugin-uni-pages
路由注册	手动编辑 pages.json	文件系统自动生成
动态路由	不支持	支持 `[id].vue` 语法
页面配置	pages.json 中每页 style 字段	`<route>` 块或 `route.config.ts`
类型安全	无	TypeScript 类型提示
分包管理	手动配置 subPackages	目录约定自动识别

生态资源#

同组织工具（uni-helper）#

项目	说明
create-uni	快速创建 uni-app 项目脚手架（301⭐）
uni-network	基于 Promise 的 HTTP 客户端（127⭐）
uni-use	Vue 3 组合式工具集（182⭐）
unocss-preset-uni	uni-app 专用 UnoCSS 预设（125⭐）
vite-plugin-uni-layouts	uni-app 布局系统插件（66⭐）
vitesse-uni-app	uni-app + Vite 快速启动模板（567⭐）
axios-adapter	uni-app axios 适配器（58⭐）

配合使用的工具#

weapp-tailwindcss：原子化 CSS 方案，与本插件互补
unocss-applet：UnoCSS 小程序兼容层
uni-typed：uni-app 组件 TypeScript 类型支持

社区资源#

官方文档：uni-helper.js.org
GitHub Discussions：问题讨论与功能建议
DeepWiki AI：deepwiki.com/uni-helper/vite-plugin-uni-pages

版本更新#

当前版本（2026-07-25 核实）#

npm 最新：v0.4.7（79 个版本，2022-11 至 2026-07）
GitHub：204⭐ / 34 forks / 1 open issue
维护状态：活跃（2026-07-21 最后推送）
License：MIT

版本历史#

插件自 2022-11-14 创建，持续迭代至今
79 个 npm 版本，平均每月 2-3 个版本
uni-helper 组织同时维护 10+ 个 uni-app 生态工具

核实记录#

2026-07-25：GitHub API + npm registry 核实，204⭐ / v0.4.7 / 79 versions / MIT / 最后推送 2026-07-21，状态活跃

详细文档