前言module.json5是 HarmonyOSStage 模型中模块级的核心配置文件它定义了模块的名称、类型、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是模块最基本的两个属性属性值说明nameentry模块名称在同一应用中唯一typeentry模块类型模块类型type的三种取值类型说明应用场景entry应用主模块可独立安装运行一个应用至少一个feature功能模块依赖 entry 模块按需加载shared共享模块提供共享代码和资源2.2 descriptiondescription: $string:module_descdescription引用资源文件中的字符串{ string: [ { name: module_desc, value: 萌宠日记应用 } ] }使用资源引用的优势支持多语言自动切换编译时进行资源校验便于统一管理所有文案2.3 mainElementmainElement: EntryAbilitymainElement指定模块的入口 Ability名称它必须与abilities数组中某个 Ability 的name一致。当系统启动该模块时会首先创建mainElement指定的 Ability。三、设备类型配置3.1 deviceTypesdeviceTypes: [ phone ]deviceTypes指定模块支持的设备类型。HarmonyOS 支持多种设备类型设备类型标识说明手机phone默认设备类型平板tablet大屏设备智能穿戴wearable手表等智慧屏tv电视设备车机car车载设备2in1 设备twoInOne平板/笔记本二合一3.2 多设备适配萌宠日记当前仅支持phone设备但后续可以扩展// 多设备支持的配置示例 deviceTypes: [ phone, tablet, twoInOne ]多设备适配需要搭配资源限定符和响应式布局共同实现资源限定符为不同屏幕尺寸提供不同布局资源响应式布局使用layoutWeight等弹性布局实现自适应四、安装配置4.1 deliveryWithInstalldeliveryWithInstall: truedeliveryWithInstall控制模块是否随应用安装一起下发值行为适用场景true随应用安装时下发主模块、核心功能模块false按需下载功能模块、插件模块萌宠日记使用true因为 entry 模块是应用的主模块必须随安装一起下发。4.2 installationFreeinstallationFree: falseinstallationFree控制模块是否支持免安装运行值行为说明true支持免安装用户无需安装即可运行有大小限制通常 ≤10MBfalse需安装后运行标准安装模式无大小限制五、页面路由配置5.1 pages 属性pages: $profile:main_pagespages通过$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 页面注册规则页面注册的注意事项所有页面必须注册每个可在路由中访问的页面都需在src数组中列出路径规则路径相对于src/main/ets/目录不含.ets后缀首屏页面第一个通过loadContent加载的页面SplashPage必须在列表中路由跳转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 基础属性说明属性值说明nameEntryAbilityAbility 名称在同一模块中唯一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 与 skillsexported: true, skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ]exported控制 Ability 是否可被其他应用调用值含义萌宠日记场景true可被外部应用通过 Want 启动从桌面图标启动false仅内部使用内部辅助 Abilityskills定义了 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.backupvalue字符串值直接指定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 配置项清单有序列表 — 配置后的检查清单确认bundleName与应用签名一致确认所有页面路径拼写正确确认 Ability 的srcEntry路径指向实际文件确认deviceTypes包含目标设备类型确认skills配置正确应用可从桌面启动9.2 配置优化建议使用资源引用description、icon、label等属性优先使用$string:、$media:引用保持配置简洁只配置必要的字段避免冗余版本同步versionCode和versionName随版本更新同步递增注释规范JSON5 格式支持注释可添加配置说明十、从 FA 到 Stage 的配置迁移10.1 配置差异对比配置项FA 模型Stage 模型配置文件config.jsonmodule.json5app.json5格式JSONJSON5支持注释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文件出发深入解析了 HarmonyOSStage 模型下模块配置的每一个字段模块基础属性name、type、description、mainElement设备类型配置deviceTypes 及多设备适配安装配置deliveryWithInstall、installationFree页面路由pages 引用 main_pages.jsonAbility 配置入口、启动窗口、skills扩展能力ExtensionAbility 的备份能力集成配置最佳实践校验规则、调试方法、迁移指南理解 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-stageUIAbility 配置https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usageExtensionAbility 概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/extensionability-overview应用程序包结构https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-structure-stageHAP 包配置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