第5篇：鸿蒙应用配置体系——从 app.json5 到 build-profile

一、引言

鸿蒙应用的配置体系涉及多个维度的配置文件，从应用级配置到模块级配置，再到构建配置。DriverLicenseExam 项目展示了完整的配置体系，本文将逐一解析。

二、应用级配置（AppScope）

2.1 app.json5——应用身份证

AppScope/app.json5 是应用级别的配置文件，定义了应用的基本信息：

{
  "app": {
    "bundleName": "qcjk.1.xxxxxx",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.6",
    "icon": "$media:layered_image",
    "label": "$string:app_name"
  }
}

关键字段说明：

字段	说明	示例值
bundleName	应用包名，唯一标识	qcjk.1.xxxxxx
vendor	应用供应商	example
versionCode	版本号（整数）	1000000
versionName	版本名（显示用）	1.0.6
icon	应用图标	$media:layered_image
label	应用名称	$string:app_name

2.2 资源文件体系

AppScope 下的资源文件通过 $r 引用，项目使用三种资源类型：

// AppScope/resources/base/element/string.json
{
  "string": [
    { "name": "app_name", "value": "驾考模板" },
    { "name": "homepage", "value": "首页" },
    { "name": "mine", "value": "我的" }
  ]
}

// AppScope/resources/base/element/color.json
{
  "color": [
    { "name": "icon_color_highlight", "value": "#FF64BB5C" },
    { "name": "search_background", "value": "#FFF1F3F5" }
  ]
}

三、模块级配置（module.json5）

每个模块都有独立的 module.json5，声明模块的 Ability、权限和服务卡片：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["default", "tablet"],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      },
      {
        "name": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
        "type": {
          "form": {
            "formVisibleNotify": true,
            "forms": [
              {
                "name": "widget_2x2",
                "src": "./ets/widget/pages/WidgetCard2X2.ets",
                "isDefault": true,
                "updateEnabled": true,
                "defaultDimension": "2*2",
                "supportDimensions": ["2*2", "2*4"]
              }
            ]
          }
        }
      }
    ]
  }
}

3.1 权限声明

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.APPROXIMATELY_LOCATION" },
      { "name": "ohos.permission.LOCATION" },
      { "name": "ohos.permission.GET_NETWORK_INFO" },
      { "name": "ohos.permission.READ_CALENDAR" },
      { "name": "ohos.permission.WRITE_CALENDAR" },
      { "name": "ohos.permission.VIBRATE" }
    ]
  }
}

四、构建配置（build-profile.json5）

4.1 工程级构建配置

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./products/entry"
    }
  ]
}

4.2 模块级构建配置

{
  "apiType": "stageMode",
  "buildOption": {
    "arkOptions": {
      "compileArkTS": true
    }
  }
}

五、包管理配置（oh-package.json5）

5.1 入口模块依赖

{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    "exam": "file:../../components/exam",
    "aggregated_ads": "file:../../components/aggregated_ads",
    "aggregated_share": "file:../../components/aggregated_share",
    "app_setting": "file:../../components/app_setting",
    "feedback": "file:../../components/feedback",
    "guide": "file:../../components/guide",
    "@ohos_agcit/driver_license_exam_commonlib": "file:../../commons/commonLib",
    "@ohos_agcit/driver_license_exam_datasource": "file:../../commons/datasource"
  }
}

5.2 HAR 模块自身配置

{
  "name": "@ohos_agcit/driver_license_exam_commonlib",
  "version": "1.0.0",
  "description": "公共工具模块",
  "main": "Index.ets",
  "license": "Apache-2.0"
}

六、配置文件的完整关系图

AppScope/app.json5          ← 应用级配置（包名、版本、图标）
  │
  ├── 引用资源文件
  │   └── AppScope/resources/base/element/string.json
  │   └── AppScope/resources/base/element/color.json
  │   └── AppScope/resources/base/element/font.json
  │
  └── 模块级配置
      └── products/entry/src/main/module.json5
          ├── 声明 Ability
          ├── 声明权限
          └── 声明服务卡片

build-profile.json5          ← 构建配置（签名、SDK 版本）
  │
  └── products/entry/build-profile.json5
      └── 模块构建选项

oh-package.json5              ← 依赖管理
  └── 本地 HAR 依赖

七、配置最佳实践

7.1 版本管理

• 使用 versionCode 整数递增，每次发布 +1
• versionName 遵循语义化版本（x.y.z）
• 在 CHANGELOG.md 中记录版本变更

7.2 资源引用

• 使用 $r('sys.color.xxx') 引用系统资源，自动适配深色模式
• 使用 $r('app.string.xxx') 引用应用资源，方便国际化
• 避免硬编码颜色值和字符串

7.3 权限管理

• 遵循最小权限原则，只申请实际需要的权限
• 动态申请权限，不要一次性申请所有权限
• 提供明确的权限用途说明

八、总结

DriverLicenseExam 项目的配置体系展示了鸿蒙应用的完整配置流程：

1. 应用级配置：定义应用身份和元信息
2. 模块级配置：定义模块类型、Ability、权限
3. 构建配置：签名、SDK 版本、编译选项
4. 依赖管理：本地 HAR 和远程依赖
5. 资源管理：字符串、颜色、字体等资源文件

正确的配置是应用正常运行的基石，也是多设备适配的基础。

---

关键源码文件：

• AppScope/app.json5 — 应用配置
• AppScope/resources/base/element/ — 资源文件
• products/entry/src/main/module.json5 — 模块配置
• build-profile.json5 — 构建配置