欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

KuiklyUI华为云真机部署

一、项目概述

KuiklyUI是腾讯开源的一款基于Kotlin Multiplatform (KMP)的高性能跨平台UI框架，支持Android、iOS、HarmonyOS Next、Web (H5)和小程序等多平台。本记录详细介绍了如何将KuiklyUI项目部署到华为云真机进行测试和验证。

二、环境准备

2.1 开发环境要求

• JDK: JDK 17+ (推荐 JDK 17.0.6 或更高)
• Android 开发: Android Studio Ladybug 或更高版本 (支持 KMP 插件)
• 鸿蒙开发: DevEco Studio 5.0+ (用于运行鸿蒙宿主工程)
• 构建工具: Gradle 8.0+ (项目内置，无需手动安装)
• 操作系统: Windows / macOS / Linux

2.2 鸿蒙环境特别配置

对于鸿蒙开发，需要配置鸿蒙SDK的环境变量，以便Gradle能够找到它：

• Windows: 设置系统环境变量 DEVECO_SDK_HOME 指向你的DevEco SDK路径（例如 C:\Users\YourName\AppData\Local\Huawei\Sdk）。

2.3 华为云账号准备

• 注册华为云账号并完成实名认证
• 前往AppGallery Connect并注册完成实名认证

2.4 项目已通过本地编译

三、证书与签名文件准备

3.1 生成 .p12 密钥库

操作路径：Build → Generate Key and CSR → New

• 密码复杂度：必须包含大小写字母+数字+特殊符号（如 Ku!kly@2026）并选择一个要存放的位置
• 别名（Alias）：建议与项目名一致（如 kuiklyDemo）
• 输出文件：kuiklyDemo.p12

执行完以上步骤就会得到KuiklyDemo.p12文件

3.2 生成 .csr 证书请求

• 复用上一步的 .p12 文件路径与密码
• 输出：kuikly.csr（用于AGC申请证书）

3.3 在AGC生成 .cer 证书

访问：AGC 控制台 AppGallery Connect(没有账号的注册一个账号登录)→ 项目设置 → 证书管理 → 新增证书

• 证书类型：发布证书（调试证书无法用于云真机）
• 上传 .csr 文件 → 下载 .cer 证书

3.4 生成 .p7b 配置文件

3.4.1 创建APP ID

• 包名来源：AppScope/app.json5 中的 bundleName
• 常见错误：包名重复 → 解决方案：在 app.json5 中修改为唯一值

3.4.2 创建发布Profile

• Profile类型：发布
• 关联证书：选择4.3步骤生成的证书
• 下载 .p7b 文件

四、DevEco Studio签名配置

4.1 配置路径

File → Project Structure → Signing Configs → release

4.2 文件映射表

配置项	对应文件	填写说明
Store File	.p12	选择文件路径
Store Password	-	.p12 创建时的密码
Key Alias	-	4.1步骤设置的别名
Key Password	-	同Store Password
Sign Cert Path	.cer	AGC下载的证书
Profile Path	.p7b	AGC下载的配置文件

4.3 强制切换Release模式

顶部工具栏 → Build Mode → 切换为 "release" → Apply

五、构建HAP包

5.1 构建命令

Build → Build Hap(s)/App(s) → Build Hap(s)

六、部署至华为云真机

6.1 云真机申请流程

访问：AGC → 质量服务 → 云测试 → 选择设备（如 Pura 80）

• 点击「开始测试」→ 等待设备初始化（约1~2分钟）

6.2 上传HAP包

• 点击设备界面「安装应用」→ 选择 *-default-signed.hap
• 等待安装完成 → 自动启动应用

七、常见问题与解决方案

7.1 包名重复问题

• 现象：在AGC创建APP ID时提示包名已存在
• 解决方案：在 app.json5 中修改bundleName，添加时间戳或其他唯一标识

7.2 密码错误问题

• 现象：构建时提示密码验证失败
• 解决方案：确保 .p12 文件密码与签名配置中的密码一致

7.3 云真机无法运行问题

• 现象：云真机上安装应用后无法启动
• 解决方案：检查是否使用了发布证书和Release模式构建HAP包

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