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 的命名规范：

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": "萌宠日记" }
]
}

应用名称的显示场景：

四、应用签名配置

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 手动签名流程

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

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 应用级配置的完整体系：

下一篇我们将深入 备份恢复能力集成，解析 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