前言

在 HarmonyOS 应用中，app.json5 位于 AppScope/ 目录下，是整个应用的"全球身份证"——它定义了应用的唯一标识（bundleName）、版本号、全局图标和标签。系统包管理器和应用市场都依赖这个文件的配置来识别和分发应用。

本文以「猫猫大作战」的 AppScope/app.json5 为锚点，逐字段拆解 bundleName 命名规范、版本管理策略、多模块间图标复用、签名配置与发布前的关键检查项。

提示：本系列不讲 ArkTS 基础语法与环境搭建，假设你已跟完第 1–76 篇。本篇是阶段三第 77 篇。

一、项目中的 app.json5

1.1 完整配置

{
  "app": {
    "bundleName": "com.maomaodazuozhan.game",
    "vendor": "maomaodazuozhan",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "description": "$string:app_desc"
  }
}

1.2 字段速查

字段	值	必填	说明
bundleName	com.maomaodazuozhan.game	✅	应用唯一标识，发布后不可更改
vendor	maomaodazuozhan	❌	开发者/组织名称
versionCode	1000000	✅	内部版本号，仅比较大小
versionName	1.0.0	✅	展示给用户的版本名
icon	$media:app_icon	✅	应用全局图标
label	$string:app_name	✅	应用名称
description	$string:app_desc	❌	应用描述

二、bundleName：应用唯一标识

2.1 命名规范

bundleName 是应用在 HarmonyOS 生态中的全局唯一标识，类似 Android 的 packageName 或 iOS 的 Bundle Identifier。

规则	说明	示例
反域名命名法	从通用到具体	com.maomaodazuozhan.game
字母数字点号	只能含小写字母、数字、点	com.example.myapp
每段 1-63 字符	点分隔的每段长度	com / maomaodazuozhan / game
总长度	不超过 127 字符	—
发布后不可改	应用商店上架后不能再修改	⚠️ 发布前必须确认

2.2 错误命名示例

// 🚫 错误命名
"bundleName": "MyGame"              // ❌ 没有反域名结构
"bundleName": "com.猫猫大作战"     // ❌ 不能含中文
"bundleName": "com.MaoMao.Game"    // ❌ 不能含大写字母
"bundleName": "com.maomao.da.zuo.zhan.game" // ⚠️ 段数太多

// ✅ 正确命名
"bundleName": "com.maomaodazuozhan.game"

2.3 bundleName 与签名证书

bundleName 必须与华为 AppGallery Connect 中创建应用的包名完全一致，否则签名校验失败，无法安装或上架。

# 查看已安装应用的 bundleName
hdc shell bm dump -a | grep "bundleName"

三、版本管理策略

3.1 versionCode 规范

versionCode 是一个整数，用于系统判断版本新旧。推荐使用10 位编码法：

格式：AABBBCCCCD

AA    = 主版本（两位，01-99）
BBB   = 次版本（三位，001-999）
CCCC  = 补丁/构建（四位，0001-9999）
D     = 标识位（0=正式版，1=测试版）

示例：
1.0.0    → 1000000000
1.0.1    → 1000001000
1.1.0    → 1001000000
2.0.0    → 2000000000
2.0.0-rc → 2000000001 (测试版)

3.2 猫猫大作战的版本方案

{
  "app": {
    "versionCode": 1000000,
    "versionName": "1.0.0"
  }
}

发布版本	versionCode	versionName	说明
v1.0.0 正式版	1000000	1.0.0	首次上架
v1.0.1 修复版	1000010	1.0.1	修复闪退
v1.1.0 新功能	1001000	1.1.0	新增排行榜
v2.0.0 重大更新	2000000	2.0.0	UI 全面重构

3.3 版本升级策略

// 运行时判断是否需要显示"更新日志"
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  const lastVersion = AppStorage.get<number>('lastVersionCode') ?? 0;
  const currentVersion = 1000000; // 当前 versionCode

  if (lastVersion === 0) {
    // 首次安装
    AppStorage.setOrCreate('isFirstInstall', true);
  } else if (lastVersion < currentVersion) {
    // 版本升级
    AppStorage.setOrCreate('showChangelog', true);
  }

  // 记录本次版本
  AppStorage.setOrCreate('lastVersionCode', currentVersion);
}

四、icon 与 label 的引用规则

4.1 $media 资源引用

{
  "icon": "$media:app_icon"
}

$media:app_icon 指向 AppScope/resources/base/media/app_icon.png。

文件存在位置：

AppScope/resources/base/media/
├── app_icon.png             ← 默认密度
├── app_icon.png             ← 放在 base/media/ 即可

4.2 $string 资源引用

{
  "label": "$string:app_name",
  "description": "$string:app_desc"
}

$string:app_name 指向 AppScope/resources/base/element/string.json：

