鸿蒙OS 应用配置文件详解：从 module.json5 到 app.json5 的完整实践

hid3438

58人浏览 · 2026-08-30 09:55:10

hid3438 · 2026-08-30 09:55:10 发布

1. 引言

在鸿蒙OS（HarmonyOS）应用开发中，配置文件是应用工程的“骨架”，它决定了应用如何被系统识别、如何申请权限、如何声明页面与组件。无论是初学者还是有一定经验的开发者，理解配置文件的结构与字段含义，都是构建可发布、可维护应用的基础。本文将从配置文件的作用、核心文件结构、字段详解到实战示例，系统梳理鸿蒙OS应用配置文件的完整知识体系。

2. 配置文件概述

鸿蒙OS应用工程中，配置文件主要分为两类：一类是应用级配置，用于声明应用的全局信息，如应用名称、版本号、图标等；另一类是模块级配置，用于描述某个模块（Module）的详细信息，包括模块名称、入口页面、权限申请、设备类型等。两者配合，共同构成应用在系统层面的完整描述。

在 HarmonyOS 工程中，最常见的配置文件包括：

app.json5：应用级配置文件，位于工程的 AppScope 目录下。
module.json5：模块级配置文件，位于每个模块的 src/main 目录下。
build-profile.json5：构建配置文件，用于声明签名、编译选项等。
hvigorfile.ts：构建脚本文件，用于配置构建任务。

其中，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"
  }
}

各字段含义如下：

字段名	类型	说明
bundleName	string	应用包名，全局唯一，用于标识应用。
vendor	string	应用供应商名称，用于标识应用开发者。
versionCode	number	应用版本号（内部版本号），用于版本管理，必须为整数。
versionName	string	应用版本名称，用于向用户展示的版本号。
icon	string	应用图标资源引用，通常使用资源索引。
label	string	应用名称资源引用，用于在桌面显示的应用名称。

需要注意的是，bundleName 一旦发布后不可更改，因此在创建工程时就要规划好包名。版本号 versionCode 在每次上架新版本时都需要递增，否则会被应用市场拒绝。

4. module.json5 模块级配置详解

module.json5 位于模块的 src/main 目录下，是模块级配置的核心文件。它声明了模块的名称、类型、入口页面、权限、设备类型等信息。下面是一个典型的 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"
        }
      }
    ]
  }
}

下面对关键字段进行逐一说明。

4.1 模块基本信息

name 字段表示模块名称，在工程内必须唯一。type 字段表示模块类型，常见取值包括：

entry：应用的主入口模块，一个应用有且仅有一个。
feature：应用的动态特性模块，可以按需加载。
har：静态共享库模块，用于代码和资源复用。
hsp：动态共享库模块，支持按需加载。

mainElement 字段指定模块的入口 Ability 名称，即应用启动时首先加载的页面能力。deviceTypes 数组声明了该模块支持的设备类型，如手机、平板、智慧屏等。

4.2 页面配置

pages 字段通过资源索引引用一个配置文件，该文件列出了模块内所有的页面路径。例如，$profile:main_pages 对应 src/main/resources/base/profile/main_pages.json 文件，其内容如下：

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

页面路径相对于 src/main/ets 目录，不需要写文件扩展名。系统会根据该列表生成路由表，用于页面跳转。

4.3 Ability 配置

abilities 数组用于声明模块内的所有 Ability。每个 Ability 可以配置名称、入口文件、图标、标签、是否可被外部调用等属性。其中 skills 字段用于声明 Ability 能够响应的意图（Intent），例如上面的示例中声明了 entity.system.home 和 action.system.home，表示该 Ability 是应用的主入口，会在桌面显示应用图标。

4.4 权限申请

requestPermissions 数组用于声明模块运行时需要的权限。每个权限项包含权限名称、申请原因和使用场景。例如申请网络权限：

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

when 字段取值包括 inuse（使用时申请）和 always（始终可用）。对于敏感权限，系统会在应用运行时弹出授权对话框，开发者需要在代码中通过 abilityAccessCtrl 模块主动发起授权请求。

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

在配置文件中，很多字段的值并不是直接写死的字符串，而是通过资源索引引用。例如 $string:app_name 表示引用字符串资源，$media:app_icon 表示引用图片资源，$color:start_window_background 表示引用颜色资源。这种设计的好处是：

