多模块签名与证书管理一、签名在 HarmonyOS 中的重要性应用签名是 HarmonyOS 安全体系的核心组成部分。每个应用在发布前都必须经过签名签名的目的是身份验证确认应用的开发者身份防止应用被篡改完整性保护确保应用包在签名后没有被修改权限授权某些系统级权限要求应用必须经过特定签名才能使用应用升级同包名的应用必须使用相同签名才能覆盖安装在我们的 11 模块架构中签名配置在根级别的build-profile.json5中统一管理所有子模块共享同一个签名配置。二、build-profile.json5 中的 signingConfigs 配置根目录的build-profile.json5中定义了签名配置{ app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.cer, keyAlias: debugKey, keyPassword: 0000001B..., profile: C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.p7b, signAlg: SHA256withECDSA, storeFile: C:\\Users\\hyh\\.ohos\\config\\default_Exam1.0.4_xxx.p12, storePassword: 0000001B... } } ] } }配置字段解析name签名配置的名称用于在 product 中引用type签名类型HarmonyOS 应用固定为 “HarmonyOS”material签名材料签名材料中的文件类型文件格式用途certpath.cer数字证书包含公钥和开发者信息storeFile.p12PKCS#12 密钥库包含私钥profile.p7b应用签名配置文件包含权限声明三、p7b 证书与 profile 文件.cer 证书数字证书.cer文件是开发者的数字证书由华为开发者联盟颁发。它包含了开发者的公钥开发者身份信息名称、组织等证书有效期颁发机构华为 CA的签名.p7bPKCS#7签名配置文件.p7b文件不是传统的证书而是包含应用签名配置信息的 PKCS#7 容器。它涉及应用的包名bundleName应用的权限声明应用的调试/发布模式授权的设备列表调试模式下p7b 文件的作用是告诉系统该应用可以做什么权限、由谁签名、可以在什么设备上运行。.p12PKCS#12密钥库.p12文件是私钥的加密容器。它受密码保护storePassword包含了开发者的私钥用于签名对应的数字证书安全性警告签名的私钥和密码是应用安全的核心。.p12文件和密码不应该提交到版本控制系统中。在我们的项目中这些文件存储在用户目录.ohos/config/下而不是项目目录中。四、调试签名 vs 发布签名调试签名Debug用于开发阶段在模拟器或调试设备上运行证书由 DevEco Studio 自动生成有效期通常较长如 3650 天限制较少可以在所有调试设备上运行配置在buildModeSet中的debug模式发布签名Release用于发布到应用市场证书需要在华为开发者联盟正式申请有更严格的权限和安装限制配置在buildModeSet中的release模式buildModeSet: [ { name: debug }, { name: release } ]在构建时通过--mode参数指定使用 debug 还是 release 配置。Hvigor 会根据配置选择对应的签名材料。五、多模块签名策略在 11 模块架构中签名策略是统一签名统一签名配置所有模块使用根目录build-profile.json5中定义的同一套签名配置模块不单独签名HAR 模块如 commonLib在开发阶段不需要签名只有在最终打包为 HAP 时才签名entry 模块继承签名entry 作为应用入口模块在构建 HAP 包时应用签名这种策略的好处是签名配置集中管理一处修改所有模块生效避免多个模块使用不同签名导致的安装冲突简化 CI/CD 配置只需维护一套签名六、签名相关的常见问题1. 签名过期数字证书有有效期限制。证书过期后安装已签名的应用会失败。解决方案在华为开发者联盟重新申请证书更新signingConfigs中的文件路径。2. 包名不匹配如果打包时app.json5中的 bundleName 与申请证书时使用的包名不同签名会失败。3. 密码错误.p12文件的 storePassword 和keyPassword必须正确。如果密码错误构建过程中的签名步骤会失败。4. 多开发者协作不同开发者有不同的签名证书和密码。在团队协作中建议每个开发者使用自己的调试证书发布证书由项目管理员保管CI/CD 系统使用专用的发布证书七、总结签名是多模块 HarmonyOS 应用发布前的必要环节。在 11 模块架构中签名配置通过根build-profile.json5的signingConfigs统一管理所有模块共享同一套签名材料。.cer 证书、.p7b profile 文件和 .p12 密钥库构成了完整的签名体系。调试和发布模式使用不同的签名配置确保了开发和生产的隔离。妥善管理签名文件和密码是应用安全的重要防线。
