【开源鸿蒙跨平台开发–KuiklyUI–02】华为云真机部署实战指南

更新说明：本文系统梳理 Kuikly 项目打包与云真机部署全流程，新增环境检查清单、常见错误速查表、自动化脚本建议，助你高效完成 Release 版本构建。

📌 文章概览

• 适用场景：Kuikly 框架开发（当前不支持 x86 模拟器）
• 核心目标：生成 Release 版 HAP 包 → 部署至华为云真机
• 预计耗时：20~30 分钟（首次配置）
• 前置要求：
  • ✅ DevEco Studio 5.0+
  • ✅ 已注册 AppGallery Connect 账号
  • ✅ 项目已通过本地编译（ohpm install 无报错）

---

一、为什么必须使用云真机？

1.1 Kuikly 的架构限制

Kuikly → ArkTS → ArkCompiler → 仅支持 ARM64 编译
          ↓
DevEco 模拟器（x86_64）→ ❌ 无法运行

1.2 云真机 vs 本地真机对比

对比项	华为云真机	本地真机
成本	免费 300 分钟/月	需购买设备
调试效率	需手动上传 HAP（分钟级）	一键部署（秒级）
适用阶段	功能验证/兼容性测试	日常开发
推荐策略	✅ 先完成 Android 端开发 → 再云真机验证鸿蒙端

---

二、证书与签名文件生成（四步法）

2.1 环境检查清单

# Windows PowerShell 检查关键工具
Get-Command keytool    # Java Keytool（DevEco 自带）
ohpm -v                # 确认 ohpm 可用

2.2 生成 .p12 密钥库

1. 操作路径：Build → Generate Key and CSR → New
2. 关键参数：
   • 密码复杂度：必须包含大小写字母+数字+特殊符号（如 Ku!kly@2026）
   • 别名（Alias）：建议与项目名一致（如 kuiklyDemo）
3. 输出文件：kuiklyDemo.p12

⚠️ 避坑提示：密码错误将导致后续所有签名失败，建议记录在密码管理器

2.3 生成 .csr 证书请求

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

在DevEco Studio点击上方的Build，选中Generate Key and CSR。

点击New，点击后会出现一个Create Key Store的弹窗，再点击文件夹的图标选择自己要存放的位置





执行完以上步骤后我们会得到KuiklyDemo.p12文件

新建.csr文件的步骤和新建.p12文件的步骤相似。依然选择文件夹的图标，自己新建一个文件夹来存放.csr文件。（我就用原来刚刚存放.p12的文件夹了，不要学我！！！）


这时我们应该会有这两个文件，没有的检查一下哪个步骤出了问题，这两个文件一定要有！！

2.4 在 AGC 生成 .cer 证书

1. 访问：AGC 控制台 → 项目设置 → 证书管理 → 新增证书
2. 证书类型：发布证书（调试证书无法用于云真机）
3. 上传 .csr 文件 → 下载 .cer 证书

没有AppGallery Connect账号的，点击蓝色文字注册 AppGallery Connect 账号

2.5 生成 .p7b 配置文件

2.5.1 创建 APP ID

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

  // 修改前
  "bundleName": "com.tencent.kuiklyDemo"
  // 修改后（添加时间戳避免冲突）
  "bundleName": "com.tencent.kuiklyDemo20260128"
  

2.5.2 创建发布 Profile

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

---

我们暂时不需要这些能力，滑到最末尾点击确认

三、DevEco Studio 签名配置

3.1 配置路径

File → Project Structure → Signing Configs → release

3.2 文件映射表

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

3.3 强制切换 Release 模式

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

🔴 致命错误：未切换模式将导致云真机报错 应用非Release版本

---

使用手动签名，把我们自己生成的文件做一下替换


点击OK后，四个绿色的对号即为成功

四、构建 HAP 包

4.1 构建命令

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

4.2 输出路径

项目根目录\entry\build\default\outputs\default
└── entry-default-unsigned.hap  # 未签名（错误）
└── entry-default-signed.hap    # ✅ 正确产物

4.3 常见构建错误速查

错误现象	根本原因	解决方案
Password verification failed	密码不一致	检查 .p12 与配置中的密码
Alias not found	别名拼写错误	核对 2.2 步骤设置的 Alias
构建成功但无 signed.hap	未切换 Release 模式	3.3 步骤强制切换

---

五、部署至华为云真机

5.1 云真机申请流程

1. 访问：AGC → 质量服务 → 云测试 → 选择设备（如 Pura 80）
2. 点击「开始测试」→ 等待设备初始化（约 1~2 分钟）

5.2 上传 HAP 包

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

5.3 调试技巧

# 查看实时日志（云真机控制台）
点击「日志」标签 → 筛选 "kuikly" 关键词

---

点击进入这个网址云真机申请网址 AppGallery Connect
选择我们刚刚创建的项目


我这里选择一个最贵的，嘿嘿嘿！


点击这个区域上传我们刚刚的包

六、最佳实践与效率优化

6.1 证书文件管理建议

项目根目录/
├── certs/
│   ├── kuiklyDemo.p12
│   ├── kuikly.csr
│   ├── kuikly.cer
│   └── kuikly.p7b
└── .gitignore  # 添加 certs/ 避免提交敏感文件

6.2 自动化构建脚本（PowerShell）

# build-release.ps1
ohpm run build:release
Copy-Item "huawei/outputs/default/release/*-signed.hap" -Destination "dist/"
Write-Host "✅ Release HAP 已生成至 dist/ 目录" -ForegroundColor Green

6.3 云真机使用策略

• ✅ 每日首次验证功能完整性
• ✅ 版本发布前兼容性测试
• ❌ 避免用于高频调试（消耗免费时长）

---

七、FAQ

Q1：能否复用同一套证书用于多个项目？
A：可以，但建议为不同项目创建独立证书便于权限隔离。

Q2：云真机时长用完怎么办？
A：次月自动重置 300 分钟；企业用户可申请配额提升。

Q3：HAP 包体积过大如何优化？
A：在 build-profile.json5 中启用 enableObfuscation 混淆 + 移除未使用资源。

---

八、延伸阅读

• 【开源鸿蒙跨平台开发–KuiklyUI】 Windows平台Kuikly OpenHarmony开发环境搭建及脚本编译模板工程流程
• Kuikly官方文档
• OpenHarmony官方文档
• Kotlin Multiplatform官方文档

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

版权声明：本文遵循 CC 4.0 BY-SA 协议，转载请注明出处。