前言在 HarmonyOS 应用中app.json5位于AppScope/目录下是整个应用的“全球身份证“——它定义了应用的唯一标识bundleName、版本号、全局图标和标签。系统包管理器和应用市场都依赖这个文件的配置来识别和分发应用。本文以「猫猫大作战」的AppScope/app.json5为锚点逐字段拆解 bundleName 命名规范、版本管理策略、多模块间图标复用、签名配置与发布前的关键检查项。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–76 篇。本篇是阶段三第 77 篇。一、项目中的 app.json51.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 字段速查字段值必填说明bundleNamecom.maomaodazuozhan.game✅应用唯一标识发布后不可更改vendormaomaodazuozhan❌开发者/组织名称versionCode1000000✅内部版本号仅比较大小versionName1.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.game2.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 } }发布版本versionCodeversionName说明v1.0.0 正式版10000001.0.0首次上架v1.0.1 修复版10000101.0.1修复闪退v1.1.0 新功能10010001.1.0新增排行榜v2.0.0 重大更新20000002.0.0UI 全面重构3.3 版本升级策略// 运行时判断是否需要显示更新日志 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const lastVersion AppStorage.getnumber(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.json5AppScopemodule.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: 10000107.3 坑三AppScope 目录下没有 app.json5// 正确目录结构 maomaodazuozhan/ ├── AppScope/ │ └── app.json5 ✅ 必须在这里 ├── entry/ │ └── src/main/ │ └── module.json5 ✅ 模块配置 └── build-profile.json5 ✅ 签名配置八、发布前的配置检查清单bundleName符合反域名命名规则全小写versionCode比上一发布版本大versionName使用语义化版本semvericon引用的图片文件在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 路由表