支持多语言适配，不同语言环境下自动加载对应的字符串资源。
支持多设备适配，不同设备类型可以加载不同的资源。
便于统一管理和维护，修改资源文件无需改动配置文件。

字符串资源定义在 src/main/resources/base/element/string.json 文件中，示例如下：

{
  "string": [
    {
      "name": "app_name",
      "value": "我的应用"
    },
    {
      "name": "module_desc",
      "value": "主模块"
    },
    {
      "name": "reason_internet",
      "value": "需要访问网络以获取数据"
    }
  ]
}

颜色资源定义在 src/main/resources/base/element/color.json 文件中：

{
  "color": [
    {
      "name": "start_window_background",
      "value": "#FFFFFF"
    }
  ]
}

6. 实战：创建一个完整的配置文件

下面通过一个完整的实战案例，演示如何从零配置一个支持多页面、多权限的鸿蒙OS应用。假设我们要开发一个新闻阅读应用，包含首页、详情页和设置页三个页面，需要网络权限和位置权限。

6.1 创建工程结构

首先创建工程目录结构：

MyNewsApp/
├── AppScope/
│   ├── app.json5
│   └── resources/
│       └── base/
│           ├── element/
│           │   └── string.json
│           └── media/
│               └── app_icon.png
└── entry/
    └── src/
        └── main/
            ├── module.json5
            ├── ets/
            │   ├── entryability/
            │   │   └── EntryAbility.ets
            │   └── pages/
            │       ├── Index.ets
            │       ├── Detail.ets
            │       └── Settings.ets
            └── resources/
                └── base/
                    ├── element/
                    │   ├── string.json
                    │   └── color.json
                    └── profile/
                        └── main_pages.json

6.2 配置 app.json5

{
  "app": {
    "bundleName": "com.example.mynewsapp",
    "vendor": "example",
    "versionCode": 1000001,
    "versionName": "1.0.1",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

6.3 配置 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": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:reason_location",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

6.4 配置页面列表

在 src/main/resources/base/profile/main_pages.json 中声明页面：

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

6.5 配置字符串资源

在 src/main/resources/base/element/string.json 中定义模块相关字符串：

{
  "string": [
    {
      "name": "module_desc",
      "value": "新闻阅读主模块"
    },
    {
      "name": "EntryAbility_desc",
      "value": "新闻阅读应用入口"
    },
    {
      "name": "EntryAbility_label",
      "value": "新闻阅读"
    },
    {
      "name": "reason_internet",
      "value": "需要访问网络以加载新闻内容"
    },
    {
      "name": "reason_location",
      "value": "需要获取位置以推荐本地新闻"
    }
  ]
}

6.6 配置颜色资源

在 src/main/resources/base/element/color.json 中定义启动窗口背景色：

{
  "color": [
    {
      "name": "start_window_background",
      "value": "#F5F5F5"
    }
  ]
}

7. 常见问题与注意事项

在实际开发中，配置文件相关的错误往往比较隐蔽，下面总结几个常见问题。

7.1 bundleName 冲突

bundleName 是应用的唯一标识，如果与其他应用重复，会导致安装失败。建议使用公司域名反写作为前缀，例如 com.example.myapp。

7.2 页面路径错误

main_pages.json 中的页面路径必须与 ets/pages 目录下的文件一一对应，且不能包含文件扩展名。如果路径错误，编译时会报“页面不存在”的错误。

7.3 权限声明不完整

某些权限需要同时声明 reason 和 usedScene，否则在应用市场上架审核时会被驳回。特别是涉及用户隐私的权限，如位置、相机、通讯录等，必须提供清晰的使用场景说明。

7.4 资源引用错误

配置文件中使用 $string:、$media:、$color: 等前缀引用资源时，必须确保对应的资源文件存在且名称正确。如果资源缺失，编译时会报资源引用错误。

8. 总结

本文系统梳理了鸿蒙OS应用配置文件的核心内容，包括 app.json5 和 module.json5 的结构、字段含义、资源关联方式，并通过一个完整的新闻阅读应用案例演示了配置文件的编写过程。掌握配置文件是鸿蒙开发的第一步，也是构建高质量应用的基础。建议开发者在实际项目中多参考官方文档，并结合 DevEco Studio 的工程模板进行实践，逐步加深对配置体系的理解。