HarmonyOS应用开发实战：萌宠日记 - json5-配置文件详解

前言

module.json5 是 HarmonyOS Stage 模型 中 模块级 的核心配置文件，它定义了模块的 名称 、类型 、Ability 、扩展能力 、设备类型 等关键信息。在 萌宠日记 应用中，我们通过 module.json5 配置了 EntryAbility 入口 、页面路由表 、备份扩展能力 等核心模块信息。

本文将从 萌宠日记 的 module.json5 文件出发，逐字段解析每个配置项的含义、作用范围以及最佳实践。

一、module.json5 的作用与定位

1.1 配置文件层级

HarmonyOS 应用的配置文件分为 三个层级：

层级	文件	作用范围	配置内容
应用级	AppScope/app.json5	整个应用	包名、版本、全局图标
模块级	entry/src/main/module.json5	单个模块	Ability、页面、扩展能力
页面级	main_pages.json	页面路由	页面路径注册表

三个层级的关系如下：

app.json5                    ← 应用级（全局配置）
  └── module.json5           ← 模块级（模块配置）
        ├── abilities[]      ← Ability 配置
        ├── extensionAbilities[] ← 扩展能力
        └── pages（引用）    ← $profile:main_pages
              └── main_pages.json  ← 页面路由表

1.2 萌宠日记的完整配置

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "extensionAbilities": [
      {
        "name": "EntryBackupAbility",
        "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
        "type": "backup",
        "exported": false,
        "metadata": [
          {
            "name": "ohos.extension.backup",
            "resource": "$profile:backup_config"
          }
        ]
      }
    ]
  }
}

提示 ：module.json5 使用 JSON5 格式，支持注释和尾逗号，比标准 JSON 更灵活。在 DevEco Studio 中编辑时会有语法提示和校验支持。

二、模块基础属性

2.1 name 与 type

{
  "name": "entry",
  "type": "entry"
}

name 和 type 是模块最基本的两个属性：

属性	值	说明
name	"entry"	模块名称，在同一应用中唯一
type	"entry"	模块类型

模块类型 type 的三种取值：

类型	说明	应用场景
entry	应用主模块	可独立安装运行，一个应用至少一个
feature	功能模块	依赖 entry 模块，按需加载
shared	共享模块	提供共享代码和资源

2.2 description

"description": "$string:module_desc"

description 引用资源文件中的字符串：

{
  "string": [
    { "name": "module_desc", "value": "萌宠日记应用" }
  ]
}

使用资源引用的优势：

• 支持 多语言 自动切换
• 编译时进行 资源校验
• 便于 统一管理 所有文案

2.3 mainElement

"mainElement": "EntryAbility"

mainElement 指定模块的 入口 Ability 名称，它必须与 abilities 数组中某个 Ability 的 name 一致。当系统启动该模块时，会首先创建 mainElement 指定的 Ability。

三、设备类型配置

3.1 deviceTypes

"deviceTypes": [
  "phone"
]

deviceTypes 指定模块支持的设备类型。HarmonyOS 支持多种设备类型：

设备类型	标识	说明
手机	phone	默认设备类型
平板	tablet	大屏设备
智能穿戴	wearable	手表等
智慧屏	tv	电视设备
车机	car	车载设备
2in1 设备	twoInOne	平板/笔记本二合一

3.2 多设备适配

萌宠日记当前仅支持 phone 设备，但后续可以扩展：

// 多设备支持的配置示例
"deviceTypes": [
  "phone",
  "tablet",
  "twoInOne"
]

多设备适配需要搭配 资源限定符 和 响应式布局 共同实现：

• 资源限定符：为不同屏幕尺寸提供不同布局资源
• 响应式布局 ：使用 layoutWeight 等弹性布局实现自适应

四、安装配置

4.1 deliveryWithInstall

"deliveryWithInstall": true

deliveryWithInstall 控制模块是否随应用安装一起下发：

值	行为	适用场景
true	随应用安装时下发	主模块、核心功能模块
false	按需下载	功能模块、插件模块

萌宠日记 使用 true，因为 entry 模块是应用的主模块，必须随安装一起下发。

4.2 installationFree

"installationFree": false

installationFree 控制模块是否支持 免安装运行：

值	行为	说明
true	支持免安装	用户无需安装即可运行，有大小限制（通常 ≤10MB）
false	需安装后运行	标准安装模式，无大小限制

五、页面路由配置

5.1 pages 属性

"pages": "$profile:main_pages"

pages 通过 $profile: 引用 profile 资源文件，指向 main_pages.json：

{
  "src": [
    "pages/Index",
    "pages/SplashPage",
    "pages/HomePage",
    "pages/WriteDiaryPage",
    "pages/PetProfilePage",
    "pages/GrowthTimelinePage",
    "pages/HealthRecordPage",
    "pages/AlbumPage",
    "pages/StatisticsPage",
    "pages/ReminderPage",
    "pages/CommunityPage",
    "pages/ProfilePage"
  ]
}

5.2 页面注册规则

页面注册的注意事项：

1. 所有页面必须注册 ：每个可在路由中访问的页面都需在 src 数组中列出
2. 路径规则 ：路径相对于 src/main/ets/ 目录，不含 .ets 后缀
3. 首屏页面 ：第一个通过 loadContent 加载的页面（SplashPage）必须在列表中
4. 路由跳转 ：router.pushUrl({ url: 'pages/Index' }) 中的路径必须与注册路径一致

