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

【开源鸿蒙跨平台开发–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-Commandkeytool# Java KeytoolDevEco 自带ohpm-v# 确认 ohpm 可用2.2 生成 .p12 密钥库操作路径Build → Generate Key and CSR → New关键参数密码复杂度必须包含大小写字母数字特殊符号如Ku!kly2026别名Alias建议与项目名一致如kuiklyDemo输出文件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 证书访问AGC 控制台 → 项目设置 → 证书管理 → 新增证书证书类型发布证书调试证书无法用于云真机上传.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.kuiklyDemo202601282.5.2 创建发布 ProfileProfile 类型发布关联证书选择 2.4 步骤生成的证书下载.p7b文件我们暂时不需要这些能力滑到最末尾点击确认三、DevEco Studio 签名配置3.1 配置路径File → Project Structure → Signing Configs → release3.2 文件映射表配置项对应文件填写说明Store File.p12选择文件路径Store Password-.p12创建时的密码Key Alias-2.2 步骤设置的别名Key Password-同 Store PasswordSign Cert Path.cerAGC 下载的证书Profile Path.p7bAGC 下载的 Profile3.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 云真机申请流程访问AGC → 质量服务 → 云测试 → 选择设备如 Pura 80点击「开始测试」→ 等待设备初始化约 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.ps1ohpm run build:releaseCopy-Itemhuawei/outputs/default/release/*-signed.hap-Destinationdist/Write-Host✅ Release HAP 已生成至 dist/ 目录-ForegroundColor Green6.3 云真机使用策略✅ 每日首次验证功能完整性✅ 版本发布前兼容性测试❌ 避免用于高频调试消耗免费时长七、FAQQ1能否复用同一套证书用于多个项目A可以但建议为不同项目创建独立证书便于权限隔离。Q2云真机时长用完怎么办A次月自动重置 300 分钟企业用户可申请配额提升。Q3HAP 包体积过大如何优化A在build-profile.json5中启用enableObfuscation混淆 移除未使用资源。八、延伸阅读【开源鸿蒙跨平台开发–KuiklyUI】 Windows平台Kuikly OpenHarmony开发环境搭建及脚本编译模板工程流程Kuikly官方文档OpenHarmony官方文档Kotlin Multiplatform官方文档欢迎加入开源鸿蒙跨平台社区开源鸿蒙跨平台开发者社区版权声明本文遵循 CC 4.0 BY-SA 协议转载请注明出处。