Root 安装指南

系统要求

在安装 Root 之前，请确保您的系统满足以下最低要求：

• 操作系统：Windows 10+、macOS 10.14+ 或 Linux (Ubuntu 18.04+)
• Node.js：Node.js 16.0 或更高版本
• 包管理器：npm、yarn 或 pnpm
• Uniapp 项目：支持 HBuilderX 或 CLI 创建的 Uniapp Vue3 项目
• 构建工具：Vite（Uniapp 默认使用）

安装方法

使用包管理器安装

Root 可以通过 npm、yarn 或 pnpm 进行安装。选择您喜欢的包管理器执行以下命令：

使用 pnpm 安装（推荐）

pnpm add -D @uni-ku/root

使用 yarn 安装

yarn add -D @uni-ku/root

使用 npm 安装

npm install -D @uni-ku/root

注意：-D 参数表示将 Root 安装为开发依赖，这是推荐的做法，因为 Root 主要在开发阶段使用。

项目配置

安装完成后，您需要在项目中配置 Root。根据您的项目类型（CLI 或 HBuilderX），配置方式略有不同。

CLI 项目配置

对于通过 CLI 创建的 Uniapp 项目，请按照以下步骤配置：

1. 编辑 vite.config.(js|ts)
   在项目根目录下的 vite.config.js 或 vite.config.ts 文件中添加 Root 插件：
   // vite.config.(js|ts)
   import Uni from '@dcloudio/vite-plugin-uni'
   import UniKuRoot from '@uni-ku/root'
   import { defineConfig } from 'vite'
   
   export default defineConfig({
     plugins: [
       // 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后
       UniKuRoot(),
       Uni()
     ]
   })
   

2. 创建虚拟根组件
   在 src 目录下创建 App.ku.vue 文件：
   <!-- src/App.ku.vue -->
   <script setup lang="ts">
   import { ref } from 'vue'
   const helloKuRoot = ref('Hello AppKuVue')
   </script>
   
   <template>
     <div>{{ helloKuRoot }}</div>
     <KuRootView />
   </template>
   

HBuilderX 项目配置

对于通过 HBuilderX 创建的 Uniapp 项目，请按照以下步骤配置：

1. 创建 vite.config.(js|ts)
   在项目根目录下创建 vite.config.js 或 vite.config.ts 文件：
   // vite.config.(js|ts)
   import Uni from '@dcloudio/vite-plugin-uni'
   import UniKuRoot from '@uni-ku/root'
   import { defineConfig } from 'vite'
   
   export default defineConfig({
     plugins: [
       // 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后
       UniKuRoot(),
       Uni()
     ]
   })
   

2. 创建虚拟根组件
   在项目根目录下创建 App.ku.vue 文件：
   <!-- App.ku.vue -->
   <script setup lang="ts">
   import { ref } from 'vue'
   const helloKuRoot = ref('Hello AppKuVue')
   </script>
   
   <template>
     <div>{{ helloKuRoot }}</div>
     <KuRootView />
   </template>
   

验证安装

安装和配置完成后，您可以通过以下步骤验证 Root 是否正确安装：

1. 启动开发服务器
   # 使用 npm
   npm run dev
   
   # 使用 yarn
   yarn dev
   
   # 使用 pnpm
   pnpm dev
   

2. 检查页面渲染
   如果一切正常，您的应用应该能够正常启动，并且页面内容会正确渲染到 App.ku.vue 中的 <KuRootView /> 位置。
3. 检查控制台输出
   打开浏览器控制台或开发者工具，查看是否有任何错误信息。如果没有错误，说明 Root 已成功安装和配置。

升级 Root

使用包管理器升级

使用 pnpm 升级

pnpm update -D @uni-ku/root

使用 yarn 升级

yarn upgrade -D @uni-ku/root

使用 npm 升级

npm update -D @uni-ku/root

升级注意事项

在升级 Root 之前，请：

1. 查看更新日志：访问 GitHub Releases 了解新版本的变更内容。
2. 备份配置：备份您的 vite.config.(js|ts) 和 App.ku.vue 文件。
3. 测试兼容性：在升级后，充分测试您的应用以确保所有功能正常工作。

卸载 Root

如果需要卸载 Root，请根据您的包管理器选择相应的卸载命令：

使用 pnpm 卸载

pnpm remove @uni-ku/root

使用 yarn 卸载

yarn remove @uni-ku/root

使用 npm 卸载

npm uninstall @uni-ku/root

卸载后，请记得：

1. 移除配置：从 vite.config.(js|ts) 中移除 UniKuRoot 插件配置。
2. 调整代码：将原来在 App.ku.vue 中的全局组件和逻辑迁移到其他位置。
3. 更新页面：移除页面中对根组件实例的引用。

常见问题

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

A: 请确保：

1. 已正确安装依赖：npm install 或 yarn install 或 pnpm install
2. 包管理器缓存是最新的：尝试清除缓存（npm cache clean --force 或 yarn cache clean）
3. Node.js 版本符合要求

Q: HBuilderX 项目如何使用 Root？

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

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

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

Q: Root 是否支持 Vue2？

A: 目前 Root 仅支持 Uniapp Vue3 项目，不支持 Vue2。

Q: 如何在多个项目中共享 Root 配置？

A: 您可以将 Root 配置提取到一个单独的文件中，然后在多个项目的 vite.config.(js|ts) 中引入和使用。

Q: 安装后应用无法启动？

A: 请检查：

1. vite.config.(js|ts) 中的插件配置是否正确
2. App.ku.vue 文件是否在正确的位置
3. 是否有语法错误或拼写错误

获取帮助

如果在安装过程中遇到问题，请：

1. 查看 GitHub Issues 中是否已有类似问题
2. 搜索 GitHub Discussions 获取社区帮助
3. 联系作者获取技术支持（QQ: 319619193）
4. 查看 示例项目 了解实际应用

下一步

安装完成后，我们建议您：

1. 阅读 快速开始指南 了解基本用法
2. 探索 功能特性 了解高级配置
3. 查看 示例项目 了解实际应用场景
4. 了解如何为 Root 贡献代码

我们期待看到您使用 Root 构建出色的 Uniapp 应用！