HarmonyOS应用开发实战：萌宠日记 - json5-与应用签名配置

前言

app.json5是 HarmonyOS 应用中最顶层的配置文件，位于AppScope/目录下，定义了应用的全局元信息，包括包名、版本号、应用图标、应用名称等关键标识。在萌宠日记应用中，app.json5 配合应用签名配置，共同决定了应用的身份标识和发布信息。

本文将从萌宠日记的 app.json5 和签名配置出发，深入解析每个字段的含义，以及签名配置的完整流程。

一、app.json5 的作用与定位

1.1 与 module.json5 的分工

app.json5 和 module.json5 在 HarmonyOS 配置体系中各司其职：

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.app"

bundleName是应用的唯一标识，遵循反向域名命名规则：

bundleName 的命名规范：

1. 全局唯一：在 HarmonyOS 生态中唯一标识一个应用
2. 不可变更：应用发布后不能修改 bundleName
3. 与签名一致：签名证书中的包名必须与 bundleName 匹配
4. 长度限制：不超过 127 个字节

2.2 vendor — 供应商

"vendor": "example"

vendor标识应用的开发者或供应商名称。在正式发布时应替换为实际的开发者名称。

2.3 版本号配置

"versionCode": 1000000, "versionName": "1.0.0"

版本号由两个字段组成：

版本号管理规范：

// 语义化版本与 versionCode 的对应关系 // 1.0.0 → 1000000 // 1.0.1 → 1000001 // 1.1.0 → 1001000 // 2.0.0 → 2000000 // 编码规则：major * 1000000 + minor * 1000 + patch

版本号升级策略：

三、图标与名称配置

3.1 应用图标

"icon": "$media:layered_image"

icon引用资源文件中的分层图标（layered image）：

{ "layered-image": { "background": "$media:background", "foreground": "$media:foreground" } }

分层图标的优势：

3.2 应用名称

"label": "$string:app_name"

应用名称引用字符串资源：

{ "string": [ { "name": "app_name", "value": "萌宠日记" } ] }

应用名称的显示场景：

1. 桌面图标下方
2. 最近任务列表中
3. 应用信息页面
4. 通知栏来源标识
5. 系统设置中的应用列表

四、应用签名配置

4.1 签名的作用

HarmonyOS 应用签名的作用包括：

4.2 签名配置文件

在build-profile.json5中配置签名信息：

{ "app": { "signingConfigs": [], "compileSdkVersion": 12, "products": [ { "name": "default", "signingConfig": "default" } ] } }

4.3 签名文件类型

HarmonyOS 应用签名涉及以下文件：

五、调试与发布配置

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" } ] } }

六、compileSdkVersion

6.1 编译 SDK 版本

"compileSdkVersion": 12

compileSdkVersion指定编译时使用的HarmonyOS SDK 版本号：

6.2 版本兼容性

// 同时指定最小和最大兼容版本 { "app": { "compileSdkVersion": 12, "compatibleSdkVersion": 10, "targetSdkVersion": 12 } }

七、多产品配置

7.1 product 概念

products 支持为不同目标定义不同的配置：

{ "app": { "products": [ { "name": "default", "signingConfig": "default" }, { "name": "huawei", "signingConfig": "release" } ] } }

7.2 多产品场景

八、签名流程

8.1 自动签名

DevEco Studio 提供自动签名功能，一键完成签名配置：

# 在 DevEco Studio 中 Build → Generate Key and CSR → 填写开发者信息 → 完成

8.2 手动签名流程

有序列表 — 手动签名的完整步骤：

1. 使用keytool -genkey生成密钥库（.p12）
2. 使用keytool -certreq生成证书请求（.csr）
3. 将 .csr 提交到 AppGallery Connect 获取签名证书
4. 下载签名证书（.cer）和授权文件（.p7b）
5. 在build-profile.json5中配置签名信息
6. 使用 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 签名错误排查

9.2 签名安全建议

• 妥善保管密钥库：.p12 文件包含私钥，切勿提交到版本控制系统
• 环境分离：调试证书和发布证书分开管理
• 定期更新：证书到期前及时更新
• CI/CD 集成：在自动化构建流水线中管理签名

十、发布前的配置检查

10.1 发布检查清单

10.2 配置修改建议

• vendor 替换：将"example"替换为实际开发者名称
• 版本号管理：每次发布前更新 versionCode 和 versionName
• 证书申请：通过 AppGallery Connect 申请发布证书
• 签名配置：在 CI/CD 中配置自动签名

总结

本文从萌宠日记的app.json5出发，深入解析了 HarmonyOS 应用级配置的完整体系：

1. app.json5 核心字段：bundleName、vendor、versionCode、versionName
2. 图标与名称配置：分层图标、引用资源文件
3. 应用签名机制：调试/发布签名、密钥管理
4. 编译 SDK 配置：版本兼容性、多产品配置
5. 签名流程：自动签名、手动签名、签名验证
6. 发布检查清单：确保配置正确性

下一篇我们将深入备份恢复能力集成，解析 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-management
• AppGallery Connect 签名：https://developer.huawei.com/consumer/cn/doc/appgallery-connect/agc-signing
• HAP 包构建：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package
• DevEco Studio 用户指南：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/deveco-overview