Kuikly-OH 跨平台实战：DAY1 KuiklyUI-OH 从环境搭建到华为云真机部署

[Kuikly-OH 跨平台实战：DAY1 KuiklyUI-OH 从环境搭建到华为云真机部署](#Kuikly-OH 跨平台实战：DAY1 KuiklyUI-OH 从环境搭建到华为云真机部署)

[引言](#引言)

[1 搭建 KuiklyUI 环境](#1 搭建 KuiklyUI 环境)

[1.1 创建项目目录](#1.1 创建项目目录)

[1.2 拉取官方仓库代码](#1.2 拉取官方仓库代码)

[1.3 代码结构概览](#1.3 代码结构概览)

[1.4 执行编译脚本](#1.4 执行编译脚本)

[1.4.1 执行 Windows 编译脚本](#1.4.1 执行 Windows 编译脚本)

[1.4.2 问题解决：JAVA_HOME 指向无效目录](#1.4.2 问题解决：JAVA_HOME 指向无效目录)

[1.4.3 优化：配置 Gradle 国内镜像源](#1.4.3 优化：配置 Gradle 国内镜像源)

[1.4.4 构建成功与产物说明](#1.4.4 构建成功与产物说明)

[2 Android Studio 中运行 Kuikly 项目](#2 Android Studio 中运行 Kuikly 项目)

[2.1 正确打开 Kuikly 项目](#2.1 正确打开 Kuikly 项目)

[2.2 安装必要的开发插件](#2.2 安装必要的开发插件)

[2.2.1 安装插件步骤](#2.2.1 安装插件步骤)

[2.2.2 验证插件安装](#2.2.2 验证插件安装)

[2.3 解决 Gradle JDK 版本不兼容问题](#2.3 解决 Gradle JDK 版本不兼容问题)

[2.3.1 检查系统 JDK 环境](#2.3.1 检查系统 JDK 环境)

[2.3.2 在 Android Studio 中切换 Gradle JDK](#2.3.2 在 Android Studio 中切换 Gradle JDK)

[2.4 连接 MuMu 模拟器作为测试设备](#2.4 连接 MuMu 模拟器作为测试设备)

[2.5 运行 androidApp 模块并验证效果](#2.5 运行 androidApp 模块并验证效果)

[3 DevEco Studio 签名配置与 HAP 构建](#3 DevEco Studio 签名配置与 HAP 构建)

[3.1 生成密钥库文件（.p12）与证书请求文件（.csr）](#3.1 生成密钥库文件（.p12）与证书请求文件（.csr）)

[3.1.1 生成密钥库文件（.p12）](#3.1.1 生成密钥库文件（.p12）)

[3.1.2 生成证书请求文件（.csr）](#3.1.2 生成证书请求文件（.csr）)

[3.2 AppGallery Connect 平台证书与 Profile 配置](#3.2 AppGallery Connect 平台证书与 Profile 配置)

[3.2.1 申请发布证书](#3.2.1 申请发布证书)

[3.2.2 创建 APP ID](#3.2.2 创建 APP ID)

[3.2.3 创建并下载 Profile 文件](#3.2.3 创建并下载 Profile 文件)

[3.3 DevEco Studio 签名信息配置](#3.3 DevEco Studio 签名信息配置)

[3.4 Release 版 HAP 包构建与验证](#3.4 Release 版 HAP 包构建与验证)

[4 AppGallery Connect 云真机部署与运行验证](#4 AppGallery Connect 云真机部署与运行验证)

[4.1 云调试服务启动与设备选择](#4.1 云调试服务启动与设备选择)

[4.2 HAP 包上传与安装](#4.2 HAP 包上传与安装)

[4.3 应用运行验证与资源释放](#4.3 应用运行验证与资源释放)

[5 总结](#5 总结)

[6 参考资料](#6 参考资料)

欢迎加入开源鸿蒙跨平台社区：

https://openharmonycrossplatform.csdn.net/

引言

Kuikly 是基于 Kotlin 多平台技术构建的 UI 与逻辑一体化跨平台解决方案，由腾讯公司级前端 Oteam 推出。其目标是提供一个高性能、全平台开发框架，具备统一代码库、极致易用性和动态灵活性。

本篇博客将以实战为导向，从 0 到 1 完整覆盖 Kuikly-OH 项目的开发全流程：从环境搭建与代码初始化，到 Android 端的运行验证，再到鸿蒙端的签名配置、HAP 包构建，最终通过华为云真机完成部署与测试。帮助开发者快速上手鸿蒙跨平台开发。

通过本次的系统性学习，你将掌握：

Kuikly-OH 项目的环境搭建与编译流程
Android Studio 中 Kuikly 项目的运行与调试
DevEco Studio 中鸿蒙应用的签名配置与 HAP 包构建
AppGallery Connect 云真机服务的部署与验证方法

无论你是初次接触跨平台开发的新手，还是希望拓展鸿蒙生态的资深开发者，本系列都将为你提供清晰、可落地的实践路径。

1 搭建 KuiklyUI 环境

1.1 创建项目目录

首先，我们需要在本地创建一个干净的项目目录，用于存放 KuiklyUI 的源代码和后续开发的鸿蒙项目。

本文中我在 D 盘根目录下创建总文件夹 KuiklyUI_OH，作为所有跨平台项目的根目录。

进入 KuiklyUI_OH 文件夹，创建具体的项目文件夹 KuiklyUI_HmProject。

路径示例：D:\KuiklyUI_OH\KuiklyUI_HmProject

打开文件资源管理器，在地址栏输入 cmd 并回车，快速在当前目录打开命令提示符。

1.2 拉取官方仓库代码

接下来，我们通过 Git 工具 / cmd命令打开命令提示符后从官方仓库克隆 KuiklyUI 的源代码。

Windows系统下安装 Git 参考链接：

https://blog.csdn.net/m0_74451345/article/details/155858889?spm=1001.2014.3001.5502

1. 在打开的命令提示符中，执行以下克隆命令

复制代码

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

2. 等待命令执行完成。这个过程会将所有源代码下载到本地的 KuiklyUI 文件夹中。

1.3 代码结构概览

克隆完成后，我们可以看到 KuiklyUI_HmProject 目录下生成了一个 KuiklyUI 文件夹。进入该文件夹，可以看到完整的项目结构：

核心渲染目录 ：如 core-render-ohos，专门用于鸿蒙平台的渲染实现。
Demo 目录 ：demo 文件夹中包含了丰富的示例代码，是学习和调试的最佳入口。
构建脚本 ：针对 Windows 系统，提供了 2.0_ohos_demo_build.bat 批处理文件，用于快速构建鸿蒙 Demo。
多平台支持 ：同时包含了 androidApp、iosApp、h5App 等目录，体现了 KuiklyUI 强大的跨平台能力。

1.4 执行编译脚本

在完成项目结构概览后，我们需要执行专门的编译脚本，将 Kuikly 核心代码编译为鸿蒙（OpenHarmony）平台可识别的动态库和头文件，为后续在 DevEco Studio 中运行鸿蒙 App 做准备。

1.4.1 执行 Windows 编译脚本

Kuikly 项目根目录提供了针对 Windows 平台的编译脚本 2.0_ohos_demo_build.bat，我们直接双击运行即可：

脚本会自动执行以下核心步骤：

Step 0：检测并使用 DevEco Studio 的 OpenHarmony SDK 路径。
Step 1：备份当前项目的 Gradle 版本配置。
Step 2：临时将 Gradle 版本切换为 8.0，以兼容鸿蒙编译环境。
Step 3 ：构建鸿蒙端核心产物（动态库 libshared.so 和头文件 libshared_api.h）。
Step 5：恢复原始 Gradle 版本配置。
Step 6 ：将构建产物复制到 ohosApp 模块的指定目录。

1.4.2 问题解决：JAVA_HOME 指向无效目录

首次执行脚本时，可能会遇到如下错误：

注意：这里的错误是我遇到的，若没有类似的问题可以忽略。（因为我的环境变量没有修改为现有的JDK17，还是延用旧的JDK14所以出现错误。）

复制代码

ERROR: JAVA_HOME is set to an invalid directory: C:\Program Files\Java\jdk-14.0.1
Please set the JAVA_HOME variable in your environment to match the location of your Java installation.

这是因为系统环境变量 JAVA_HOME 指向了旧版 JDK 14，与鸿蒙编译要求的 JDK 17 不兼容。

解决方法：

右键「此电脑」→「属性」→「高级系统设置」→「环境变量」。
找到系统变量中的 JAVA_HOME，将其值修改为 JDK 17 的根目录，例如：C:\Program Files\Java\jdk-17
点击「确定」保存，重启 CMD 后重新执行编译脚本。

C:\Program Files\Java\jdk-17 # 这里是我的jdk 17安装路径，可在电脑上查看下自己的路径

1.4.3 优化：配置 Gradle 国内镜像源

在脚本执行过程中，Gradle 会自动下载指定版本（8.0）或者其他版本的安装包。由于默认的官方源在国内访问速度较慢，我们可以提前修改 gradle-wrapper.properties 文件，使用国内镜像源加速下载：

打开项目根目录下的 gradle/wrapper/gradle-wrapper.properties 文件。
将 distributionUrl 字段修改为腾讯云镜像地址：

distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.0-bin.zip

1.4.4 构建成功与产物说明

当脚本执行完成后，若出现以下提示，说明鸿蒙端产物构建成功：

复制代码

BUILD SUCCESSFUL in 21m 22s
16 actionable tasks: 13 executed, 3 up-to-date
[Step 6] Copying artifact files...
libshared.so: copied to ohosApp\entry\libs\arm64-v8a
libshared_api.h: copied to ohosApp\entry\src\main\cpp\thirdparty\biz_entry

Build completed
Now open ohosApp in DevEco Studio to run

核心产物说明：

libshared.so：Kuikly 核心逻辑的鸿蒙动态库，负责页面渲染和业务逻辑。
libshared_api.h：动态库的头文件，供鸿蒙原生代码调用 Kuikly 能力。

这些产物会被自动复制到 ohosApp 模块的对应目录，为后续在 DevEco Studio 中开发鸿蒙应用做好了准备。

2 Android Studio 中运行 Kuikly 项目

在 Android Studio 中运行 Kuikly 项目（Android 端验证）

完成 KuiklyUI 环境搭建与编译脚本执行后，我们优先在 Android 端验证项目可行性 ------ 通过 Android Studio 搭配 MuMu 模拟器运行项目，既能快速验证核心环境配置，也为后续鸿蒙端适配打下基础。

2.1 正确打开 Kuikly 项目

Kuikly 是多平台多模块项目，切勿直接打开子模块（如 androidApp），否则会导致依赖缺失。

打开 Android Studio，点击顶部菜单 File → Open。
在文件浏览器中，导航到项目根目录：
选中 KuiklyUI 文件夹，点击 OK，等待 Android Studio 加载整个项目结构。

例如博主之前创建拉取的目录，如下：

复制代码

D:\KuiklyUI_OH\KuiklyUI_HmProject\KuiklyUI

2.2 安装必要的开发插件

Kuikly 项目依赖两个核心插件，它们提供了 KMP 开发支持和 Kuikly 专属的项目模板与代码生成能力：

Kotlin Multiplatform Mobile：Kotlin 跨平台开发的核心插件，提供代码高亮、调试和多模块管理能力。
KuiklyTemplate：Kuikly 官方提供的辅助插件，用于创建项目、生成页面代码和配置运行环境。

2.2.1 安装插件步骤

点击顶部菜单 File → Settings（或快捷键 Ctrl+Alt+S）打开设置面板。
在左侧导航栏选择 Plugins，切换到 Marketplace 标签页。
在搜索框中分别搜索并安装以下插件：
- Kotlin Multiplatform Mobile（通常已内置，若未安装则点击 Install）
- KuiklyTemplate（需从 Marketplace 安装）
安装完成后，点击 Apply → OK，并重启 Android Studio 使插件生效。

2.2.2 验证插件安装

重启后，再次进入 Settings → Plugins，在 Installed 标签下确认两个插件已启用（勾选状态）：

2.3 解决 Gradle JDK 版本不兼容问题

首次打开项目时，若 Android Studio 版本 ≥ 2024.2.1，默认 Gradle JDK 为 21，会与项目要求的 JDK 17 不兼容，出现如下错误：

注意：因为我的 Android Studio 版本为 2024.3.2，所以这里要修改为 JDK 17 版本。

复制代码

Your build is currently configured to use incompatible Java 21.0.6 and Gradle 8.0. Cannot sync the project.

2.3.1 检查系统 JDK 环境

先确认系统已安装 JDK 17：

复制代码

java -version
# 输出应类似：java version "17.0.17" 2025-10-21 LTS

where java
# 找到 JDK 17 根目录，如：C:\Program Files\Java\jdk-17

若未安装 JDK 17 可参考一下文章链接来安装：

https://blog.csdn.net/m0_74451345/article/details/155857985?spm=1001.2014.3001.5502

2.3.2 在 Android Studio 中切换 Gradle JDK

点击 File → Settings（或快捷键 Ctrl+Alt+S）。
依次展开 Build, Execution, Deployment → Build Tools → Gradle。
在 Gradle JDK 下拉框中，选择已安装的 17 Oracle OpenJDK 17.0.17。
点击 Apply → OK，再执行 File → Sync Project with Gradle Files （或者点击底部左下角的刷新按钮）重新同步项目。

2.4 连接 MuMu 模拟器作为测试设备

为了运行 Android App，我们通过 ADB 连接 MuMu 模拟器：

启动 MuMu 模拟器，确保其处于运行状态。
打开 Android SDK 的 platform-tools 目录（如本人安装的路径为 D:\PCzyxxrj\Android\Sdk\platform-tools）。
在该目录下打开 CMD，执行连接命令：

adb connect 127.0.0.1:7555

输出 connected to 127.0.0.1:7555 表示连接成功

连接成功后，Android Studio 会自动识别该设备。

2.5 运行 androidApp 模块并验证效果

在 Android Studio 顶部的运行配置下拉框中，选择 androidApp。
确认已连接 MuMu 模拟器（或 Android 真机），点击运行按钮（绿色三角图标）。
等待编译、安装完成后，App 会在设备上启动，显示 Kuikly 页面路由界面：

在输入框中输入页面名称（如 router 或 demo），点击【跳转】，即可体验 Kuikly 的跨平台页面渲染能力，验证 Android 端运行正常。

🚀 小结：

通过以上【打开项目 → 安装插件 → 配置 JDK → 连接设备 → 运行验证】的完整流程，我们确认了 Kuikly 项目在 Android 端的环境配置完全正确。这不仅为后续鸿蒙端开发扫清了障碍，也验证了 Kuikly 跨平台框架的核心能力。

3 DevEco Studio 签名配置与 HAP 构建

在上一部分中，我们完成了 Kuikly 项目在 Android 端的环境搭建与运行验证。下面将聚焦于鸿蒙端，详细讲解如何在 DevEco Studio 中完成签名配置，并构建出可直接部署到设备的 Release 版 HAP 安装包。

首先，需要通过 DevEco Studio 打开项目。

3.1 生成密钥库文件（.p12）与证书请求文件（.csr）

鸿蒙应用发布需要合法的数字签名，我们首先需要生成密钥库文件（.p12）和证书请求文件（.csr），用于后续在 AppGallery Connect 平台申请正式证书。

3.1.1 生成密钥库文件（.p12）

打开 DevEco Studio，在顶部菜单栏选择 Build → Generate Key and CSR。

点击 Key store file (*.p12) 旁的 New 按钮，在项目根目录下创建一个名为 p12file 的文件夹，用于集中管理签名文件。

进入 p12file 文件夹，将文件命名为 KuiklyUI_HmProject.p12，点击 OK。

设置密钥库密码（需包含英文、数字和特殊符号），并在 Alias 字段中输入 KuiklyUI，同时设置密钥密码（可与密钥库密码相同）。

点击 Next，进入 CSR 文件生成步骤。

3.1.2 生成证书请求文件（.csr）

在向导中点击 CSR file (*.csr) 旁的文件夹图标，在项目根目录下创建一个名为 csrfile 的文件夹。

进入 csrfile 文件夹，将文件命名为 KuiklyUI_HmProject.csr，点击 OK。

确认所有信息无误后，点击 Finish，完成文件生成。此时，csrfile 文件夹中将生成 KuiklyUI_HmProject.csr 文件。

3.2 AppGallery Connect 平台证书与 Profile 配置

接下来，我们需要登录 AppGallery Connect（AGC）平台，使用生成的 CSR 文件申请正式发布证书，并创建 Profile 文件，用于应用签名和部署。

3.2.1 申请发布证书

登录 AppGallery Connect 控制台，进入 KuiklyUI_HmProject 项目。
在左侧导航栏选择 证书、APP ID和Profile → 证书，点击右上角的 新增证书。

填写证书名称，如： KuiklyUI_HmProject，证书类型选择 发布证书，并上传之前生成的 KuiklyUI_HmProject.csr 文件。

点击 提交，证书生效后，点击 下载 获取 KuiklyUI_HmProject.cer 证书文件，保存至 csrfile 文件夹中。

3.2.2 创建 APP ID

在左侧导航栏选择 APP ID，点击 创建。

应用类型选择 HarmonyOS应用，应用名称填写 KuiklyUI_HmProject，应用包名需与 app.json5 中的 bundleName 完全一致（如原来的报名可能为 com.tencent.kuiklyohosTest ，我在后面的操作中修改为 com.tencent.kuiklyohosTest）。

⚠️ 注意：若包名已存在，需修改为唯一值，确保与项目配置一致，否则后续签名和部署将失败。

应用分类选择 应用，点击 下一步 → 确认，完成 APP ID 创建。

⚠️ 注意：下面图片中出现了 "应用包名已经存在" 的警告提示，若包名已存在，需修改为唯一值，确保与项目配置一致，否则后续签名和部署将失败。

修改下包名后重试下。

3.2.3 创建并下载 Profile 文件

在左侧导航栏选择 Profile，点击 添加。

应用名称选择 KuiklyUI_HmProject，Profile 名称填写 KuiklyUI_HmProject，类型选择 发布。

点击 选择证书，关联之前申请的 KuiklyUI_HmProject 发布证书。

点击 添加，Profile 生效后，点击 下载 获取 KuiklyUI_HmProjectRelease.p7b 文件，保存至项目根目录下新建的 p7bfile 文件夹中。

3.3 DevEco Studio 签名信息配置

回到 DevEco Studio，我们需要将生成的签名文件配置到项目中，确保构建出的 HAP 包带有合法签名。

1. 打开 DevEco Studio，点击顶部菜单栏 File → Project Structure → Signing Configs。

2. 填写以下关键信息：

Store file ：选择 p12file 文件夹中的 KuiklyUI_HmProject.p12。
Store password：输入之前设置的密钥库密码。
Key alias ：需与密钥库中的别名一致。若构建时出现 Key alias not found 错误，可通过 keytool -list -keystore KuiklyUI_HmProject.p12 命令查看到真实别名（如 kuiklyui），并在此处填写。
Key password：输入之前设置的密钥密码。
Profile file ：选择 p7bfile 文件夹中的 KuiklyUI_HmProjectRelease.p7b。
Certpath file ：选择 csrfile 文件夹中的 KuiklyUI_HmProject.cer。

3. 点击 Apply → OK，完成签名配置。

3.4 Release 版 HAP 包构建与验证

签名配置完成后，我们可以构建 Release 版 HAP 包，用于部署到鸿蒙设备。

在 DevEco Studio 工具栏，点击 Build Variants 按钮，将 Build Mode 切换为 release。

点击顶部菜单栏 Build → Build Hap(s)/APP(s) → Build Hap(s)，开始构建。

注意：我这里出现了报错，显示 Key alias not found 错误，是因为前面的真实别名（如 kuiklyui）填写错误了。

Key alias ：需与密钥库中的别名一致。若构建时出现 Key alias not found 错误，可通过 keytool -list -keystore KuiklyUI_HmProject.p12 命令查看到真实别名（如 kuiklyui），并在此处填写。

Win+R 键输入cmd 打开命令提示符窗口，输入以下命令查看之前的别名。

重新修改别名。

Release 版 HAP 包构建成功。

构建成功后，在 ohosApp/entry/build/default/outputs/default 目录下找到 entry-default-signed.hap 文件，这就是带有合法签名的正式安装包，可直接安装到鸿蒙设备或云真机上运行。

4 AppGallery Connect 云真机部署与运行验证

构建完成后，我们可以通过 AppGallery Connect 的云调试服务，将 Kuikly 应用部署到华为云真机上进行运行验证，确保应用在真实鸿蒙设备上的兼容性和功能完整性。

4.1 云调试服务启动与设备选择

在 AppGallery Connect 控制台，进入 开发与服务 → 云调试。
在机型选择页面，可根据需求筛选设备（如 HarmonyOS NEXT 专享机型），选择一款空闲设备（如 Pura 80），点击 开始测试。

在弹出的提示框中确认剩余优惠时长，点击 确定，启动云真机服务。

4.2 HAP 包上传与安装

进入云调试的 单机调试 页面，在右侧 应用 区域点击本地上传区域，选择之前构建的 entry-default-signed.hap 文件。

等待文件上传完成，系统将自动开始安装应用，提示 "应用正在安装中，请稍后"。

4.3 应用运行验证与资源释放

应用安装完成后，将自动启动，在左侧的云真机屏幕上可以看到 Kuikly 应用的主界面（如 Kuikly 页面路由、APP 原型 Demo 等功能入口），验证应用正常运行。

测试完成后，点击右上角的 停止测试，在弹出的提示框中点击 确定，释放云真机资源，避免消耗优惠时长。

🚀 小结：

通过本章的学习，我们完成了 Kuikly 项目在鸿蒙端的签名配置、HAP 构建以及云真机部署验证。从生成签名文件、在 AGC 平台配置证书与 Profile，到 DevEco Studio 中完成签名配置，再到通过云调试服务验证应用运行，每一步都为 Kuikly 跨平台应用的鸿蒙端发布奠定了坚实基础。

5 总结

本篇博客以 Kuikly-OH 跨平台开发为核心，通过四个关键阶段，完整呈现了从项目初始化到鸿蒙云真机部署的全链路实践：

**环境搭建与项目初始化：**从创建项目目录、拉取官方代码，到解决编译过程中的 JAVA_HOME 与 Gradle 镜像问题，我们完成了 Kuikly-OH 项目的基础构建，为后续开发奠定了坚实基础。
**Android Studio 中运行 Kuikly 项目：**通过正确打开项目、安装必要插件、解决 Gradle JDK 版本兼容问题，并连接 MuMu 模拟器，我们成功验证了 Kuikly 应用在 Android 端的运行效果，展现了其跨平台兼容性的核心优势。
**DevEco Studio 签名配置与 HAP 构建：**从生成密钥库文件与证书请求，到在 AppGallery Connect 平台申请发布证书、创建 APP ID 与 Profile 文件，再到 DevEco Studio 中完成签名配置，我们最终构建出可直接部署的 Release 版 HAP 包，打通了鸿蒙应用发布的关键环节。
**AppGallery Connect 云真机部署与运行验证：**借助华为云调试服务，我们将构建好的 HAP 包部署到云真机上，完成了应用的安装、运行与功能验证，确保 Kuikly 应用在真实鸿蒙设备上的稳定性与兼容性。

通过这一系列实践，我们不仅能够掌握 Kuikly-OH 跨平台开发的核心技能，还可以更深入理解了鸿蒙应用发布与云调试的完整流程。Kuikly-OH 的跨平台能力，让开发者能够以更低的成本、更高的效率，同时覆盖 Android 与鸿蒙两大生态，为应用的快速迭代与多端分发提供了有力支撑。

6 参考资料

（1）参考文章链接：

Android Studio 下载与安装：

https://blog.csdn.net/m0_74451345/article/details/151120149?sharetype=blogdetail&sharerId=151120149&sharerefer=PC&sharesource=m0_74451345&spm=1011.2480.3001.8118

OpenHarmony环境搭建------02-JDK17安装教程：

https://blog.csdn.net/m0_74451345/article/details/155857985?spm=1001.2014.3001.5502

Windows系统下安装 Git ：

https://blog.csdn.net/m0_74451345/article/details/155858889?spm=1001.2014.3001.5502

（2）Kuikly-OH介绍文章链接：

Kuikly-OH 实践指南

https://gitcode.com/Tencent-TDS/KuiklyUI#%E8%BF%90%E8%A1%8C-android-%E5%BA%94%E7%94%A8

📱 最后，文中也有许多待优化点，欢迎大家关注交流～

Kuikly-OH 跨平台实战：DAY1 KuiklyUI-OH 从环境搭建到华为云真机部署