HarmonyOS开发应用签名——签名配置核心要点签名是HarmonyOS应用安装的通行证没有签名的HAP装不上设备签名不对的HAP也装不上——搞懂签名配置是应用能跑起来的前提。背景与动机你辛辛苦苦打了个HAP包连上设备准备安装结果弹出来一个错误“签名校验失败”。然后你开始各种搜、各种试折腾半天还是装不上。这场景熟悉不签名这事儿开发阶段你可能不太在意——DevEco Studio帮你自动签名了嘛。但到了真机调试、团队协作、发布上架这些环节签名问题就一个接一个地冒出来调试签名和发布签名有啥区别签名文件怎么配换台电脑为什么签名就失效了多人协作怎么共享签名这些问题不搞清楚你就永远在签名失败的泥潭里打转。核心原理为什么需要签名签名解决的是信任问题。设备怎么知道这个HAP是你开发的、没有被篡改靠的就是签名。签名用非对称加密算法你用私钥签名设备用公钥验证。私钥只有你有所以只有你能签出合法的包。私钥签名安装公钥验证是否开发者HAP文件设备签名合法?安装成功拒绝安装HarmonyOS签名体系HarmonyOS的签名体系比Android更严格涉及三层证书调试证书Debug Certificate开发阶段使用只能安装在调试设备上发布证书Release Certificate发布阶段使用可以安装在所有设备上应用签名证书App Signing Certificate华为AGC托管的签名证书上架应用市场时使用签名流程涉及的关键文件文件说明谁生成.p12个人信息交换文件包含私钥开发者通过OpenSSL生成.cer数字证书文件包含公钥华为开发者联盟签发.p7b应用签名Profile文件华为AGC生成.jksJava密钥库调试用DevEco Studio自动生成签名验证机制设备安装HAP时的签名验证流程解析HAP中的签名数据从签名数据中提取证书链验证证书链的合法性是否由华为CA签发用证书中的公钥验证HAP的签名检查签名Profile中的包名和指纹是否匹配全部通过才允许安装代码实战基础用法调试签名配置开发阶段最简单的签名方式DevEco Studio自动帮你搞定// build-profile.json5{app:{signingConfigs:[{name:default,type:HarmonyOS,material:{certpath:C:/Users/Dev/.ohos/config/default_MyApp_xxx.cer,// 证书文件storeFile:C:/Users/Dev/.ohos/config/default_MyApp_xxx.p12,// 密钥库文件storePassword:xxx,// 密钥库密码keyAlias:debugKey,// 密钥别名keyPassword:xxx,// 密钥密码profile:C:/Users/Dev/.ohos/config/default_MyApp_xxx.p7b,// 签名ProfilesignAlg:SHA256withECDSA,// 签名算法storeFileHash:xxx// 密钥库哈希防篡改}}],products:[{name:default,signingConfig:default// 使用名为default的签名配置}]}}这是DevEco Studio自动生成的调试签名配置。你第一次运行项目时IDE会自动生成调试证书和Profile填到这个配置里。但这里有个坑——调试签名只能在调试设备上用。什么是调试设备就是在华为开发者联盟注册过UDID的设备。没有注册的设备调试签名也装不上。进阶用法发布签名配置发布应用时调试签名不够用了需要正式的发布签名第一步生成密钥对和证书请求文件# 生成密钥对.p12文件openssl req-new-x509-keyprivate_key.pem-outcert_request.csr\-newkeyrsa:2048-nodes-keyoutprivate_key.pem\-subj/CCN/STBeijing/LBeijing/OMyCompany/OUDev/CNMyApp\-days3650# 转换为PKCS12格式openssl pkcs12-export-outMyApp_Release.p12\-inkeyprivate_key.pem-incert_request.csr\-namereleaseKey-passoutpass:your_password第二步在华为开发者联盟申请发布证书登录华为开发者联盟 → 证书管理 → 新增证书 → 上传CSR文件 → 下载.cer证书文件。第三步在AGC创建应用并下载Profile登录AppGallery Connect → 我的应用 → 创建应用 → 填写包名 → 下载.p7b签名Profile。第四步配置发布签名// build-profile.json5{app:{signingConfigs:[{name:default,type:HarmonyOS,material:{certpath:signing/MyApp_Release.cer,storeFile:signing/MyApp_Release.p12,storePassword:your_password,keyAlias:releaseKey,keyPassword:your_password,profile:signing/MyApp_Release.p7b,signAlg:SHA256withECDSA}}],products:[{name:default,signingConfig:default}]}}关键安全提示发布签名的.p12文件和密码绝对不能泄露一旦泄露别人就能用你的签名打包恶意应用。建议签名文件不要放在工程目录里放在安全的位置.gitignore中排除签名文件密码不要明文写在配置文件里用环境变量// 更安全的签名配置方式{name:default,type:HarmonyOS,material:{certpath:${SIGN_CERT_PATH},// 环境变量storeFile:${SIGN_STORE_FILE},// 环境变量storePassword:${SIGN_STORE_PASSWORD},// 环境变量keyAlias:${SIGN_KEY_ALIAS},// 环境变量keyPassword:${SIGN_KEY_PASSWORD},// 环境变量profile:${SIGN_PROFILE},// 环境变量signAlg:SHA256withECDSA}}完整示例多环境签名配置实际项目中你可能需要多套签名——调试一套、内测一套、正式发布一套// build-profile.json5{app:{signingConfigs:[{name:debug,type:HarmonyOS,material:{certpath:signing/debug/debug.cer,storeFile:signing/debug/debug.p12,storePassword:debug_pwd,keyAlias:debugKey,keyPassword:debug_pwd,profile:signing/debug/debug.p7b,signAlg:SHA256withECDSA}},{name:beta,type:HarmonyOS,material:{certpath:signing/beta/beta.cer,storeFile:signing/beta/beta.p12,storePassword:${BETA_SIGN_PWD},keyAlias:betaKey,keyPassword:${BETA_SIGN_PWD},profile:signing/beta/beta.p7b,signAlg:SHA256withECDSA}},{name:release,type:HarmonyOS,material:{certpath:${RELEASE_CERT_PATH},storeFile:${RELEASE_STORE_FILE},storePassword:${RELEASE_STORE_PWD},keyAlias:${RELEASE_KEY_ALIAS},keyPassword:${RELEASE_KEY_PWD},profile:${RELEASE_PROFILE},signAlg:SHA256withECDSA}}],products:[{name:default,signingConfig:debug// 默认用调试签名},{name:beta,signingConfig:beta// 内测用beta签名},{name:release,signingConfig:release// 正式用release签名}]}}命令行指定签名配置打包# 调试包hvigorw assembleHap--modemodule-pmoduleentrydefault-pproductdefault# 内测包hvigorw assembleHap--modemodule-pmoduleentrydefault-pproductbeta# 正式发布包hvigorw assembleHap--modemodule-pmoduleentrydefault-pproductrelease签名验证工具// scripts/verify-signature.ets// 验证HAP签名信息的工具脚本import{hapSignVerify}fromohos/hvigor-ohos-plugin;interfaceSignatureInfo{bundleName:string;// 包名appId:string;// 应用IDfingerprint:string;// 证书指纹validity:{// 证书有效期notBefore:string;notAfter:string;};permissions:string[];// 声明的权限}// 解析HAP签名信息functionverifyHapSignature(hapPath:string):SignatureInfo|null{try{constresulthapSignVerify.verify(hapPath);if(result.code0){return{bundleName:result.bundleName,appId:result.appId,fingerprint:result.fingerprint,validity:{notBefore:result.notBefore,notAfter:result.notAfter},permissions:result.permissions||[]};}console.error(签名验证失败:${result.message});returnnull;}catch(error){console.error(签名验证异常:${error});returnnull;}}// 检查证书是否即将过期functioncheckCertExpiry(hapPath:string,warnDays:number30):void{constinfoverifyHapSignature(hapPath);if(!info)return;constnotAfternewDate(info.validity.notAfter);constnownewDate();constdaysLeftMath.floor((notAfter.getTime()-now.getTime())/(1000*60*60*24));if(daysLeft0){console.error(❌ 证书已过期请立即续期);}elseif(daysLeftwarnDays){console.warn(⚠️ 证书将在${daysLeft}天后过期请尽快续期);}else{console.info(✅ 证书有效期剩余${daysLeft}天);}}踩坑与注意事项坑1调试设备未注册UDID调试签名安装失败最常见的原因就是设备UDID没在华为开发者联盟注册。注册流程开发者联盟 → 设备管理 → 添加设备 → 输入UDID。获取设备UDID的方法# 通过hdc命令获取hdc shell param get const.ohos.serial# 或者通过DevEco Studio的设备管理器查看# Tools → Device Manager → 点击设备详情坑2签名Profile过期.p7b签名Profile有有效期过期后打包的HAP无法安装。调试Profile有效期通常是一年发布Profile有效期更长。解法定期检查Profile有效期过期前重新申请。建议在CI脚本中加入自动检查# 检查p7b文件有效期openssl pkcs7-informDER-inMyApp.p7b-print_certs-noout-text|grep-A2Not After坑3签名配置中密码明文泄露把.p12密码直接写在build-profile.json5里然后提交到Git——这是最常见的安全事故。一旦仓库泄露签名私钥就暴露了。解法.gitignore中加入signing/目录和*.p12、*.jks文件密码用环境变量CI中通过Secret注入本地开发用local.properties存放敏感信息这个文件也在.gitignore中坑4多模块签名不一致多HAP工程中Entry和Feature模块必须使用同一套签名。如果Entry用调试签名、Feature用发布签名安装时会报签名不匹配。解法在工程级build-profile.json5中统一配置签名所有模块共用。不要在模块级别单独配置签名。坑5签名算法不兼容HarmonyOS 5.0默认签名算法是SHA256withECDSA但有些旧设备只支持SHA256withRSA。如果你的目标设备包含旧设备需要同时支持两种算法。解法signAlg字段使用默认值SHA256withECDSA即可HarmonyOS的签名工具会自动处理兼容性。如果确实遇到旧设备签名验证失败可以尝试切换为SHA256withRSA。HarmonyOS 6适配说明HarmonyOS 6对签名机制做了以下更新SHA-384签名算法支持新增SHA384withECDSA签名算法安全性更高。新申请的发布证书默认使用此算法。AGC托管签名增强AppGallery Connect的托管签名功能升级支持自动签名和密钥轮换。开发者不再需要自己管理私钥AGC帮你签名更安全。签名Profile权限细化HarmonyOS 6的签名Profile新增权限分级不同等级的权限需要不同等级的证书。比如ohos.permission.INSTALL_BUNDLE需要系统级证书普通开发者证书无法申请。多证书签名支持一个HAP使用多个证书签名用于不同安全等级的代码段。这在金融、政务等高安全场景下有用。证书透明性CT日志HarmonyOS 6要求发布证书必须记录到CT日志中防止证书被恶意签发。新申请的证书会自动加入CT日志无需开发者额外操作。总结签名这事儿开发阶段你可能觉得能用就行但到了发布阶段任何一个签名问题都能让你卡住半天。记住这几个关键点调试签名只能调试用发布必须用发布签名签名文件和密码是命根子泄露了等于把应用交给了别人多模块签名必须一致不同签名会导致安装失败证书和Profile有有效期过期前记得续期