KuiklyUI 运行到鸿蒙平台的实践

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

环境准备

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

必需环境

DevEco Studio
- 下载地址：https://developer.huawei.com/consumer/cn/deveco-studio/
- 建议使用最新稳定版本
JDK 17
- 下载并安装 JDK 17
- 配置环境变量
Git
- 确保已安装 Git 并配置 SSH 密钥（用于克隆项目）

可选环境

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

克隆项目

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

bash 复制代码

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

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

bash 复制代码

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

构建 Ohos App

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

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

bash 复制代码

./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 打开项目

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

首次打开时的同步过程：

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 之前，必须配置应用签名：

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

重要提示：

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

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

选项 A：连接真机

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

选项 B：启动模拟器

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

步骤 5：运行应用

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

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

运行成功标志：

应用正常启动并显示界面
可以在应用中进行交互操作
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 库

优化建议：

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

参考资源

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

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

KuiklyUI 运行到鸿蒙平台的实践