1. 引言

在鸿蒙OS（HarmonyOS）应用开发中，配置文件是连接应用代码与系统能力的桥梁。无论是应用的基础信息、页面路由，还是权限声明、设备适配，都离不开配置文件的支撑。理解配置文件的元素构成，是每一位鸿蒙开发者必须掌握的基础技能。

本文将从鸿蒙OS配置文件的整体结构出发，逐一剖析其中的核心元素，并结合丰富的代码实例，帮助你在实际项目中灵活运用。

2. 配置文件概述

鸿蒙OS应用的配置文件主要分为两类：全局配置文件（app.json5）和模块配置文件（module.json5）。前者描述应用的整体属性，后者描述具体模块（如 entry、feature）的细节配置。

在工程目录中，配置文件通常位于以下位置：

project_root/
├── AppScope/
│   └── app.json5          // 全局配置文件
├── entry/
│   └── src/main/
│       └── module.json5   // 模块配置文件
└── build-profile.json5    // 构建配置文件

下面我们分别介绍这两类配置文件中的核心元素。

3. 全局配置文件 app.json5 的元素

全局配置文件 app.json5 用于声明应用的全局属性，包括应用名称、包名、版本号、图标等。一个典型的 app.json5 示例如下：

{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

3.1 bundleName（包名）

bundleName 是应用的唯一标识，相当于应用的身份证。它必须遵循反向域名命名规则，且在整个鸿蒙生态中保持唯一。包名一旦发布，不可随意更改。

"bundleName": "com.example.myapp"

3.2 versionCode 与 versionName

versionCode 是应用的内部版本号，用于版本升级判断，必须为整数且单调递增；versionName 是面向用户的版本名称，如 "1.0.0"。

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

3.3 icon 与 label

icon 指定应用的图标资源，label 指定应用的显示名称。它们通常引用资源文件，而不是直接写死字符串：

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

4. 模块配置文件 module.json5 的元素

模块配置文件 module.json5 是开发中最常打交道的配置文件，它描述了模块的名称、类型、入口页面、权限、设备类型等关键信息。下面是一个典型的 module.json5：

{
  "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"]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

4.1 name 与 type

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

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

4.2 deviceTypes（设备类型）

deviceTypes 声明该模块支持的设备类型，如手机、平板、智慧屏等。系统会根据该字段决定应用在哪些设备上可见。

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

4.3 pages（页面配置）

pages 字段指向一个 profile 资源文件，该文件列出了模块内所有的页面路由。页面配置文件 main_pages.json 的内容如下：

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

4.4 abilities（能力声明）

abilities 数组声明了模块内的所有 Ability。每个 Ability 可以配置名称、入口文件、图标、标签、启动窗口等属性。其中 skills 字段用于声明 Ability 能够响应的意图（Intent）：

"abilities": [
  {
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "exported": true,
    "skills": [
      {
        "entities": ["entity.system.home"],
        "actions": ["action.system.home"]
      }
    ]
  }
]

4.5 requestPermissions（权限声明）

当应用需要访问系统敏感能力（如网络、相机、定位）时，必须在 requestPermissions 中声明相应权限：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:reason_internet",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.CAMERA"
  }
]

5. 页面配置文件中的元素

页面配置文件（如 main_pages.json）虽然结构简单，但它是应用路由跳转的基础。每个页面路径对应一个 .ets 文件：

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

对应的工程目录结构如下：

entry/src/main/ets/
├── pages/
│   ├── Index.ets
│   └── Detail.ets
└── entryability/
    └── EntryAbility.ets

6. 资源文件与配置的关联

配置文件中大量使用 $string、$media、$color 等资源引用语法。这些资源定义在 resources 目录下：

entry/src/main/resources/
├── base/
│   ├── element/
│   │   ├── string.json
│   │   └── color.json
│   └── media/
│       ├── app_icon.png
│       └── startIcon.png
└── zh_CN/
    └── element/
        └── string.json

例如，string.json 中定义应用名称：

{
  "string": [
    {
      "name": "app_name",
      "value": "我的应用"
    },
    {
      "name": "module_desc",
      "value": "主模块"
    }
  ]
}

这样，配置文件中的 "label": "$string:app_name" 就会自动解析为「我的应用」，并且支持多语言适配。

7. 实战：完整配置示例

下面给出一个完整的实战配置示例，包含全局配置、模块配置和页面配置三个部分。

7.1 全局配置 app.json5

{
  "app": {
    "bundleName": "com.example.smartnote",
    "vendor": "example",
    "versionCode": 2000000,
    "versionName": "2.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

7.2 模块配置 module.json5

{
  "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"]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:reason_internet",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

7.3 页面配置 main_pages.json

{
  "src": [
    "pages/Index",
    "pages/NoteList",
    "pages/NoteEdit"
  ]
}

8. 常见问题与注意事项

• 包名不可修改：应用发布后，bundleName 不能更改，否则会被视为新应用。
• 版本号递增：每次发布新版本，versionCode 必须大于上一版本。
• 权限最小化：只申请应用实际需要的权限，避免过度申请导致审核不通过。
• 资源引用规范：优先使用 $string、$media 等资源引用，便于多语言和主题适配。
• 页面路径正确性：pages 中的路径必须与 .ets 文件实际位置一致，否则运行时会报路由错误。

9. 总结

鸿蒙OS的配置文件虽然看起来只是简单的 JSON5 结构，但其中每个元素都承载着特定的系统语义。掌握 app.json5 和 module.json5 的核心元素，理解资源引用机制，是开发高质量鸿蒙应用的基础。

在实际开发中，建议多参考官方模板工程，结合 DevEco Studio 的可视化配置界面，逐步加深对配置文件元素的理解。希望本文的代码实例能帮助你快速上手鸿蒙OS的配置开发。