鸿蒙工程在云端编译:我踩过的四个坑和一个签名死结
最近在华为云的鸿蒙开发工作区里编译一个多模块工程(一个公交出行 App 模板,entry + 5 个 feature 模块)。工程本身是官方模板,理论上应该开箱能编译,实际一路踩了四个坑。
记录下来,后来人少走点弯路。
坑一:ohpm 解析不了 file:../common
工程的两个模块在 oh-package.json5 里这样声明依赖:
"dependencies": {
"common": "file:../common"
}
ohpm install 报错,说找不到这个依赖。
原因:file: 协议在 ohpm 里对相对路径的支持有限,尤其在多模块工程里,跨目录引用很容易解析失败。
解法有两条:
- 把公共模块发布成私有仓,用版本号引用(正规做法,但依赖仓)
- 在根
oh-package.json5里用 workspaces 声明本地包,让 ohpm 统一解析
临时绕过的做法是直接 ohpm install 到各自模块目录,让依赖落在本地 oh_modules,但这不是长久之计。
坑二:缺 local.properties
编译脚本找不到 SDK,报:
ERROR: SDK path not found
鸿蒙的命令行构建依赖 local.properties 里的 sdk.dir:
sdk.dir=/root/command-line-tools/sdk/default/openharmony
这个文件通常由 DevEco Studio 生成,纯命令行环境里没人给你建。手动补上就行——但路径要指向工作区里实际的 SDK,不是文档里的示例路径。
坑三:HMS SDK 和 OpenHarmony SDK 不是一回事
工程 build-profile.json5 里写的是:
"compatibleSdkVersion": "5.0.0(12)"
工作区里装的是 OpenHarmony SDK,而工程按 HarmonyOS 的 SDK 声明去解析,两边对不上,报的错还很含糊——只说依赖缺失,不说具体缺哪个。
判断方法:看 local.properties 的 sdk.dir 指向哪个目录,再看工程的 compatibleSdkVersion 是谁家的版本号。两个不是一家的,就得改其中一个。
我们最后是把 SDK 指向 OpenHarmony 那一套,编译才过。
坑四:构建成功不等于能装
这是最要命的一个。构建日志显示成功:
BUILD SUCCESSFUL
产物:entry/build/default/outputs/default/entry-default-unsigned.hap
大小:15.7 MB
注意文件名里的 -unsigned。鸿蒙设备不接受未签名的包,hdc install 会直接拒绝。
死结:签名需要 AGC 的证书
鸿蒙应用的签名三件套:
| 文件 | 作用 |
|---|---|
| .p12 | 私钥库,由 CSR 生成 |
| .cer | 调试证书 |
| .p7b | Profile,绑定包名和调试设备 |
这三样都得在 AppGallery Connect 里创建:
1. 用华为开发者账号登录 AGC
2. 创建 HarmonyOS 应用,填包名
3. 本地生成 CSR(DevEco Studio 或 keytool)
4. 上传 CSR 换 .cer
5. 用 .cer + 设备 UDID 生成 .p7b
没有这三样,signingConfigs 配不出来,产物永远带 -unsigned,永远装不进设备——包括云端模拟器。
这一步是账号资产,不是技术问题。代码写得再对,没有证书就是装不上。
几条经验
先看 build-profile.json5 再动手编译。 SDK 版本、模块依赖、签名配置全在里面,先读一遍能省掉一半报错。
云工作区不是完整的 DevEco。 IDE 会自动生成的东西(local.properties、签名配置、依赖缓存),命令行环境一样都没有。
报错信息往往不指向根因。 「依赖缺失」可能是 SDK 版本不匹配,「编译失败」可能是签名没配。按「工程配置 → SDK → 依赖 → 签名」的顺序逐层排除。
产物大小能反推是否正常。 15 MB 左右说明资源打全了;只有几百 KB 通常是资源没进去或构建中断。
最后
云端编译鸿蒙工程这件事,工具链已经备好了,卡人的从来不是命令,是那些 IDE 帮你做掉、命令行没人提醒你的隐性步骤。
签名这一关尤其典型:它不属于「开发」,属于「资质」。写代码的人往往到最后一刻才发现,自己缺的不是技术,是账号。
- 点赞
- 收藏
- 关注作者
评论(0)