鸿蒙工程在云端编译:我踩过的四个坑和一个签名死结

举报
yd_219023509 发表于 2026/11/14 11:40:38 2026/11/14
【摘要】 官方模板在云端工作区一路编译失败:ohpm 解析不了 file: 依赖、缺 local.properties、HMS SDK 和 OpenHarmony SDK 对不上,最后构建成功了却卡在签名——鸿蒙安装必须过 AGC 证书这一关。

最近在华为云的鸿蒙开发工作区里编译一个多模块工程(一个公交出行 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 帮你做掉、命令行没人提醒你的隐性步骤。

签名这一关尤其典型:它不属于「开发」,属于「资质」。写代码的人往往到最后一刻才发现,自己缺的不是技术,是账号。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。