KuiklyUI 运行到鸿蒙平台的实践

本指南将帮助你快速搭建 KuiklyUI 在 HarmonyOS 平台的开发环境，并成功运行示例应用。

目录

• 环境准备
• 克隆项目
• 构建 Ohos App
• 运行 Ohos App
• 常见问题
• 参考资源

环境准备

在开始之前，请确保你的开发环境已准备就绪：

必需环境

1. DevEco Studio

   • 下载地址：https://developer.huawei.com/consumer/cn/deveco-studio/
   • 建议使用最新稳定版本

2. JDK 17

   • 下载并安装 JDK 17
   • 配置环境变量

3. Git

   • 确保已安装 Git 并配置 SSH 密钥（用于克隆项目）

可选环境

• 鸿蒙设备或模拟器：用于运行和测试应用
• Android Studio：如果需要同时开发 Android 版本

克隆项目

在终端中执行以下命令克隆 KuiklyUI 项目：

git clone git@gitcode.com:Tencent-TDS/KuiklyUI.git
cd KuiklyUI

注意： 如果使用 HTTPS 方式克隆，命令为：

git clone https://gitcode.com/Tencent-TDS/KuiklyUI.git

构建 Ohos App

步骤 1：编译鸿蒙跨端产物

在 KuiklyUI 根目录执行鸿蒙跨端产物编译脚本：

./2.0_ohos_demo_build.sh

预期输出：

构建成功后，你会看到类似以下的输出：

BUILD SUCCESSFUL in 9m 25s
17 actionable tasks: 17 executed
Copying artifact files:
cp: ./ohosApp/entry/libs/arm64-v8a: No such file or directory
libshared.so: copied from /path/to/KuiklyUI/demo/build/bin/ohosArm64/sharedDebugShared/libshared.so to ohos demo directory: ./ohosApp/entry/libs/arm64-v8a
cp: ./ohosApp/entry/src/main/cpp/thirdparty/biz_entry: No such file or directory
libshared_api.h: copied from /path/to/KuiklyUI/demo/build/bin/ohosArm64/sharedDebugShared/libshared_api.h to ohos demo directory: ./ohosApp/entry/src/main/cpp/thirdparty/biz_entry
Copy ops done!

说明：

• cp: No such file or directory 警告是正常的，脚本会自动创建这些目录
• 构建产物（libshared.so 和 libshared_api.h）会被自动复制到 Ohos 项目目录

构建时间： 首次构建可能需要 5-15 分钟，取决于你的机器性能。后续构建会更快。

步骤 2：使用 DevEco Studio 打开项目

1. 启动 DevEco Studio
2. 选择 Open 或 File -> Open
3. 选择 KuiklyUI/ohosApp 目录（注意： 是 ohosApp 目录，不是根目录）
4. 等待项目同步完成

首次打开时的同步过程：

DevEco Studio 会自动执行同步操作，你会看到类似以下的输出：

"/Applications/DevEco-Studio 2.app/Contents/tools/node/bin/node" "/Applications/DevEco-Studio 2.app/Contents/tools/hvigor/bin/hvigorw.js" --mode module -p module=render -p product=default compileNative --analyze=normal --parallel --incremental --daemon
> hvigor WARN: The project has not explicitly set the 'targetSdkVersion' version at build-profile.json5. It is recommended to configure it. Reference: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-profile-app#section45865492619
> hvigor UP-TO-DATE :render:default@PreBuild...  
> hvigor Finished :render:default@ConfigureCmake... after 59 ms 
> hvigor Finished :render:default@BuildNativeWithCmake... after 14 ms 
> hvigor Finished :render:compileNative... after 1 ms 
> hvigor BUILD SUCCESSFUL in 336 ms 

Process finished with exit code 0

关于警告：

• targetSdkVersion 警告是提示性的，不影响构建。如需配置，可参考提示的文档链接。

如果同步失败：

