uni-ku/root
工具借助 Vite 模拟虚拟根组件（App.ku.vue），解决 uni-app Vue3 项目无法使用全局共享组件的问题。支持自定义组件命名、PageMeta 自动提升、nvue 页面兼容。
Vite 插件uni-app全局组件Vue 3构建工具uni-helper
详细文档
uni-ku/root#
平台概述#
uni-ku/root 是一个 Vite 插件，通过模拟虚拟根组件（App.ku.vue）解决 uni-app Vue3 项目中无法使用全局共享组件的核心痛点。
核心价值：uni-app 的架构限制导致每个页面都是独立的 Vue 实例，开发者无法像标准 Vue 应用那样在根组件（App.vue）中注册全局 Provider、布局组件、全局弹窗等。本插件通过 Vite 编译阶段注入虚拟包裹组件，使开发者可以在 App.ku.vue 中定义全局逻辑和组件，自动应用到所有页面。
项目数据（2026-08-04 核实）：
- GitHub：170⭐ / 12 forks / MIT License
- npm：
@uni-ku/rootv1.5.0，22 个版本（2024-07 至今） - 最近活跃：2026-07-25（v1.5.0 发布）
- 主要维护者：skiyee（97 contributions）
- License：MIT
设计规范#
虚拟根组件架构#
插件在编译阶段为每个页面自动注入一个虚拟包裹组件（App.ku.vue），其结构如下：
App.ku.vue（虚拟根组件）
├── 全局 Provider / 注入
├── 全局布局组件
├── <KuRootView />（页面内容插槽）
└── 全局弹窗 / 浮层
核心特性#
| 特性 | 说明 |
|---|---|
| 自定义根组件命名 | 默认 App.ku.vue，可通过 rootFileName 配置 |
| KuRootView 标签 | 类似 RouterView，标记页面内容插入位置 |
| PageMeta 自动提升 | 自动将 PageMeta 组件提升到页面顶层（阻止滚动穿透） |
| nvue 兼容 | 支持 nvue 页面使用虚拟根组件 |
| 组合式 API | 提供 useKuRootRef() 等 Composition 方法获取根组件实例 |
与标准 Vue 根组件的区别#
| 特性 | 标准 Vue App.vue | uni-app + uni-ku/root |
|---|---|---|
| 全局 Provider | ✅ 直接使用 | ✅ 通过 App.ku.vue |
| 全局布局 | ✅ 直接使用 | ✅ 通过 App.ku.vue |
| 路由切换感知 | ✅ VueRouter | ❌ 需手动处理 |
| 页面独立 Vue 实例 | ❌ 单实例 | ✅ 每页独立（uni-app 限制） |
审核规范#
不涉及（构建工具，不影响审核流程）。
开发指南#
快速上手#
# 安装
pnpm add -D @uni-ku/root
// vite.config.ts
import { defineConfig } from 'vite'
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
export default defineConfig({
plugins: [
UniKuRoot(), // 建议放置在 Uni() 之前
Uni(),
],
})
<!-- src/App.ku.vue -->
<script setup lang="ts">
import { ref, provide } from 'vue'
import GlobalNav from '@/components/global-nav.vue'
import GlobalModal from '@/components/global-modal.vue'
// 全局状态注入
const globalTheme = ref<'light' | 'dark'>('light')
provide('theme', globalTheme)
</script>
<template>
<!-- 全局导航栏，所有页面自动显示 -->
<GlobalNav />
<!-- 页面内容插槽（必须有且仅有一个） -->
<KuRootView />
<!-- 全局弹窗 -->
<GlobalModal />
</template>
高级配置#
// vite.config.ts - 自定义配置
UniKuRoot({
// 自定义虚拟根组件文件名（默认：App.ku.vue）
rootFileName: 'KuRoot',
// 自定义 KuRootView 标签名
rootTag: 'root-view',
})
常见陷阱#
- KuRootView 唯一性：每个 App.ku.vue 中必须有且仅有一个
<KuRootView />标签，否则编译报错 - 插件顺序：
UniKuRoot()建议在Uni()之前调用，尤其当存在其他修改pages.json的插件时 - 不支持 VueRouter：uni-app 没有VueRouter，因此 KuRootView 不等同于 RouterView，页面切换由 uni-app 路由 API 控制
- HBuilderX 项目：需在项目根目录创建
vite.config.ts（HBuilderX 项目默认无此文件） - nvue 注意事项：nvue 页面的 KuRootView 仅支持 nvue 兼容的组件
与 uni-helper 生态配合#
uni-ku/root 与以下 uni-helper 工具配合使用效果最佳：
| 工具 | 说明 |
|---|---|
| vite-plugin-uni-pages | 文件路由自动生成 pages.json |
| create-uni | 快速创建 uni-app 项目（内置可选 uni-ku/root） |
| uni-use | Vue 3 组合式工具集 |
| unocss-preset-uni | uni-app UnoCSS 预设 |
生态资源#
解决的问题#
uni-app Vue3 中全局组件的历史痛点：
- ❌ 无法在所有页面共享 Provider（如主题、国际化、用户状态）
- ❌ 无法在所有页面自动渲染全局 UI（如导航栏、底部 Tab、悬浮按钮）
- ❌ 无法统一处理全局弹窗、Toast、Loading
- ✅ uni-ku/root 通过编译时注入解决以上所有问题
社区资源#
- GitHub 仓库：uni-ku/root
- npm 包：@uni-ku/root
- 作者技术支持：QQ 319619193（付费定制开发）
版本更新#
当前版本（2026-08-04 核实）#
- npm 最新：v1.5.0（22 个版本，2024-07 至今）
- GitHub：170⭐ / 12 forks / 2 open issues / 5 contributors
- 维护状态：活跃（2026-07-25 最后推送，v1.5.0 发布）
- License：MIT
版本历史要点#
- v1.5.0（2026-07-25）：最新版本，功能完善
- v1.4.x（2025-09）：nvue 支持、组合式 API 增强
- v1.0.0（2024-07）：初始发布，核心虚拟根组件功能
核实记录#
- 2026-08-04：GitHub API + npm registry 核实，170⭐ / v1.5.0 / 22 versions / MIT / 最后推送 2026-07-25，状态活跃
