HarmonyOS之app.json5功能详解

🧩 一、app.json5 核心功能详解

1. 应用标识与基本信息

代码示例：

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

2. 应用显示信息

代码示例：

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

3. API 兼容性

代码示例：

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

4. 调试与检测工具

代码示例：

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

5. 设备差异化配置

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

代码示例：

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

6. 应用多开模式

代码示例：

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

7. 云能力配置

代码示例：

{
  "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 的配置是开发高质量跨端应用的基础。