• 检查网络连接
• 打开 ohosApp 目录下的 .npmrc 文件，点击右上角的 Sync 按钮重新同步
• 确保已正确执行步骤 1 的构建脚本

运行 Ohos App

步骤 3：配置签名

在运行 App 之前，必须配置应用签名：

1. 在 DevEco Studio 中，选择 File -> Project Structure -> Signing Configs
2. 按照向导配置签名信息
3. 参考文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing#section1240072619462

重要提示：

• 如果没有签名配置，应用将无法安装到设备上
• 开发阶段可以使用自动签名，生产环境需要使用正式签名

步骤 4：连接设备或启动模拟器

选项 A：连接真机

1. 在手机上开启开发者模式和 USB 调试
2. 使用 USB 线连接手机到电脑
3. 在 DevEco Studio 中确认设备已识别

选项 B：启动模拟器

1. 在 DevEco Studio 中，选择 Tools -> Device Manager
2. 创建或启动一个鸿蒙模拟器

步骤 5：运行应用

1. 在 DevEco Studio 中，选择运行配置为 entry
2. 点击 Run 按钮

3. 等待应用编译和安装完成
4. 应用会自动启动在连接的设备或模拟器上

运行成功标志：

• 应用正常启动并显示界面
• 可以在应用中进行交互操作
• DevEco Studio 底部显示 “BUILD SUCCESSFUL”

常见问题

1. 构建脚本执行失败

问题： 执行 ./2.0_ohos_demo_build.sh 时出错

解决方案：

• 确保脚本有执行权限：chmod +x 2.0_ohos_demo_build.sh
• 检查 JDK 版本是否为 17
• 确保网络连接正常（需要下载依赖）
• 查看错误日志，根据具体错误信息排查

2. DevEco Studio 同步失败

问题： 打开项目后同步失败

解决方案：

• 打开 ohosApp/.npmrc 文件，点击右上角 Sync 重新同步
• 检查网络连接，确保可以访问 npm 仓库
• 尝试清理缓存：File -> Invalidate Caches / Restart

3. 找不到 libshared.so 文件

问题： 运行时提示找不到 native 库

解决方案：

• 确保已执行步骤 1 的构建脚本
• 检查 ohosApp/entry/libs/arm64-v8a/libshared.so 文件是否存在
• 如果不存在，重新执行构建脚本

4. 签名配置问题

问题： 应用无法安装到设备

解决方案：

• 确保已正确配置签名（步骤 3）
• 检查设备是否开启了 USB 调试
• 尝试卸载设备上的旧版本应用后重新安装

5. 设备连接问题

问题： DevEco Studio 无法识别设备

解决方案：

• 检查 USB 连接和驱动
• 在设备上确认允许 USB 调试
• 尝试重启 DevEco Studio 和设备
• 使用 hdc list targets 命令检查设备连接

6. 构建时间过长

问题： 首次构建耗时很长

说明： 这是正常现象，因为需要：

• 下载 Gradle 和项目依赖
• 编译 Kotlin Multiplatform 代码
• 构建 native 库

优化建议：

• 使用稳定的网络连接
• 确保有足够的磁盘空间
• 后续构建会使用缓存，速度会显著提升

参考资源

官方文档

• 腾讯端服务官网： https://framework.tds.qq.com/
• Kuikly 文档： https://kuikly.tds.qq.com/Introduction/arch.html
• 快速开始（HarmonyOS）： https://kuikly.tds.qq.com/QuickStart/harmony.html

项目资源

• 项目地址： https://atomgit.com/Tencent-TDS/KuiklyUI

社区资源

• 开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net/
• HarmonyOS 开发者文档： https://developer.huawei.com/consumer/cn/doc/

---

欢迎大家一起来尝试 KuiklyUI 在 HarmonyOS 平台上的开发！

如有问题，欢迎在项目 Issues 中提出或参与社区讨论。