HarmonyOS之app.json5功能详解 - 实践

一、app.json5 核心功能详解

1. 应用标识与基本信息

配置项	说明	示例
bundleName	唯一标识应用的Bundle名称，命名需符合反域名规范（如 com.example.app）。	"bundleName": "com.example.myapp"
versionCode	应用版本号（整数），用于判断版本更新（新版本需大于旧版本）。	"versionCode": 1000000
versionName	用户可见的版本号（字符串），推荐四段式（如 1.0.0.0）。	"versionName": "1.0.0"
vendor	开发厂商信息（非必需）。	"vendor": "MyCompany"

代码示例：

{
"app": {
"bundleName": "com.example.myapp",
"versionCode": 1000000,
"versionName": "1.0.0",
"vendor": "MyCompany"
}
}

---

2. 应用显示信息

配置项	说明	示例
icon	应用图标资源路径（支持 $media:xxx）。	"icon": "$media:app_icon"
label	应用名称（支持多语言，通过 $string:xxx 引用）。	"label": "$string:app_name"
description	应用描述信息（非必需）。	"description": "$string:description"

代码示例：

{
"app": {
"icon": "$media:app_icon",
"label": "$string:app_name",
"description": "$string:description"
}
}

---

3. API 兼容性

配置项	说明	示例
minAPIVersion	应用运行所需的最小 SDK API 版本（由构建系统自动生成）。	"minAPIVersion": 9
targetAPIVersion	应用的目标 API 版本（由构建系统自动生成）。	"targetAPIVersion": 9
apiReleaseType	API 版本类型（Release/BetaN/CanaryN）	"apiReleaseType": "Release"

代码示例：

{
"app": {
"minAPIVersion": 9,
"targetAPIVersion": 9,
"apiReleaseType": "Release"
}
}

---

4. 调试与检测工具

配置项	说明	示例
debug	是否允许调试（开发阶段设为 true，发布阶段设为 false）。	"debug": false
asanEnabled	启用地址越界检测工具（Asan）。	"asanEnabled": true
hwasanEnabled	启用硬件辅助地址检测工具（HWAsan）。	"hwasanEnabled": true
ubsanEnabled	启用未定义行为检测工具（UBsan）。	"ubsanEnabled": true

代码示例：

{
"app": {
"debug": false,
"asanEnabled": true,
"hwasanEnabled": true,
"ubsanEnabled": true
}
}

---

5. 设备差异化配置

支持为不同设备（如 tablet、tv、car）单独配置 minAPIVersion，若未配置则使用全局值。

代码示例：

{
"app": {
"minAPIVersion": 9,
"tablet": {
"minAPIVersion": 8
},
"tv": {
"minAPIVersion": 7
}
}
}

---

6. 应用多开模式

配置项	说明	示例
multiAppMode	配置多开模式（multiInstance 或 appClone）。	"multiAppMode": {"multiAppModeType": "appClone", "maxCount": 5}

代码示例：

{
"app": {
"multiAppMode": {
"multiAppModeType": "appClone",
"maxCount": 5
}
}
}

---

7. 云能力配置

配置项	说明	示例
cloudFileSyncEnabled	启用端云文件同步。	"cloudFileSyncEnabled": true
cloudStructuredDataSyncEnabled	启用端云结构化数据同步（API 20+）。	"cloudStructuredDataSyncEnabled": true

代码示例：

{
"app": {
"cloudFileSyncEnabled": true,
"cloudStructuredDataSyncEnabled": true
}
}

---

8. 字体适配控制

通过 configuration 标签引用 profile 文件，控制字体是否跟随系统变化。

代码示例：

{
"app": {
"configuration": "$profile:font_config"
}
}

Profile 文件（font_config.json）：

{
"fontSizeScale": "followSystem",
"fontSizeMaxScale": "1.75"
}

---

9. 环境变量配置

通过 appEnvironments 为第三方库提供运行时环境变量。

代码示例：

{
"app": {
"appEnvironments": [
{
"name": "ENV_VAR1",
"value": "value1"
},
{
"name": "ENV_VAR2",
"value": "value2"
}
]
}
}

---

二、完整配置示例

{
"app": {
"bundleName": "com.example.myapp",
"versionCode": 1000000,
"versionName": "1.0.0",
"vendor": "MyCompany",
"icon": "$media:app_icon",
"label": "$string:app_name",
"description": "$string:description",
"minAPIVersion": 9,
"targetAPIVersion": 9,
"apiReleaseType": "Release",
"debug": false,
"tablet": {
"minAPIVersion": 8
},
"multiAppMode": {
"multiAppModeType": "appClone",
"maxCount": 5
},
"cloudFileSyncEnabled": true,
"configuration": "$profile:font_config",
"appEnvironments": [
{
"name": "ENV_VAR1",
"value": "value1"
}
]
}
}

---

✅ 三、关键注意事项

1. 命名规范

   • bundleName 必须符合反域名格式（如 com.example.myapp）。
   • 字符串长度限制：7~128 字节。

2. 版本管理

   • versionCode 必须递增（新版本 > 旧版本）。
   • versionName 推荐使用四段式（如 1.0.0.0）。

3. 设备适配

   • 为不同设备（tablet、tv 等）单独配置 minAPIVersion。

4. 调试工具

   • 发布版本关闭所有 Sanitizer（asanEnabled、hwasanEnabled 等）。

5. 字体适配

   • 通过 configuration 标签控制字体跟随系统变化，避免布局错乱。

---

四、总结

app.json5 是 HarmonyOS/OpenHarmony 应用的核心配置文件，涵盖了应用标识、兼容性、调试、多开、云能力等关键功能。通过合理配置，开发者可以实现：

• 精确控制应用行为（如调试模式、多开模式）。
• 适配不同设备（tablet、tv 等）。
• 提升用户体验（如字体适配、云同步）。
• 优化安全性与稳定性（内存检测工具）。

掌握 app.json5 的配置是开发高质量跨端应用的基础。