鸿蒙签名踩坑指南：SDK 调试证书过期三年没人发现，hapsigntool 五关全解析## TL;DR

鸿蒙应用签名有五道坑，全部不在官方文档里：-mode 参数要填 localSign、SDK 调试证书模板 2023 年已过期、五件套路径各版本不一致、证书与 profile 绑定关系无报错线索、签名"成功"≠装机能跑。本文逐关解析+给出可复用的解法。

引言

做鸿蒙开发的朋友大概率被签名折磨过。我们把 hapsigntool 全链趟了一遍，前后撞了五道墙。每一关的答案都不在官方文档里——全是工具自己的报错一步步"报案"教出来的。

第一关：mode 词汇关

hapsigntool 的 -mode 参数，你以为是 debug 或 release？都不是，要填 localSign。报错信息完全不会提示你这一点。

# 错误写法（报错不提示根因）
hapsigntool sign -mode debug ...

# 正确写法
hapsigntool sign -mode localSign ...

第二关：五件套定位关

签名要凑齐五件套：

1. 签名 jar（hapsigntool.jar）
2. p12 证书（签名证书）
3. pem 证书（CA 证书）
4. profile 模板（.p7b）
5. java 运行环境

这五个路径散落在 SDK 的不同角落，而且不同 SDK 版本的位置还不一致。

第三关：过期模板关（最离谱）

SDK 自带的调试证书模板，有效期停在 2023 年。也就是说，你今天拿官方模板生成的调试证书，生成即过期。过期三年，官方文档只字未提。

我们是怎么发现的？不是靠人，是靠工具自己的报错：在自动化签名时，报错链一步步指向"证书已过期"，顺着查才发现模板本身就有问题。

第四关：profile 匹配关

证书和 profile 的绑定关系，报错信息给零线索。profile 过期、证书指纹不匹配、包名对不上——三种情况报错长得一模一样。只能逐项比对排除。

第五关：静默失败关

签名命令"成功"了，不代表签名是对的。装到设备上启动即崩的案例我们都遇到过——签名问题要靠 装机 + hilog 日志回读 才能终审。

这也是为什么要把「构建→签名→装机→日志断言」做成闭环：任何一环的假成功都逃不过真机验证。

解法：harmony_sign 一键封装

这五关的解法全部沉淀进了开源工具 hmharness（MIT 协议）：

npm install -g @hmharness/cli
hmh "创建鸿蒙工程，构建签名装到模拟器跑起来"

harmony_sign 一个调用搞定签名全链（含过期 profile 检测与刷新），配合 harmony_build、harmony_install、harmony_logs，鸿蒙开发的 CI 化从此不需要人肉踩坑。

参考

• GitHub：https://github.com/swsgbl/hmharness
• 证据页：https://swsgbl.github.io/hmharness/evidence/
• 完整破案记录：项目 DEVLOG