常见问题

Root 使用过程中常见问题及解决方案

本文档收集了用户在使用 Root 过程中遇到的常见问题及其解决方案。如果您遇到的问题没有在此列出，请查看 GitHub Issues 或提交新的问题。

基础问题

Q: Root 是什么？它解决了什么问题？

A: Root 是一个专为 Uniapp 生态设计的工具，它通过 Vite 模拟出虚拟根组件（支持 SFC 的 App.vue），有效解决了 Uniapp 无法使用公共组件的问题。在标准的 Vue 应用中，我们可以在 App.vue 中定义全局组件和布局，但在 Uniapp 中，由于框架限制，无法直接实现这一点。Root 通过虚拟根组件的方式，让开发者可以在 Uniapp 中实现类似的功能。

Q: Root 支持哪些 Uniapp 项目？

A: Root 支持 HBuilderX 或者 CLI 创建的 Uniapp Vue3 项目。它不支持 Vue2 项目，因为其实现依赖于 Vue3 的特性。

Q: Root 是否会影响应用性能？

A: Root 的设计非常轻量，对应用性能的影响极小。它主要通过 Vite 插件在构建时进行处理，运行时几乎没有额外的性能开销。如果您担心性能问题，可以通过 excludePages 选项排除不需要根组件的页面，进一步优化性能。

安装和配置问题

Q: 安装 Root 后出现模块找不到的错误？

A: 请确保：

已正确安装依赖：运行 npm install、yarn install 或 pnpm install
包管理器缓存是最新的：尝试清除缓存（npm cache clean --force 或 yarn cache clean）
Node.js 版本符合要求（建议使用 Node.js 16.0 或更高版本）
检查 vite.config.(js|ts) 中的插件配置是否正确

Q: HBuilderX 项目如何使用 Root？

A: HBuilderX 项目需要手动创建 vite.config.(js|ts) 文件，并在项目根目录（而非 src 目录）创建 App.ku.vue 文件。具体步骤如下：

在项目根目录创建 vite.config.js 文件：

import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniKuRoot(),
    Uni()
  ]
})

在项目根目录创建 App.ku.vue 文件：

<script setup lang="ts">
// 根组件逻辑
</script>

<template>
  <KuRootView />
</template>

Q: 如何在 TypeScript 项目中使用 Root？

A: Root 完全支持 TypeScript。确保您的项目已正确配置 TypeScript，并且安装了相应的类型定义文件。在 vite.config.ts 中配置 Root：

import { defineConfig } from 'vite'
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import type { RootPluginOptions } from '@uni-ku/root'

const rootOptions: RootPluginOptions = {
  // 配置选项
}

export default defineConfig({
  plugins: [
    UniKuRoot(rootOptions),
    Uni()
  ]
})

Q: 配置不生效怎么办？

A: 当配置不生效时，请检查以下方面：

配置位置：确保 UniKuRoot 插件配置在正确的位置
插件顺序：确保 UniKuRoot 在修改 pages.json 的插件之后
文件路径：检查 excludePages 中的路径是否正确
缓存问题：尝试清除 Vite 缓存并重新启动开发服务器
语法错误：检查配置文件中是否有语法错误

功能使用问题

Q: 如何自定义虚拟根组件文件名？

A: 通过在 vite.config 中配置 rootFileName 选项：

// vite.config.(js|ts)
UniKuRoot({
  rootFileName: 'KuRoot'
})

然后创建对应的 KuRoot.vue 文件作为虚拟根组件，而不是默认的 App.ku.vue。

Q: 如何在页面中访问根组件的方法和数据？

A: 有两种方式可以获取虚拟根组件实例：局部启用和全局启用。

局部启用

在根组件中暴露方法和数据：

<!-- src/App.ku.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const message = ref('Hello from root')

function showMessage() {
  console.log('Root method called')
}

defineExpose({
  message,
  showMessage
})
</script>

<template>
  <KuRootView />
</template>

在页面中获取引用：

<!-- src/pages/*.vue -->
<script setup lang="ts">
import { ref } from 'vue'
const rootInstance = ref()
</script>

<template root="rootInstance">
  <view>
    <button @click="rootInstance.showMessage()">调用根组件方法</button>
  </view>
</template>

全局启用

在 vite.config 中启用全局引用：

// vite.config.(js|ts)
UniKuRoot({
  enabledGlobalRef: true
})

在页面中通过 getCurrentPages() 获取实例：

<!-- src/pages/*.vue -->
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const rootInstance = ref()

onMounted(() => {
  const pagesStack = getCurrentPages()
  if (pagesStack.length > 0) {
    rootInstance.value = pagesStack[pagesStack.length - 1].$vm.$refs.uniKuRoot
  }
})
</script>

<template>
  <view>
    <button @click="rootInstance.showMessage()">调用根组件方法</button>
  </view>
</template>

Q: 如何排除某些页面不使用根组件？

A: 使用 excludePages 配置项，支持 glob 模式：

// vite.config.(js|ts)
UniKuRoot({
  excludePages: [
    'src/exclude.vue',
    'src/exclude/**/*.vue',
    'src/pages/login.vue',
    'src/pages/error/**/*.vue'
  ]
})

被排除的页面将不会使用根组件，而是直接渲染。

// apps/app-1/vite.config.js
import UniKuRoot from '@uni-ku/root'

export default {
  plugins: [
    UniKuRoot({
      rootFileName: 'App1Root',
      enabledGlobalRef: false
    })
  ]
}

// apps/app-2/vite.config.js
import UniKuRoot from '@uni-ku/root'

export default {
  plugins: [
    UniKuRoot({
      rootFileName: 'App2Root',
      enabledGlobalRef: true,
      excludePages: ['src/pages/special/**']
    })
  ]
}

Q: 如何在不同环境中使用不同的 Root 配置？

A: 您可以根据环境变量动态配置 Root：

// vite.config.(js|ts)
import { defineConfig, loadEnv } from 'vite'
import UniKuRoot from '@uni-ku/root'

export default ({ mode }) => {
  const isProduction = mode === 'production'
  
  return defineConfig({
    plugins: [
      UniKuRoot({
        rootFileName: isProduction ? 'ProdRoot' : 'DevRoot',
        enabledGlobalRef: isProduction,
        excludePages: isProduction 
          ? ['src/pages/test/**']
          : []
      })
    ]
  })
}