{
  "string": [
    { "name": "app_name", "value": "猫猫大作战" },
    { "name": "app_desc", "value": "一款可爱的猫咪合并消除游戏" }
  ]
}

4.3 多语言适配

在 AppScope/resources/ 下创建各语言资源目录，自动根据系统语言选择对应资源：

AppScope/resources/
├── base/
│   └── element/string.json          ← 默认（英文/fallback）
├── zh_CN/
│   └── element/string.json          ← 简体中文
├── zh_TW/
│   └── element/string.json          ← 繁体中文
└── en_US/
    └── element/string.json          ← 美式英语

五、app.json5 与 module.json5 的关系

5.1 配置分工

维度	app.json5（AppScope）	module.json5（模块级）
作用域	整个应用	单个 HAP/HSP 模块
bundleName	✅ 定义	❌ 不出现
版本号	✅ 定义	❌ 不出现
全局图标	✅ 定义	❌ 可覆盖
Ability 注册	❌ 不出现	✅ 注册
模块类型	❌ 不出现	✅ 定义
设备类型	❌ 不出现	✅ 定义

5.2 编译合并规则

打包时，两个文件合并成一个完整的 config.json：
app.json5（全局） + module.json5（模块特定） = 最终配置

5.3 图标优先级

模块级图标（module.json5.abilities[].icon） > 应用级图标（app.json5.icon）

如果 module.json5 中没有配置 icon，则使用 app.json5 中的全局图标：

// module.json5 — 使用应用级图标（不单独配置）
{
  "abilities": [
    {
      "name": "EntryAbility"
      // icon 不写 → 使用 app.json5 中的 icon
    }
  ]
}

六、签名与证书配置

6.1 签名文件位置

AppScope 目录下的 app.json5 不包含签名信息，签名配置在 build-profile.json5（项目根目录）中：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "material": {
          "certPath": "/path/to/release.cer",
          "keyPath": "/path/to/key.p7b",
          "profilePath": "/path/to/HMOS.p7b"
        }
      }
    ]
  }
}

6.2 bundleName 与签名证书的绑定

bundleName 必须与申请签名证书时填写的包名完全一致
         ↓
签名证书中的 bundleName ≠ app.json5 中的 bundleName
         ↓
应用安装失败（PARSE_FAILED_BAD_BUNDLE_NAME）

七、常见踩坑

7.1 坑一：bundleName 包含下划线

// 🚫 错误
"bundleName": "com.maomao_dazuozhan.game"  // ❌ 下划线

// ✅ 正确
"bundleName": "com.maomaodazuozhan.game"   // ✅ 全小写加点的组合

7.2 坑二：versionCode 没有递增

// 🚫 错误：上架 v1.0.0 后，v1.0.1 的 versionCode 没有增大
v1.0.0 → versionCode: 1000000
v1.0.1 → versionCode: 1000000  // ❌ 系统认为没更新

// ✅ 正确：versionCode 必须严格递增
v1.0.0 → versionCode: 1000000
v1.0.1 → versionCode: 1000010

7.3 坑三：AppScope 目录下没有 app.json5

// 正确目录结构
maomaodazuozhan/
├── AppScope/
│   └── app.json5           ✅ 必须在这里
├── entry/
│   └── src/main/
│       └── module.json5    ✅ 模块配置
└── build-profile.json5     ✅ 签名配置

八、发布前的配置检查清单

• bundleName 符合反域名命名规则，全小写
• versionCode 比上一发布版本大
• versionName 使用语义化版本（semver）
• icon 引用的图片文件在 AppScope/resources/base/media/ 中存在
• label 引用的字符串在 string.json 中存在且有中英文
• description 准确描述了应用功能
• 签名证书的 bundleName 与 app.json5 一致
• AppScope 目录路径正确

九、总结

app.json5 是 HarmonyOS 应用的全局配置入口，定义了应用的唯一标识、版本号、全局图标和标签。它是系统识别应用、应用市场分发应用的核心依据。

核心要点：

• bundleName 是应用唯一标识，反域名命名，发布后不可更改
• versionCode 整数递增，推荐 10 位编码法
• versionName 用于向用户展示版本号
• icon/label 使用 $media/$string 引用资源，支持多语言
• app.json5 在 AppScope/ 下，与模块级 module.json5 协作
• bundleName 必须与签名证书中的包名完全一致

下一篇预告：第 78 篇将深入 main_pages 路由表——页面注册机制与多页面路由配置。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• app.json5 配置文件参考
• bundleName 命名规范
• 版本管理最佳实践
• 资源目录与 $media/$string 引用
• 签名证书配置
• 开源鸿蒙跨平台社区
• 第 76 篇：module.json5 配置
• 第 78 篇：main_pages 路由表