摘要

本文基于 KMP / CMP for OpenHarmony 技术路线，记录在 macOS 环境下完成 KuiklyUI 源码构建，并通过 hdc 无线调试方式运行到鸿蒙设备 的完整实践过程。

本文聚焦于工程可落地性，围绕真实构建流程，依次覆盖源码获取、鸿蒙跨端产物构建、Ohos 工程加载、Xcode 与命令行工具配置、hdc 工具环境配置与验证、无线调试连接、设备连接前置条件下的应用签名配置以及真机运行结果验证。

---

一、实践背景

KuiklyUI 是基于 Kotlin Multiplatform（KMP） 与 CMP 技术体系构建的跨平台 UI 框架，目标是在多端平台间实现业务逻辑与 UI 能力的复用。

在 OpenHarmony 场景下，其工程实践的关注重点主要集中在以下几个方面：

• KMP 业务逻辑在鸿蒙侧的可编译与可运行性
• Native 产物与鸿蒙工程构建体系之间的协同关系
• 与 DevEco Studio 原生工程模型的集成方式

本次实践的目标明确且单一：

完成 KuiklyUI 源码级构建，并在真实鸿蒙设备上成功运行示例应用。

---

二、环境准备

2.1 DevEco Studio

通过官方页面下载安装 DevEco Studio，用于加载 Ohos 工程并完成应用构建、签名与运行。

https://developer.huawei.com/consumer/cn/deveco-studio/

图 2-1 DevEco Studio 启动界面

---

2.2 JDK 17

KuiklyUI 的构建过程依赖 Java 工具链，需要安装 JDK 17。

https://adoptium.net/temurin/releases/?version=17

安装完成后，在终端中验证版本信息：

java -version

图 2-2 JDK 17 版本信息

---

2.3 Git

macOS 系统通常已自带 Git 工具，用于项目源码的克隆与版本管理。

在终端中验证 Git 是否可用：

git --version

图 2-3 系统 Git 版本信息

---

2.4 Xcode 与命令行工具

KuiklyUI 在构建 KMP Native 产物时，会依赖 macOS 平台的原生编译工具链，因此需要完整安装 Xcode 及其命令行工具。

通过 App Store 安装 Xcode：

https://apps.apple.com/app/xcode/id497799835

安装完成后，在终端中验证 xcodebuild：

xcodebuild -version

图 2-4 Xcode 版本信息

并执行 License 接受操作：

sudo xcodebuild -license accept

图 2-5 Xcode License 接受完成提示

---

三、克隆 KuiklyUI 项目

在终端中执行以下命令克隆 KuiklyUI 源码：

git clone https://atomgit.com/Tencent-TDS/KuiklyUI.git
cd KuiklyUI
ls

图 3-1 KuiklyUI 项目目录结构

---

四、构建鸿蒙跨端产物

在 KuiklyUI 根目录下执行鸿蒙侧跨端产物构建脚本：

chmod +x 2.0_ohos_demo_build.sh
./2.0_ohos_demo_build.sh

该脚本将完成以下核心工作：

1. 编译 KMP / CMP 相关模块
2. 生成鸿蒙侧可用的 Native 产物
3. 将构建结果自动复制至 Ohos 工程目录

构建完成后，终端会输出完整的成功日志。

图 4-1 鸿蒙跨端产物构建完成日志

---

五、使用 DevEco Studio 打开 Ohos 工程

启动 DevEco Studio，选择打开以下工程路径：

KuiklyUI/ohosApp

工程加载完成后，DevEco Studio 会自动执行项目同步，并触发必要的 Native 构建流程。

图 5-1 ohosApp 工程加载与同步完成

---

六、配置 hdc 环境并验证

6.1 下载 Command Line Tools For HarmonyOS

下载 Command Line Tools For HarmonyOS 并解压至本地目录，例如：

~/command-line-tools

下载地址：

https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos

图 6-1 Command Line Tools For HarmonyOS 下载页面

---

6.2 配置 hdc 环境变量

在终端中配置 hdc 所需环境变量，使用 ~/.zprofile 作为环境变量配置入口：

touch ~/.zprofile

将 hdc 相关配置写入文件：

echo 'export HDC_HOME=~/command-line-tools/sdk/default/openharmony/toolchains' >> ~/.zprofile
echo 'export PATH=$HDC_HOME:$PATH' >> ~/.zprofile
echo 'export HDC_SERVER_PORT=7035' >> ~/.zprofile

---

6.3 使环境变量生效

source ~/.zprofile

---

6.4 验证 hdc 工具

hdc --version

图 6-2 hdc 版本信息输出

---

七、开启无线调试并连接设备（签名前置条件）

7.1 开启开发者模式

设置 → 关于手机 → 连续点击“软件版本”7次

---

7.2 启用无线调试

设置 → 系统 → 开发者选项 → 无线调试

---

7.3 无线连接设备

在设备无线调试页面获取 IP 与端口后，执行：

hdc tconn <device_ip>:<connect_port>

图 7-1 hdc 无线连接成功提示

---

7.4 验证设备连接状态

hdc list targets

图 7-2 hdc 识别到鸿蒙设备

---

八、配置应用签名（需已连接设备）

在 DevEco Studio 中进入：

File → Project Structure → Signing Configs

在设备已连接状态下，启用 Automatically generate signature，由 DevEco Studio 自动生成调试签名。

图 8-1 DevEco Studio 签名配置界面

---

九、运行应用

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

图 9-1 DevEco Studio 运行配置界面

---

十、运行结果验证

应用完成构建与安装后，在鸿蒙设备上成功启动并显示 KuiklyUI 示例界面。

图 10-1 KuiklyUI 示例应用在鸿蒙设备上的运行效果

---

十一、实践小结

• KuiklyUI 源码在 OpenHarmony 平台完成了完整构建与运行流程
• Xcode 及其命令行工具是 KMP Native 构建的必要前置条件
• hdc 无线调试需在签名配置之前完成设备连接
• KMP / CMP 跨端方案在鸿蒙侧具备实际工程可行性

---

十二、参考资源

KuiklyUI 架构说明
https://kuikly.tds.qq.com/Introduction/arch.html

KuiklyUI HarmonyOS 快速开始
https://kuikly.tds.qq.com/QuickStart/harmony.html

KuiklyUI 项目地址（AtomGit）
https://atomgit.com/Tencent-TDS/KuiklyUI

HarmonyOS 开发者文档
https://developer.huawei.com/consumer/cn/doc/

---