前言在 HarmonyOS Stage 模型中AppScope/app.json5是应用级全局清单文件。它与模块级module.json5形成层级关系app.json5 描述整个应用的全局属性包名、版本、图标而 module.json5 描述具体模块的能力与权限。本文将以开源鸿蒙笔友通信应用 xiexin 的app.json5为蓝本详细剖析应用级配置的各个字段重点讲解 bundleName 命名规范、版本号策略、图标资源引用、与 module.json5 的层级关系以及多模块工程下的 app.json5 实践。提示本文假设你已经了解 HarmonyOS Stage 模型基础。如果还不熟悉建议先阅读前四篇文章。一、app.json5 的定位app.json5是 HarmonyOS应用清单位于工程的AppScope/目录下。它告诉系统这个应用叫什么名字、用什么包名应用版本号是多少应用的图标和标签是什么应用支持的 SDK 版本范围对于 xiexin 项目app.json5位于AppScope/app.json5这是工程级的配置文件所有模块共享这一份应用清单。二、xiexin 的 app.json5 完整内容xiexin 的app.json5内容极其简洁{ app: { bundleName: com.xiexin.letter, vendor: xiexin, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name } }整个文件只有 6 个字段。这种极简风格实际上是 HarmonyOS 官方推荐的写法——把所有可省略的字段都省略掉让配置文件保持清爽。下面我们逐一拆解每个字段。三、app 顶层字段详解3.1 bundleNamebundleName: com.xiexin.letter应用包名是应用在系统中的唯一标识。它类似于 Android 的applicationId或 iOS 的Bundle Identifier。bundleName 命名规范反向域名格式com.公司名.产品名如com.xiexin.letter全小写避免大写字母使用点分隔每段之间用.分隔每段以字母开头不以数字或特殊字符开头bundleName 的不可变性提示bundleName 一旦发布到应用市场就不能再修改。修改 bundleName 会被系统视为全新应用老用户无法通过更新升级到新版本。bundleName 与签名证书的关系签名证书的bundleName必须与app.json5的bundleName完全一致否则签名验证失败。这要求开发期使用 debug 证书bundleName 可以任意发布期使用 release 证书bundleName 必须与应用市场注册的一致3.2 vendorvendor: xiexin应用厂商名称标识应用的发布者。这个字段对用户不可见主要用于应用市场的厂商展示系统的应用信息页面后台数据分析提示vendor 字段虽小但建议填写真实厂商名便于用户识别应用来源。3.3 versionCode 与 versionNameversionCode: 1000000, versionName: 1.0.0这两个字段共同描述应用版本versionCode版本号整数用于系统内部比较版本高低versionName版本名字符串对用户可见versionCode 的命名规范xiexin 使用的versionCode: 1000000遵循主版本.次版本.修订版本的格式1000000 1 * 1000000 0 * 1000 0 * 1 ^主版本 ^次版本 ^修订版本这种格式的好处是易于比较1.0.0 (1000000) 1.0.1 (1000001) 1.1.0 (1001000)扩展空间大每个段支持 0-999足够用十年整数运算方便代码中比较versionName 的命名规范xiexin 使用的versionName: 1.0.0遵循语义化版本规范主版本1不兼容的 API 修改次版本0向下兼容的功能性新增修订版本0向下兼容的问题修正提示versionName 是字符串可以包含任意字符。建议遵循X.Y.Z格式便于用户理解。可选地追加预发布标识如1.0.0-beta.1、1.0.0-rc.1。版本升级的硬约束应用市场升级时有严格约束新版本的 versionCode 必须大于老版本bundleName 必须一致签名证书必须一致任何一个约束不满足升级都会失败。3.4 iconicon: $media:app_icon应用图标引用AppScope/resources/base/media/app_icon.png。icon 资源的查找规则系统查找icon资源时遵循以下优先级AppScope/resources/qualifier/media/app_icon.png限定目录优先AppScope/resources/base/media/app_icon.png默认目录其中qualifier可以是dark深色模式zh_CN、en_US多语言phone、tablet多设备icon 尺寸规范应用图标需要满足以下尺寸规范用途尺寸格式桌面图标1024x1024源图PNG桌面图标裁剪后192x192PNG启动器小图标96x96PNG通知栏图标24x24PNG提示HarmonyOS 提供了分层图标layered-image特性允许图标在不同主题下自适应。具体用法可参考HarmonyOS 分层图标设计。3.5 labellabel: $string:app_name应用名称引用AppScope/resources/base/element/string.json中的app_name字段。string.json 文件结构AppScope/resources/base/element/string.json文件结构如下{ string: [ { name: app_name, value: 写心 } ] }每个字符串资源包含name字符串资源名称value字符串值多语言适配通过在AppScope/resources/下创建限定目录可以实现多语言适配AppScope/resources/ ├── base/element/string.json # 默认中文 ├── en_US/element/string.json # 英文 └── zh_CN/element/string.json # 中文显式声明en_US/element/string.json内容{ string: [ { name: app_name, value: Xiexin } ] }提示多语言适配时每个限定目录的string.json必须包含相同的name字段。否则在某种语言环境下会出现字符串资源不存在的错误。四、app.json5 的扩展字段xiexin 当前没有使用 app.json5 的扩展字段但 HarmonyOS 还支持以下可选字段4.1 minAPIVersion、targetAPIVersion、apiReleaseType{ app: { minAPIVersion: 11, targetAPIVersion: 12, apiReleaseType: Release, // ... } }这三个字段描述应用对 HarmonyOS API 的依赖字段说明minAPIVersion应用支持的最低 API 版本targetAPIVersion应用目标 API 版本推荐值apiReleaseTypeAPI 版本类型Release/Beta/CanaryAPI 版本与 HarmonyOS 系统版本对应关系API 版本HarmonyOS 版本9HarmonyOS 3.110HarmonyOS 4.011HarmonyOS 4.112HarmonyOS 5.013HarmonyOS 5.1提示minAPIVersion越低能覆盖的用户越多但可用的 API 越少。建议设置为目标 API 版本的前两个版本平衡兼容性和功能。4.2 debug{ app: { debug: true, // ... } }调试模式标志可选值true调试模式应用可以被 DevEco Studio 调试false发布模式应用不能被调试提示发布到应用市场前必须确认debug: false。debug 模式的应用会暴露调试端口存在安全风险。4.3 icon 与 label 的多限定目录{ app: { icon: $media:app_icon, label: $string:app_name } }这两个字段可以引用多个限定目录下的资源系统会根据当前环境自动选择AppScope/resources/ ├── base/ │ ├── element/string.json # app_name: 写心 │ └── media/app_icon.png # 默认图标 ├── dark/ │ └── media/app_icon.png # 深色模式图标 └── en_US/ └── element/string.json # app_name: Xiexin深色模式适配示例AppScope/resources/base/media/app_icon.png浅色背景 深色文字AppScope/resources/dark/media/app_icon.png深色背景 浅色文字当系统切换到深色模式时自动使用dark目录下的图标。五、app.json5 与 module.json5 的层级关系HarmonyOS 工程的配置文件呈现两层级结构AppScope/app.json5应用级清单entry/src/main/module.json5entry 模块清单settings/src/main/module.json5settings 模块清单share/src/main/module.json5share 模块清单5.1 字段归属规则字段类别归属层级bundleName、versionCode、vendorapp.json5模块能力abilities、permissionsmodule.json5全局资源应用图标、应用名app.json5模块资源页面字符串、模块图标module.json55.2 多模块工程的 app.json5如果 xiexin 未来扩展为多模块工程结构如下xiexin/ ├── AppScope/ │ └── app.json5 # 应用级清单全局 ├── entry/ # 主模块 │ └── src/main/module.json5 ├── settings/ # 设置模块feature │ └── src/main/module.json5 └── share/ # 分享模块feature └── src/main/module.json5每个模块都有自己的 module.json5但所有模块共享同一个 app.json5。提示entry 模块是必须的feature 模块是可选的。一个工程至少要有 entry 模块。六、app.json5 与构建配置的协同app.json5与工程级build-profile.json5共同决定应用如何构建。6.1 build-profile.json5 的关键字段// build-profile.json5 { app: { signingConfigs: [/* 签名配置 */], products: [ { name: default, signingConfig: default, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 6.0.2(22), runtimeOS: HarmonyOS } ], buildModeSet: [ { name: debug }, { name: release } ] }, modules: [ { name: entry, srcPath: ./entry, targets: [/* ... */] } ] }6.2 三层配置文件的协同关系配置文件层级核心职责AppScope/app.json5应用级全局属性包名、版本、图标build-profile.json5工程级构建配置签名、products、modulesentry/src/main/module.json5模块级模块能力abilities、permissions、pages三者通过 bundleName、moduleName 等字段建立关联。七、app.json5 的多渠道构建实践HarmonyOS 支持通过products字段实现多渠道构建。7.1 配置多个 product// build-profile.json5 { app: { products: [ { name: default, signingConfig: default, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 6.0.2(22), runtimeOS: HarmonyOS }, { name: preview, signingConfig: preview, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 6.0.2(22), runtimeOS: HarmonyOS } ] } }7.2 不同 product 使用不同 app.json5 字段通过在build-profile.json5中覆盖 app.json5 的字段可以实现多渠道构建{ app: { products: [ { name: default, buildOption: { arkOptions: { buildProfileFields: { app: { versionName: 1.0.0-default, versionCode: 1000000 } } } } } ] } }提示多渠道构建是大型应用发布的标配。建议在 CI/CD 流程中通过脚本动态生成 app.json5避免手动维护多个版本。八、app.json5 与应用市场审核app.json5 的某些字段直接影响应用市场审核结果。以下是几个关键点8.1 bundleName 唯一性应用市场会校验 bundleName 的唯一性。如果 bundleName 已被其他开发者注册应用无法上架。提示建议在应用市场提前注册公司名或品牌名作为 bundleName 前缀避免冲突。8.2 版本号一致性应用市场要求新版本的versionCode严格大于老版本。如果发布时versionCode没有递增审核会被驳回。8.3 icon 与 label 合规应用图标和名称需要满足不含敏感内容暴力、色情、政治不模仿系统应用图标不使用其他品牌的商标提示建议在发布前对照应用市场的审核规范逐项检查 app.json5 的配置。九、app.json5 的扩展实践让我们为 xiexin 扩展 app.json5添加完整的可选字段{ app: { bundleName: com.xiexin.letter, vendor: xiexin, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name, minAPIVersion: 11, targetAPIVersion: 12, apiReleaseType: Release } }这个配置最低支持 API 11HarmonyOS 4.1目标 API 12HarmonyOS 5.0使用 Release 版本 API十、app.json5 调试技巧10.1 查看运行时 app.json5可以通过以下代码读取运行时的 app.json5import{bundleManager}fromkit.AbilityKit;constinfobundleManager.getBundleInfoForSelfSync(bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT);console.log(bundleName:${info.name});console.log(versionCode:${info.versionCode});console.log(versionName:${info.versionName});10.2 调试资源引用如果$media:app_icon引用错误运行时会报错Error: Resource not found: $media:app_icon排查步骤检查AppScope/resources/base/media/下是否有app_icon.png检查文件名是否完全匹配区分大小写检查图片格式是否正确PNG、JPG提示建议在 DevEco Studio 中使用资源管理器视图可视化查看所有资源引用。总结本文详细剖析了 HarmonyOS app.json5 应用级全局清单文件的各个字段重点讲解了 bundleName 命名规范、版本号策略、图标资源引用、与 module.json5 的层级关系以及多模块工程下的 app.json5 实践。理解 app.json5 的关键是把握三个层级应用级app.json5→ 工程级build-profile.json5→ 模块级module.json5。这三个层级通过 bundleName、moduleName 等字段建立关联共同构成了 HarmonyOS 应用配置的基础设施。下一篇文章我们将深入 SplashPage剖析启动引导流程与启动状态判断的实现。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHarmonyOS app.json5 配置https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-fileHarmonyOS 应用配置文件概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-overview-stageHarmonyOS 分层图标设计https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/layered-imageHarmonyOS 资源分类与访问https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-accessHarmonyOS bundleManager 模块https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-bundleManagerHarmonyOS 多语言适配https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/i18n-guidelinesHarmonyOS 深色模式适配https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-dark-light-adaptation
