1. 引言

在鸿蒙OS（HarmonyOS）应用开发中，配置文件是应用工程的“门面”和“说明书”。无论是应用的基础信息、模块声明、权限申请，还是页面路由、能力扩展，都需要通过配置文件进行声明。理解并正确编写配置文件，是构建一个可安装、可运行、可上架的鸿蒙应用的前提。

本文将以 ArkTS 工程为例，系统讲解鸿蒙OS应用开发中两类核心配置文件——app.json5 和 module.json5 的结构、字段含义与常见实践，并提供丰富的代码实例，帮助开发者快速上手。

2. 配置文件总览

一个标准的鸿蒙OS应用工程，通常包含以下与配置相关的文件：

• app.json5：应用级配置文件，声明应用的全局信息，如包名、版本号、支持的设备类型等。
• module.json5：模块级配置文件，声明当前模块（Module）的详细信息，如入口能力、页面路由、权限、元数据等。
• build-profile.json5：构建配置文件，用于配置签名、产品、编译选项等。
• oh-package.json5：依赖配置文件，声明三方库依赖和工程元信息。

其中，app.json5 和 module.json5 是应用运行时的核心配置，也是本文的重点。

3. app.json5 应用级配置

app.json5 位于工程的 AppScope 目录下，描述应用在设备上安装和运行所需的全局属性。一个典型的 app.json5 示例如下：

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

3.1 核心字段说明

字段	类型	说明
bundleName	string	应用包名，全局唯一，通常采用反向域名格式。
vendor	string	应用供应商名称。
versionCode	number	应用版本号（整数），用于版本比较和升级判断。
versionName	string	应用版本名称，展示给用户的版本标识。
icon	string	应用图标资源引用，使用 $media 资源引用语法。
label	string	应用名称资源引用，使用 $string 资源引用语法。

3.2 多设备类型配置

当应用需要支持多种设备形态时，可以在 app.json5 中通过 targetAPIVersion 和 deviceTypes 等字段进行声明。以下示例展示了如何声明应用支持的设备类型：

{
  "app": {
    "bundleName": "com.example.multidevice",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "targetAPIVersion": 12,
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ]
  }
}

其中 deviceTypes 支持的值包括：phone（手机）、tablet（平板）、2in1（二合一设备）、tv（智慧屏）、wearable（穿戴设备）、car（车机）等。

4. module.json5 模块级配置

module.json5 位于每个模块（Module）的 src/main/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	string	模块名称，在同一应用内唯一。
type	string	模块类型，常见取值：entry（应用入口模块）、feature（功能模块）、har（静态共享库）、hsp（动态共享库）。
mainElement	string	模块入口能力名称，对应 abilities 中声明的某个能力。
deviceTypes	array	当前模块支持的设备类型。
deliveryWithInstall	boolean	模块是否随应用安装时一起交付。
installationFree	boolean	模块是否支持免安装运行。

4.2 页面路由配置

module.json5 中的 pages 字段通过 $profile 资源引用指向一个 JSON 文件，该文件定义了模块内所有页面的路由映射。例如，在 src/main/resources/base/profile/main_pages.json 中：

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

这里的 src 数组中的每一项对应 ets/pages 目录下的页面文件（省略 .ets 后缀）。页面路由的配置决定了应用内页面跳转的可用路径。

4.3 Ability 能力声明

abilities 数组用于声明模块内的 UIAbility 能力。每个能力可以配置入口文件、图标、标签、启动窗口、是否可被外部应用拉起等属性。以下示例展示了如何声明一个带自定义启动窗口和权限校验的能力：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "MainAbility",
    "deviceTypes": [
      "phone"
    ],
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/entryability/MainAbility.ets",
        "description": "$string:main_ability_desc",
        "icon": "$media:icon",
        "label": "$string:main_ability_label",
        "startWindowIcon": "$media:start_icon",
        "startWindowBackground": "$color:white",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      },
      {
        "name": "SecondAbility",
        "srcEntry": "./ets/entryability/SecondAbility.ets",
        "description": "$string:second_ability_desc",
        "icon": "$media:icon",
        "label": "$string:second_ability_label",
        "exported": false
      }
    ]
  }
}

其中 exported 字段控制该能力是否允许被其他应用通过显式意图拉起。对于不希望被外部调用的能力，应设置为 false。

4.4 权限声明

应用需要访问系统敏感能力（如网络、相机、位置等）时，必须在 module.json5 的 requestPermissions 数组中声明对应权限。以下示例声明了网络访问、相机和位置权限：

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

对于用户授权类权限（如相机、位置），reason 字段用于向用户说明申请权限的原因，usedScene 描述权限的使用场景和时机。

4.5 元数据配置

通过 metadata 字段，可以在模块或能力级别添加自定义元数据，供应用运行时读取。以下示例展示了如何在模块级别配置元数据：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone"
    ],
    "metadata": [
      {
        "name": "my_custom_key",
        "value": "my_custom_value"
      },
      {
        "name": "my_config_key",
        "resource": "$string:config_value"
      }
    ]
  }
}

元数据既可以使用 value 直接指定字符串值，也可以使用 resource 引用资源文件中的值。

5. 资源引用语法

在配置文件中，经常可以看到 $string:xxx、$media:xxx、$color:xxx、$profile:xxx 等引用语法。这些语法用于引用 src/main/resources 目录下的资源文件，实现配置与资源的解耦。常见的资源引用类型如下：

引用语法	资源目录	示例
$string:name	base/element/string.json	$string:app_name
$media:name	base/media/	$media:app_icon
$color:name	base/element/color.json	$color:start_window_background
$profile:name	base/profile/	$profile:main_pages
$float:name	base/element/float.json	$float:corner_radius

例如，在 base/element/string.json 中定义应用名称：

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

然后在 app.json5 中通过 "label": "$string:app_name" 引用，即可实现多语言和资源复用。

6. 常见问题与最佳实践

6.1 bundleName 的命名规范

bundleName 是应用的唯一标识，一旦发布不可更改。建议采用反向域名格式，例如 com.company.appname。避免使用纯数字或特殊字符。

6.2 版本号的管理

versionCode 是整数类型，用于系统判断版本新旧；versionName 是展示给用户的版本号。每次发布新版本时，应递增 versionCode，并同步更新 versionName。

6.3 权限的最小化原则

只申请应用实际需要的权限，避免过度申请。对于用户授权类权限，应提供清晰的 reason 说明，并在 usedScene 中准确描述使用场景，以提高用户授权通过率。

6.4 资源引用的优势

尽量使用资源引用（$string、$media 等）而不是硬编码字符串，这样可以方便地支持多语言、多主题和多设备适配，同时避免因硬编码导致的编译检查遗漏。

6.5 模块类型的选型

对于应用的主入口模块，使用 type: "entry"；对于功能模块，使用 type: "feature"；对于需要复用的代码和资源，使用 HAR 或 HSP。合理的模块划分有助于工程的可维护性和编译效率。

7. 总结

本文系统介绍了鸿蒙OS应用开发中的核心配置文件：app.json5 和 module.json5。通过丰富的代码实例，我们了解了应用级配置、模块级配置、页面路由、能力声明、权限申请、元数据配置以及资源引用语法等关键内容。

正确编写配置文件是鸿蒙应用开发的基础功。建议开发者在实际项目中，结合官方文档和工程模板，逐步熟悉每个字段的含义和最佳实践，从而构建出结构清晰、配置规范、可维护性强的鸿蒙应用。