uni-app 也能像 Vue 一样用 App.vue 了？这款插件做到了！

你是不是像我在App.vue写了toast，一次一次找不到为啥弹不出来。 留着汗水默默敲下键盘，老板不是我做不出，以前在Vue里就是这样写的，是这个 uni-app 它毁谤我啊！

---

🌱 痛点：uni-app 没有“根组件”

在传统的 Vue3 项目中，我们把全局共享的组件（Toast、Loading、LoginModal 等）直接放在 App.vue 里即可，所有页面都能访问。但 uni-app 因为架构限制，没有真正意义上的根组件，导致：

• ❌ App.vue 不支持 <template> 块
• ❌ 无法全局挂载组件，只能每个页面手动引入
• ❌ 难以实现全局状态共享（如主题、弹窗）

🚑 解决方案：@uni-ku/root

@uni-ku/root 通过 Vite 插件“虚拟”出一个根组件，让 uni-app 也能像 Vue 一样使用 App.vue！

• ✅ 支持 Vue SFC（单文件组件）
• ✅ 支持热更新
• ✅ 自动处理小程序 PageMeta
• ✅ 支持 CLI & HBuilderX 双模式

---

🚀 三步上手

1. 安装

pnpm add -D @uni-ku/root@latest

2. 配置 vite

// vite.config.ts
import { defineConfig } from 'vite'
import UniKuRoot from '@uni-ku/root'

export default defineConfig({
  plugins: [UniKuRoot()] // 放最前面
})

3. 创建 App.ku.vue

<!-- CLI 放 src/App.ku.vue，HBuilderX 放根目录 -->
<script setup lang="ts">
import GlobalToast from '@/components/GlobalToast.vue'
</script>

<template>
  <KuRootView />       <!-- 相当于 RouterView -->
  <GlobalToast />      <!-- 任意全局组件 -->
</template>

---

✨ 实战：全局 Toast 弹窗

1. 编写组件

<!-- src/components/GlobalToast.vue -->
<script setup lang="ts">
import { useToast } from '@/composables/useToast'
const { globalToastState, hideToast } = useToast()
</script>

<template>
  <div v-if="globalToastState" class="toast-wrapper" @click="hideToast">
    <div class="toast-box">Hello @uni-ku/root!</div>
  </div>
</template>

2. 组合式 API

// src/composables/useToast.ts
import { ref } from 'vue'
const globalToastState = ref(false)

export function useToast() {
  return {
    globalToastState,
    showToast: () => (globalToastState.value = true),
    hideToast: () => (globalToastState.value = false),
  }
}

3. 页面调用

<script setup lang="ts">
import { useToast } from '@/composables/useToast'
const { showToast } = useToast()
</script>

<template>
  <button @click="showToast">弹出 Toast</button>
</template>

---

🎨 更多玩法

场景	做法示例
全局主题切换	在 App.ku.vue 包裹 <wd-config-provider>（Wot UI）
全局 Loading	放置 <GlobalLoading /> 并通过 useLoading() 控制
全局登录弹窗	放置 <LoginModal /> 并通过 useLogin() 控制

---

🤔 与 uni-helper-layouts 的区别？

特性	@uni-ku/root	@uni-helper/vite-plugin-uni-layouts
定位	虚拟根组件（App.vue 级）	类 Nuxt 的 layouts 系统
自由度	高（任意布局 + 逻辑）	中等（固定 header/main/footer）
支持 PageMeta	✅	❌
支持模板引用	✅ 局部 / 全局	✅ 仅局部

---

📦 开源信息

• GitHub：uni-ku/root
• NPM：@uni-ku/root
• 协议：MIT
• 交流群：QQ 976866565

---

🏁 结语

如果你厌倦了在 uni-app 里“每个页面 import 一遍 Toast”，@uni-ku/root 将是你的救星。点个 ⭐ 支持 @uni-ku/root 的作者，一起在 uni-app 里写出更优雅的 Vue3 代码吧！我们未来也将会在 WotDemo 中提供 @uni-ku/root 接入示例，敬请期待。