1. 引言

在鸿蒙OS（HarmonyOS）应用开发中，配置文件是连接应用代码与系统能力的桥梁。无论是应用的基础信息、模块声明，还是权限申请、设备适配，都离不开配置文件的支撑。理解配置文件的元素结构，是每一位鸿蒙开发者入门的第一课。

本文将从鸿蒙OS配置文件的核心元素入手，结合丰富的代码实例，带你系统掌握配置文件的结构、字段含义以及常见配置技巧。

2. 配置文件概述

鸿蒙OS应用工程中，配置文件主要分为两类：

• 应用级配置文件：位于工程根目录，用于声明应用的整体信息，如应用名称、版本、图标等。
• 模块级配置文件：位于每个模块（Module）目录下，用于声明模块的详细信息，如模块名称、入口能力、权限等。

在 HarmonyOS 3.1 及之前的版本中，应用级配置文件为 app.json5，模块级配置文件为 module.json5。从 HarmonyOS 4.0 开始，两者统一合并为 module.json5，应用级信息通过 app 字段在模块配置文件中声明。

3. 配置文件的基础结构

一个典型的 module.json5 文件结构如下：

{
  "app": {
    "bundleName": "com.example.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  },
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

4. app 元素详解

app 元素用于声明应用级配置信息，是整个配置文件的顶层元素之一。下面逐一解析其子元素。

4.1 bundleName（包名）

bundleName 是应用的唯一标识，相当于应用的身份证。它必须遵循反向域名命名规则，且全局唯一。

"bundleName": "com.example.myapplication"

4.2 versionCode 与 versionName

versionCode 是应用的版本号（整数），用于应用市场的版本管理，只能递增；versionName 是版本名称（字符串），用于向用户展示。

"versionCode": 1000000,
"versionName": "1.0.0"

4.3 icon 与 label

icon 指定应用图标，label 指定应用名称。两者通常引用资源文件，使用 $media 和 $string 前缀。

"icon": "$media:app_icon",
"label": "$string:app_name"

4.4 vendor（供应商）

vendor 用于声明应用的供应商信息，可选字段。

"vendor": "example"

5. module 元素详解

module 元素是模块级配置的核心，包含模块的名称、类型、入口能力、设备类型、权限等关键信息。

5.1 name 与 type

name 是模块名称，type 是模块类型。常见的模块类型有 entry（应用入口模块）和 feature（功能模块）。

"name": "entry",
"type": "entry"

5.2 mainElement（入口能力）

mainElement 指定模块的入口 UIAbility，即应用启动时首先加载的能力。

"mainElement": "EntryAbility"

5.3 deviceTypes（设备类型）

deviceTypes 声明模块支持的设备类型，如手机、平板、智慧屏、手表等。

"deviceTypes": [
  "phone",
  "tablet",
  "wearable"
]

5.4 pages（页面配置）

pages 指定页面路由配置文件，通常指向 main_pages.json，其中列出了模块的所有页面路径。

"pages": "$profile:main_pages"

对应的 main_pages.json 文件内容如下：

{
  "src": [
    "pages/Index",
    "pages/Detail",
    "pages/About"
  ]
}

5.5 abilities（能力列表）

abilities 是一个数组，声明模块内所有的 UIAbility。每个能力包含名称、入口文件、图标、标签、启动窗口等配置。

"abilities": [
  {
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "description": "$string:EntryAbility_desc",
    "icon": "$media:icon",
    "label": "$string:EntryAbility_label",
    "startWindowIcon": "$media:startIcon",
    "startWindowBackground": "$color:start_window_background",
    "exported": true,
    "skills": [
      {
        "entities": ["entity.system.home"],
        "actions": ["action.system.home"]
      }
    ]
  }
]

6. requestPermissions（权限配置）

当应用需要访问系统敏感能力（如相机、定位、麦克风）时，必须在配置文件中声明相应权限。权限通过 requestPermissions 数组配置。

"requestPermissions": [
  {
    "name": "ohos.permission.CAMERA",
    "reason": "$string:reason_camera",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.LOCATION",
    "reason": "$string:reason_location",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "always"
    }
  }
]

其中 name 是权限名称，reason 是申请权限的原因说明，usedScene 描述权限的使用场景。

7. 完整实战示例

下面给出一个包含权限申请、多能力声明和页面配置的完整 module.json5 示例：

{
  "app": {
    "bundleName": "com.example.smartnote",
    "vendor": "example",
    "versionCode": 2000000,
    "versionName": "2.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  },
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "MainAbility",
    "deviceTypes": ["phone", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:reason_camera",
        "usedScene": {
          "abilities": ["MainAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "$string:reason_read_media",
        "usedScene": {
          "abilities": ["MainAbility"],
          "when": "inuse"
        }
      }
    ],
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/entryability/MainAbility.ets",
        "description": "$string:MainAbility_desc",
        "icon": "$media:icon",
        "label": "$string:MainAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      },
      {
        "name": "SecondAbility",
        "srcEntry": "./ets/entryability/SecondAbility.ets",
        "description": "$string:SecondAbility_desc",
        "icon": "$media:icon",
        "label": "$string:SecondAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": false
      }
    ]
  }
}

8. 常见问题与注意事项

• 包名唯一性：bundleName 一旦发布不可更改，务必在开发初期确定好命名规则。
• 版本号递增：versionCode 只能递增，不能回退，否则会导致应用市场更新失败。
• 权限最小化：只申请应用实际需要的权限，避免过度申请导致用户信任度下降。
• 资源引用：图标、标签等建议使用资源引用（$media、$string），便于多语言和多设备适配。
• 设备类型匹配：deviceTypes 必须与工程实际支持的设备一致，否则可能导致安装失败。

9. 总结

鸿蒙OS配置文件是应用开发的基石，掌握 app 和 module 两大核心元素及其子元素的含义，是构建高质量鸿蒙应用的前提。本文通过丰富的代码实例，详细解析了配置文件的结构、字段含义和实战配置方法。建议开发者在实际项目中多动手实践，结合官方文档深入理解每个字段的用途，从而写出规范、健壮的配置文件。