🧩 一、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" |
代码示例:
json
{
"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" |
代码示例:
json
{
"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" |
代码示例:
json
{
"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 |
代码示例:
json
{
"app": {
"debug": false,
"asanEnabled": true,
"hwasanEnabled": true,
"ubsanEnabled": true
}
}
5. 设备差异化配置
支持为不同设备(如 tablet
、tv
、car
)单独配置 minAPIVersion
,若未配置则使用全局值。
代码示例:
json
{
"app": {
"minAPIVersion": 9,
"tablet": {
"minAPIVersion": 8
},
"tv": {
"minAPIVersion": 7
}
}
}
6. 应用多开模式
配置项 | 说明 | 示例 |
---|---|---|
multiAppMode |
配置多开模式(multiInstance 或 appClone )。 |
"multiAppMode": {"multiAppModeType": "appClone", "maxCount": 5} |
代码示例:
json
{
"app": {
"multiAppMode": {
"multiAppModeType": "appClone",
"maxCount": 5
}
}
}
7. 云能力配置
配置项 | 说明 | 示例 |
---|---|---|
cloudFileSyncEnabled |
启用端云文件同步。 | "cloudFileSyncEnabled": true |
cloudStructuredDataSyncEnabled |
启用端云结构化数据同步(API 20+)。 | "cloudStructuredDataSyncEnabled": true |
代码示例:
json
{
"app": {
"cloudFileSyncEnabled": true,
"cloudStructuredDataSyncEnabled": true
}
}
8. 字体适配控制
通过 configuration
标签引用 profile 文件,控制字体是否跟随系统变化。
代码示例:
json
{
"app": {
"configuration": "$profile:font_config"
}
}
Profile 文件(font_config.json
):
json
{
"fontSizeScale": "followSystem",
"fontSizeMaxScale": "1.75"
}
9. 环境变量配置
通过 appEnvironments
为第三方库提供运行时环境变量。
代码示例:
json
{
"app": {
"appEnvironments": [
{
"name": "ENV_VAR1",
"value": "value1"
},
{
"name": "ENV_VAR2",
"value": "value2"
}
]
}
}
🧪 二、完整配置示例
json
{
"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"
}
]
}
}
✅ 三、关键注意事项
-
命名规范
bundleName
必须符合反域名格式(如com.example.myapp
)。- 字符串长度限制:7~128 字节。
-
版本管理
versionCode
必须递增(新版本 > 旧版本)。versionName
推荐使用四段式(如1.0.0.0
)。
-
设备适配
- 为不同设备(
tablet
、tv
等)单独配置minAPIVersion
。
- 为不同设备(
-
调试工具
- 发布版本关闭所有 Sanitizer(
asanEnabled
、hwasanEnabled
等)。
- 发布版本关闭所有 Sanitizer(
-
字体适配
- 通过
configuration
标签控制字体跟随系统变化,避免布局错乱。
- 通过
📌 四、总结
app.json5
是 HarmonyOS/OpenHarmony 应用的核心配置文件,涵盖了应用标识、兼容性、调试、多开、云能力等关键功能。通过合理配置,开发者可以实现:
- 精确控制应用行为(如调试模式、多开模式)。
- 适配不同设备(
tablet
、tv
等)。 - 提升用户体验(如字体适配、云同步)。
- 优化安全性与稳定性(内存检测工具)。
掌握 app.json5
的配置是开发高质量跨端应用的基础。