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

前言

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

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

一、app.json5 的作用与定位

1.1 与 module.json5 的分工

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

对比维度	app.json5	module.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.app"

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

组成部分	值	说明
顶级域名	com	商业组织
二级域名	mengchongriji	应用名称拼音
应用名	app	应用标识

bundleName 的命名规范：

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

2.2 vendor --- 供应商

"vendor": "example"

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

2.3 版本号配置

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

版本号由两个字段组成：

字段	值	类型	说明
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

版本号升级策略：

版本变更	versionCode 变化	versionName 变化	场景
补丁修复	+1	1.0.0 → 1.0.1	Bug 修复
小功能	+1000	1.0.0 → 1.1.0	新增功能
大版本	+1000000	1.0.0 → 2.0.0	重大更新

三、图标与名称配置

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 应用签名涉及以下文件：

文件类型	扩展名	说明
密钥库文件	.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"
      }
    ]
  }
}

六、compileSdkVersion

6.1 编译 SDK 版本

"compileSdkVersion": 12

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

SDK 版本	HarmonyOS 版本	API 级别
10	HarmonyOS 4.0	API 10
11	HarmonyOS 4.1	API 11
12	HarmonyOS 5.0	API 12

6.2 版本兼容性

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

配置项	说明	萌宠日记值
compileSdkVersion	编译 SDK 版本	12
compatibleSdkVersion	兼容的最低 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 手动签名流程

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

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 签名错误排查

错误信息	可能原因	解决方案
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.app
vendor	实际开发者名称	⚠️ 当前为 example，需替换
versionCode	比上一个版本大	✅ 1000000
versionName	语义化版本	✅ 1.0.0
发布证书	非调试证书	⚠️ 需申请发布证书
icon	正式图标	✅ 分层图标配置

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