六、Ability 配置详解

6.1 基础属性

{
  "name": "EntryAbility",
  "srcEntry": "./ets/entryability/EntryAbility.ets",
  "description": "$string:EntryAbility_desc",
  "icon": "$media:layered_image",
  "label": "$string:EntryAbility_label"
}

Ability 基础属性说明：

属性	值	说明
name	EntryAbility	Ability 名称，在同一模块中唯一
srcEntry	./ets/entryability/EntryAbility.ets	源代码路径
description	$string:EntryAbility_desc	描述，引用字符串资源
icon	$media:layered_image	图标，引用媒体资源
label	$string:EntryAbility_label	显示名称，引用字符串资源

6.2 启动窗口配置

"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background"

启动窗口属性：

属性	说明	最佳实践
startWindowIcon	启动窗口图标	使用与应用图标一致的图标
startWindowBackground	启动窗口背景色	设置为闪屏页背景色，实现无缝过渡

6.3 exported 与 skills

"exported": true,
"skills": [
  {
    "entities": ["entity.system.home"],
    "actions": ["ohos.want.action.home"]
  }
]

exported 控制 Ability 是否可被其他应用调用：

值	含义	萌宠日记场景
true	可被外部应用通过 Want 启动	从桌面图标启动
false	仅内部使用	内部辅助 Ability

skills 定义了 Ability 能够响应的 Want 匹配规则：

• entities：实体类型，entity.system.home 表示桌面应用
• actions：动作类型，ohos.want.action.home 表示主页面动作

七、ExtensionAbility 扩展能力

7.1 备份扩展能力

{
  "name": "EntryBackupAbility",
  "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
  "type": "backup",
  "exported": false,
  "metadata": [
    {
      "name": "ohos.extension.backup",
      "resource": "$profile:backup_config"
    }
  ]
}

7.2 ExtensionAbility 类型大全

类型	用途	萌宠日记是否使用
backup	数据备份恢复	✅ 已配置
service	后台服务	可扩展
form	服务卡片	可扩展
widget	桌面小组件	可扩展
accessibility	无障碍服务	可扩展

7.3 metadata 配置

"metadata": [
  {
    "name": "ohos.extension.backup",
    "resource": "$profile:backup_config"
  }
]

metadata 用于向 Ability 传递额外的配置信息，以键值对形式存在：

属性	说明	示例
name	元数据名称	ohos.extension.backup
value	字符串值	直接指定
resource	资源引用	$profile:backup_config

八、常见配置错误与排查

8.1 配置校验规则

错误类型	现象	原因
name 重复	编译报错	同一模块中 Ability 名称重复
路径错误	页面白屏	srcEntry 路径与实际文件不匹配
页面未注册	路由跳转失败	页面未在 main_pages.json 中注册
资源引用错误	编译警告	$string:xxx 对应的资源不存在

8.2 调试方法

# 查看模块配置是否正确加载
hdc shell aa dump -a -p com.mengchongriji.app

九、配置最佳实践

9.1 配置项清单

有序列表 --- 配置后的检查清单：

1. 确认 bundleName 与应用签名一致
2. 确认所有页面路径拼写正确
3. 确认 Ability 的 srcEntry 路径指向实际文件
4. 确认 deviceTypes 包含目标设备类型
5. 确认 skills 配置正确，应用可从桌面启动

9.2 配置优化建议

• 使用资源引用 ：description、icon、label 等属性优先使用 $string:、$media: 引用
• 保持配置简洁：只配置必要的字段，避免冗余
• 版本同步 ：versionCode 和 versionName 随版本更新同步递增
• 注释规范：JSON5 格式支持注释，可添加配置说明

十、从 FA 到 Stage 的配置迁移

10.1 配置差异对比

配置项	FA 模型	Stage 模型
配置文件	config.json	module.json5 + app.json5
格式	JSON	JSON5（支持注释）
Ability 定义	使用 PageAbility	使用 UIAbility
页面注册	pages 数组	$profile:main_pages 引用
扩展能力	无	extensionAbilities 数组

10.2 迁移建议

• 将 config.json 拆分为 app.json5 和 module.json5
• 将 PageAbility 替换为 UIAbility
• 将 pages 数组迁移到 main_pages.json 中
• 新增 extensionAbilities 配置扩展能力

总结

本文从 萌宠日记 的 module.json5 文件出发，深入解析了 HarmonyOS Stage 模型 下模块配置的每一个字段：

1. 模块基础属性：name、type、description、mainElement
2. 设备类型配置：deviceTypes 及多设备适配
3. 安装配置：deliveryWithInstall、installationFree
4. 页面路由：pages 引用 main_pages.json
5. Ability 配置：入口、启动窗口、skills
6. 扩展能力：ExtensionAbility 的备份能力集成
7. 配置最佳实践：校验规则、调试方法、迁移指南

理解 module.json5 的配置细节，是正确构建 HarmonyOS 应用的基础。下一篇我们将深入 app.json5 与应用签名配置，解析应用级配置的各项细节。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• module.json5 配置文件：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file
• 应用配置文件概述：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-overview-stage
• UIAbility 配置：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage
• ExtensionAbility 概述：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/extensionability-overview
• 应用程序包结构：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-structure-stage
• HAP 包配置：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package
• 设备类型适配：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/device-adaptation
• 应用签名配置：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-signing