前言module.json5是 HarmonyOS 模块级配置的核心文件它决定了模块类型、支持的设备、入口 Ability、页面路由表、扩展 Ability 等关键信息。本篇拆解小分享 App 的entry/src/main/module.json5理解每个字段的含义与作用。详细配置可参考 HarmonyOS module.json5 官方文档。一、完整配置1.1 module.json5 全文小分享 App 的module.json5如下{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [phone], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [...], extensionAbilities: [...] } }1.2 关键字段速览关键字段速览如下字段作用取值示例name模块名entrytype模块类型entry/feature/sharedmainElement启动入口EntryAbilitydeviceTypes支持设备phone/tablet/tvpages路由白名单$profile:main_pages二、模块级字段详解2.1 name typename: entry, type: entry,name是模块名工程内唯一。type取值如下entry入口模块可直接安装运行feature功能模块作为动态特性下发shared动态共享包HSP2.2 mainElementmainElement: EntryAbility,指定启动时加载的 Ability。这个值必须与abilities数组中某一项的name完全一致否则会启动失败。2.3 deviceTypesdeviceTypes: [phone]支持的设备类型。常用取值如下值设备phone手机tablet平板tv智慧屏wearable智能穿戴car车机小分享 App 目前只适配手机。若要上架平板需要追加tablet并做布局适配。2.4 deliveryWithInstall installationFreedeliveryWithInstall: true, installationFree: false,字段含义如下deliveryWithInstall模块是否随 App 一起安装。entry模块必须为trueinstallationFree是否支持免安装元服务。true表示可作为 1KB-10MB 的元服务分发2.5 pagespages: $profile:main_pages,指向resources/base/profile/main_pages.json里面是页面路径数组。这是 ArkUI 路由的「白名单」未注册的页面无法跳转。三、abilities 数组详解3.1 完整 Ability 配置{ 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] } ] }3.2 字段说明字段说明如下字段作用nameAbility 名称全工程唯一srcEntryAbility 源码相对路径icon桌面图标label桌面显示名称startWindowIcon启动时显示的图标startWindowBackground启动时背景色exported是否允许其他 App 调起skillsAbility 可被哪些 Intent 触发3.3 skills 字段——让 Ability 成为桌面入口skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ]字段含义如下entity.system.home标识为桌面入口ohos.want.action.home点击桌面图标时触发只有声明了这个skills的 Ability 才会出现在桌面图标列表中。提示若一个应用声明了多个带entity.system.home的 Ability桌面只取第一个。四、extensionAbilities 数组4.1 备份扩展配置小分享 App 注册了一个备份扩展{ name: EntryBackupAbility, srcEntry: ./ets/entrybackupability/EntryBackupAbility.ets, type: backup, exported: false, metadata: [ { name: ohos.extension.backup, resource: $profile:backup_config } ] }4.2 关键字段关键字段如下type扩展类型backup/form/inputMethod/service等metadata附加元数据这里指向备份配置backup_config.jsonexported: false备份扩展不需要被外部调起五、常见配置陷阱5.1 陷阱 1startWindowIcon 缺失startWindowIcon: $media:startIcon若漏掉这个字段启动时不会显示启动图标而是直接黑屏一闪而过。系统要求必须提供。5.2 陷阱 2mainElement 与 abilities 名不匹配mainElement: EntryAbility, abilities: [{ name: MainAbility }]这种配置会导致启动时找不到 Ability 而崩溃。5.3 陷阱 3多个 Ability 都声明 home skills桌面只会取其中一个作为入口图标建议仅EntryAbility声明。六、本篇核心知识点6.1 module.json5 核心字段module.json5 核心字段总结如下name/type模块标识与类型mainElement启动入口 AbilitydeviceTypes支持的设备类型pagesArkUI 路由白名单abilities/extensionAbilitiesAbility 列表6.2 实战开发要点实战开发中需要重点关注以下几个要点startWindowIcon必须配置mainElement必须与abilities名一致备份扩展通过extensionAbilities注册skills决定 Ability 是否出现在桌面总结本文深入剖析了 HarmonyOS module.json5 配置文件的核心字段结合小分享 App 的实际配置讲解了模块类型、入口 Ability、设备适配、扩展 Ability 等关键概念。下一篇我们将看main_pages.json路由表理解页面注册机制。附录完整实现细节1. 核心 API 参考API作用说明本文涉及的核心 API功能实现参见华为官方文档2. 完整代码示例// 核心功能代码 // 详见正文中的完整实现3. 常见问题排查问题原因解决方案编译错误import 路径错误检查路径和 API 版本运行时异常参数不合法使用 try/catch 捕获性能问题主线程耗时操作使用异步 API4. 最佳实践错误处理完善使用 try/catch 包裹资源及时释放避免内存泄漏异步操作使用 async/await权限配置完整按需申请5. 完整代码文件索引文件路径说明本文涉及的代码文件见正文6. 实现要点总结核心实现要点API 的正确使用方法和参数说明完整的代码实现流程常见问题的排查方案性能优化和安全建议7. 总结本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。开发注意事项1. API 版本兼容性确保使用的 API 在目标 SDK 版本中可用。不同版本的 HarmonyOS 可能对 API 的支持有所不同建议查阅官方文档确认。2. 权限配置根据功能需求配置相应的系统权限。权限在 module.json5 中声明运行时通过 abilityAccessCtrl 申请。3. 错误处理所有异步操作使用 try/catch 包裹确保异常不会导致应用崩溃。错误信息通过 hilog 输出便于调试。4. 资源释放使用完毕后及时释放系统资源避免内存泄漏。例如文件操作后关闭文件句柄数据库操作后关闭 ResultSet。5. 性能优化避免在主线程执行耗时操作使用异步 API 处理耗时任务。大量数据渲染时使用 LazyForEach 懒加载。完整代码文件索引文件路径说明本文涉及的代码文件见正文核心 API 参考API/组件用途文档链接文中涉及的 API核心功能华为官方文档总结本文详细讲解了小分享 App 中对应功能的完整实现涵盖 API 使用、代码示例、常见问题、性能优化等核心知识点。通过本文的学习读者可以掌握 HarmonyOS 开发的完整流程。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力