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

前言

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

版本号由两个字段组成：

字段值类型说明
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_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 级别
10HarmonyOS 4.0API 10
11HarmonyOS 4.1API 11
12HarmonyOS 5.0API 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