前言

在 HarmonyOS 应用中，module.json5是每个模块下必不可少的配置文件——它定义了模块的名称、类型、支持的设备、Ability 注册、页面路径、权限声明等关键信息。不理解这个文件，就无法理解应用是如何被系统识别和启动的。

本文以「猫猫大作战」的entry/src/main/module.json5为锚点，逐字段拆解其含义，深入讲解 Ability 注册规则、skills 意图过滤、deviceTypes 多设备适配，以及与 app.json5 的协作关系。

提示：本系列不讲 ArkTS 基础语法与环境搭建，假设你已跟完第 1–75 篇。本篇是阶段三第 76 篇。

一、项目中的 module.json5

1.1 完整配置

{ "module": { "name": "entry", "type": "entry", "deviceTypes": [ "tablet", "phone", "wearable" ], "deliveryWithInstall": true, "installationFree": false, "pages": "$profile:main_pages", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:app_icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:app_icon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { "actions": [ "action.system.home" ] } ] } ] } }

1.2 顶层字段速查

二、module.type 模块类型

2.1 四种模块类型

2.2 猫猫大作战的多模块设想

[ { "module": { "name": "entry", "type": "entry" } // 主游戏模块 }, { "module": { "name": "ranking_feature", "type": "feature", "deviceTypes": ["tablet", "phone"], "abilities": [ { "name": "RankingAbility", "srcEntry": "./ets/rankingability/RankingAbility.ets" } ] } // 排行榜独立 feature 模块 } ]

三、abilities 注册详解

3.1 Ability 配置字段

3.2 exported 的作用

{ "abilities": [ { "name": "EntryAbility", "exported": true, // 允许 Launcher 启动 "skills": [ { "actions": ["action.system.home"] } ] } ] }

3.3 skills 意图过滤

{ "skills": [ { "actions": ["action.system.home"], // 桌面图标入口 "entities": ["entity.system.home"], "uris": [] // 可处理的 URI } ] }

多 skills 示例：

{ "abilities": [ { "name": "EntryAbility", "exported": true, "skills": [ { // 桌面图标启动 "actions": ["action.system.home"], "entities": ["entity.system.home"] }, { // DeepLink 深度链接启动 "actions": ["action.system.view"], "uris": [ { "scheme": "catscheme", "host": "ranking", "pathPrefix": "/player" } ] } ] } ] }

四、deviceTypes 多设备适配

4.1 猫猫大作战支持的设备

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

4.2 设备类型枚举

4.3 多设备配置示例

{ "deviceTypes": ["phone", "tablet"], "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets" } ] }

当应用在平板上安装时，如果deviceTypes没有包含tablet，应用将无法在平板上搜索或安装。

五、pages 页面路由配置

{ "pages": "$profile:main_pages" }

$profile:main_pages指向resources/base/profile/main_pages.json：

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

注意：pages字段也可以直接写成"pages": ["pages/Index"]，但不推荐——使用$profile引用更方便管理和扩展。

六、常见踩坑

6.1 坑一：srcEntry 路径错误

// 🚫 错误：srcEntry 路径不对 { "srcEntry": "entryability/EntryAbility.ets" // ❌ 缺少 ./ets/ } // ✅ 正确 { "srcEntry": "./ets/entryability/EntryAbility.ets" }

srcEntry路径从src/main/开始计算，所以./ets/entryability/EntryAbility.ets对应实际目录src/main/ets/entryability/EntryAbility.ets。

6.2 坑二：忘记配置 skills

// 🚫 缺少 skills → Launcher 找不到入口 { "abilities": [ { "name": "EntryAbility", "exported": true // ❌ 没有 skills，桌面没有图标 } ] }

表现：应用安装成功，但桌面上找不到图标。

解决：必须添加skills并设置action.system.home：

"skills": [ { "actions": ["action.system.home"], "entities": ["entity.system.home"] } ]

6.3 坑三：module.json5 位置错误

// ✅ 正确位置 entry/src/main/module.json5 // 🚫 错误位置 entry/module.json5 AppScope/module.json5

七、module.json5 与 app.json5 的协作

7.1 职责分离

7.2 app.json5 配置

{ "app": { "bundleName": "com.maomaodazuozhan.game", "vendor": "maomaodazuozhan", "versionCode": 1000000, "versionName": "1.0.0", "icon": "$media:app_icon", "label": "$string:app_name", "description": "$string:app_desc" } }

7.3 $引用资源规则

// $string:xxx → 引用 resources/base/element/string.json 中的字符串 // $media:xxx → 引用 resources/base/media/ 中的媒体文件 // $color:xxx → 引用 resources/base/element/color.json 中的颜色值 // $profile:xxx → 引用 resources/base/profile/ 中的 JSON 文件

八、module.json5 配置检查清单

• name与模块目录名一致
• type正确（entry/feature/har/hsp）
• deviceTypes包含目标设备
• abilities[].srcEntry路径正确（./ets/...）
• abilities[].exported按需设置
• entry 模块的 EntryAbility 配置了skills+action.system.home
• pages引用正确的 profile 文件
• $string/$media/$color资源都已在相应目录存在

九、总结

module.json5是 HarmonyOS 模块的“身份证“，定义了模块是什么类型、在哪些设备上运行、包含哪些 Ability、如何响应系统意图。理解其配置规则是正确构建和发布应用的基础。

核心要点：

• type: entry是主模块，feature是特性模块，一个应用只有一个 entry
• deviceTypes限制了应用安装的目标设备
• abilities[]注册所有 Ability，exported控制能否被外部启动
• skills中的action.system.home是桌面图标入口的必须配置
• srcEntry路径相对于src/main/，需加上./ets/前缀
• $profile:main_pages引用路由配置，$string/$media引用资源

下一篇预告：第 77 篇将深入app.json5全局配置——bundleName、版本管理、图标标签与签名配置。

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

相关资源：

• module.json5 配置文档
• Ability 配置与启动
• 多设备类型开发指南
• 应用包结构与配置
• skills 意图过滤器
• 开源鸿蒙跨平台社区
• 第 75 篇：onForeground/onBackground
• 第 77 篇：app.json5 全局配置