前言app.json5是 HarmonyOS 应用中最顶层的配置文件位于AppScope/目录下定义了应用的全局元信息包括包名、版本号、应用图标、应用名称等关键标识。在萌宠日记应用中app.json5 配合应用签名配置共同决定了应用的身份标识和发布信息。本文将从萌宠日记的 app.json5 和签名配置出发深入解析每个字段的含义以及签名配置的完整流程。一、app.json5 的作用与定位1.1 与 module.json5 的分工app.json5 和 module.json5 在 HarmonyOS 配置体系中各司其职对比维度app.json5module.json5所在位置AppScope/entry/src/main/作用范围整个应用单个模块配置内容包名、版本、全局图标Ability、页面、扩展能力修改影响重新签名、重新发布编译打包文件数量1 个整个应用唯一每个模块 1 个1.2 萌宠日记的 app.json5{ app: { bundleName: com.mengchongriji.app, vendor: example, versionCode: 1000000, versionName: 1.0.0, icon: $media:layered_image, label: $string:app_name } }提示app.json5 使用JSON5 格式支持注释和尾逗号与 module.json5 保持一致。二、核心字段详解2.1 bundleName — 应用包名bundleName: com.mengchongriji.appbundleName是应用的唯一标识遵循反向域名命名规则组成部分值说明顶级域名com商业组织二级域名mengchongriji应用名称拼音应用名app应用标识bundleName 的命名规范全局唯一在 HarmonyOS 生态中唯一标识一个应用不可变更应用发布后不能修改 bundleName与签名一致签名证书中的包名必须与 bundleName 匹配长度限制不超过 127 个字节2.2 vendor — 供应商vendor: examplevendor标识应用的开发者或供应商名称。在正式发布时应替换为实际的开发者名称。2.3 版本号配置versionCode: 1000000, versionName: 1.0.0版本号由两个字段组成字段值类型说明versionCode1000000整数内部版本号用于版本比较必须递增versionName1.0.0字符串用户可见的版本名遵循语义化版本版本号管理规范// 语义化版本与 versionCode 的对应关系 // 1.0.0 → 1000000 // 1.0.1 → 1000001 // 1.1.0 → 1001000 // 2.0.0 → 2000000 // 编码规则major * 1000000 minor * 1000 patch版本号升级策略版本变更versionCode 变化versionName 变化场景补丁修复11.0.0 → 1.0.1Bug 修复小功能10001.0.0 → 1.1.0新增功能大版本10000001.0.0 → 2.0.0重大更新三、图标与名称配置3.1 应用图标icon: $media:layered_imageicon引用资源文件中的分层图标layered image{ layered-image: { background: $media:background, foreground: $media:foreground } }分层图标的优势特性说明自适应在不同设备上自动适配形状动态效果支持交互反馈按压、长按系统统一与系统图标风格一致前景背景分离背景层可虚化前景层保持清晰3.2 应用名称label: $string:app_name应用名称引用字符串资源{ string: [ { name: app_name, value: 萌宠日记 } ] }应用名称的显示场景桌面图标下方最近任务列表中应用信息页面通知栏来源标识系统设置中的应用列表四、应用签名配置4.1 签名的作用HarmonyOS 应用签名的作用包括作用说明身份验证确认应用开发者身份完整性校验确保应用未被篡改权限管理签名关联权限的授予应用更新确保更新包来自同一开发者4.2 签名配置文件在build-profile.json5中配置签名信息{ app: { signingConfigs: [], compileSdkVersion: 12, products: [ { name: default, signingConfig: default } ] } }4.3 签名文件类型HarmonyOS 应用签名涉及以下文件文件类型扩展名说明密钥库文件.p12包含私钥和证书证书请求文件.csr证书签名请求调试证书.cer调试用数字证书发布证书.cer发布用数字证书配置文件.p7b包含应用授权信息五、调试与发布配置5.1 调试模式配置// 调试签名的配置 { app: { signingConfigs: [ { name: debug, material: { certPath: path/to/debug.cer, keyStorePath: path/to/debug.p12, keyStorePassword: ******, keyStoreAlias: debug, keyStoreAliasPassword: ****** } } ], products: [ { name: default, signingConfig: debug } ] } }5.2 发布模式配置// 发布签名的配置 { app: { signingConfigs: [ { name: release, material: { certPath: path/to/release.cer, keyStorePath: path/to/release.p12, keyStorePassword: ******, keyStoreAlias: release, keyStoreAliasPassword: ****** } } ], products: [ { name: default, signingConfig: release } ] } }六、compileSdkVersion6.1 编译 SDK 版本compileSdkVersion: 12compileSdkVersion指定编译时使用的HarmonyOS SDK 版本号SDK 版本HarmonyOS 版本API 级别10HarmonyOS 4.0API 1011HarmonyOS 4.1API 1112HarmonyOS 5.0API 126.2 版本兼容性// 同时指定最小和最大兼容版本 { app: { compileSdkVersion: 12, compatibleSdkVersion: 10, targetSdkVersion: 12 } }配置项说明萌宠日记值compileSdkVersion编译 SDK 版本12compatibleSdkVersion兼容的最低 SDK 版本可选未配置targetSdkVersion目标 SDK 版本可选未配置七、多产品配置7.1 product 概念products 支持为不同目标定义不同的配置{ app: { products: [ { name: default, signingConfig: default }, { name: huawei, signingConfig: release } ] } }7.2 多产品场景场景不同 product差异点调试/发布debug / release签名证书不同渠道分发huawei / xiaomi渠道标识不同免费/付费free / pro功能配置不同国内/海外cn / global资源文件不同八、签名流程8.1 自动签名DevEco Studio 提供自动签名功能一键完成签名配置# 在 DevEco Studio 中 Build → Generate Key and CSR → 填写开发者信息 → 完成8.2 手动签名流程有序列表 — 手动签名的完整步骤使用keytool -genkey生成密钥库.p12使用keytool -certreq生成证书请求.csr将 .csr 提交到 AppGallery Connect 获取签名证书下载签名证书.cer和授权文件.p7b在build-profile.json5中配置签名信息使用 DevEco Studio 的 Build → Build HAP 进行签名打包8.3 签名验证# 验证 HAP 包签名 hdc shell aa dump -a -p com.mengchongriji.app # 查看签名信息 hdc shell bm dump -n com.mengchongriji.app九、常见签名问题9.1 签名错误排查错误信息可能原因解决方案INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES签名不一致使用相同签名文件重新打包INSTALL_FAILED_INVALID_APK签名无效重新生成签名证书SIGNATURE_ERROR签名校验失败检查签名配置是否正确BUNDLE_NAME_MISMATCH包名与签名不匹配确保 bundleName 与证书中的包名一致9.2 签名安全建议妥善保管密钥库.p12 文件包含私钥切勿提交到版本控制系统环境分离调试证书和发布证书分开管理定期更新证书到期前及时更新CI/CD 集成在自动化构建流水线中管理签名十、发布前的配置检查10.1 发布检查清单检查项要求萌宠日记状态bundleName正式包名非测试包名✅com.mengchongriji.appvendor实际开发者名称⚠️ 当前为example需替换versionCode比上一个版本大✅1000000versionName语义化版本✅1.0.0发布证书非调试证书⚠️ 需申请发布证书icon正式图标✅ 分层图标配置10.2 配置修改建议vendor 替换将example替换为实际开发者名称版本号管理每次发布前更新 versionCode 和 versionName证书申请通过 AppGallery Connect 申请发布证书签名配置在 CI/CD 中配置自动签名总结本文从萌宠日记的app.json5出发深入解析了 HarmonyOS 应用级配置的完整体系app.json5 核心字段bundleName、vendor、versionCode、versionName图标与名称配置分层图标、引用资源文件应用签名机制调试/发布签名、密钥管理编译 SDK 配置版本兼容性、多产品配置签名流程自动签名、手动签名、签名验证发布检查清单确保配置正确性下一篇我们将深入备份恢复能力集成解析 EntryBackupAbility 的实现细节。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源app.json5 配置文件https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file应用签名概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-signing应用包名配置https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-structure-stage分层图标开发https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/layered-image版本管理规范https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/version-managementAppGallery Connect 签名https://developer.huawei.com/consumer/cn/doc/appgallery-connect/agc-signingHAP 包构建https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-packageDevEco Studio 用户指南https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/deveco-overview
