前言在 HarmonyOS 应用开发中配置文件是连接代码与系统的重要桥梁。module.json5定义了模块的基本信息、Ability 注册、权限声明等而main_pages.json则管理着所有页面的路由注册。“海风日记“共包含28 个页面所有页面都需要在main_pages.json中注册同时module.json5中配置了 EntryAbility 的启动信息、图标、标签等。本文将从源码出发深入讲解这两个配置文件的完整结构和最佳实践。一、module.json5 概述1.1 文件位置module.json5位于每个模块的src/main/目录下entry/ src/ main/ module.json5 ← 模块配置文件 ets/ ← ArkTS 源码 resources/ ← 资源文件1.2 海风日记的 module.json5{ 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:app_icon, label: $string:EntryAbility_label, startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [action.system.home] } ] } ] } }1.3 顶层配置项配置项类型说明海风日记的值namestring模块名称entrytypestring模块类型entry入口模块descriptionstring模块描述$string:module_descmainElementstring入口 AbilityEntryAbilitydeviceTypesstring[]支持的设备类型[phone]deliveryWithInstallboolean是否随安装包交付trueinstallationFreeboolean是否免安装falsepagesstring页面配置文件$profile:main_pages二、模块类型详解2.1 模块类型HarmonyOS 支持三种模块类型类型说明用途entry应用入口模块包含主 Ability每个应用只有一个feature功能模块可独立安装或按需加载shared共享模块HSP共享代码和资源HAR 的替代方案2.2 entry 模块的特点{ module: { type: entry, // 入口模块 deliveryWithInstall: true, // 随安装包交付 installationFree: false // 非免安装 } }entry 模块的特点每个应用有且只有一个 entry 模块必须包含mainElement指定的入口 AbilitydeliveryWithInstall通常为trueinstallationFree通常为false2.3 feature 模块的特点{ module: { type: feature, // 功能模块 deliveryWithInstall: false, // 按需安装 installationFree: true // 支持免安装 } }feature 模块的特点一个应用可以有多个 feature 模块支持按需下载和安装支持免安装运行需installationFree: true三、Ability 配置详解3.1 基本配置{ abilities: [ { name: EntryAbility, // Ability 名称 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: [...] // 意图过滤器 } ] }3.2 配置项详细说明配置项必填说明name是Ability 类名需与代码中的类名一致srcEntry是源码文件路径相对于ets/目录description否能力描述可引用资源icon是应用图标建议使用$media:xxx引用label是应用名称显示在桌面startWindowIcon否冷启动时显示的图标startWindowBackground否冷启动时的背景色exported否是否允许其他应用启动该 Abilityskills否意图过滤器数组3.3 启动窗口配置startWindowIcon和startWindowBackground控制冷启动时的启动窗口{ startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background }启动窗口的配置策略策略说明效果统一背景使用应用主色启动时显示品牌色减少白屏透明背景使用透明色启动时显示桌面壁纸模拟首屏使用首屏页面的颜色启动到首屏无缝过渡3.4 skills 意图过滤器{ skills: [ { entities: [entity.system.home], // 桌面入口 actions: [action.system.home] // 主页动作 } ] }skills配置了 Ability 能够响应的意图entitiesactions说明entity.system.homeaction.system.home应用桌面图标入口entity.system.browsableaction.system.view浏览器打开链接entity.system.shareaction.system.share接收分享数据四、main_pages.json 页面路由配置4.1 文件位置main_pages.json位于resources/base/profile/目录下entry/ src/ main/ resources/ base/ profile/ main_pages.json ← 页面路由配置文件4.2 海风日记的 main_pages.json“海风日记“共注册了 26 个页面路径{ src: [ pages/SplashPage, pages/Index, pages/onboarding/OnboardingPage, pages/login/LoginPhonePage, pages/login/LoginNamePage, pages/diary/WriteDiaryPage, pages/diary/EditDiaryPage, pages/diary/DiaryDetailPage, pages/diary/DiaryDetail2Page, pages/calendar/CalendarYearPage, pages/search/SearchPage, pages/tag/TagDetailPage, pages/premium/PremiumPage, pages/privacy/PrivacyPasswordPage, pages/image/ImageViewerPage, pages/mine/ProfileInfoPage, pages/mine/PersonalSettingsPage, pages/mine/AccountSettingsPage, pages/mine/PhoneBindPage, pages/mine/TagManagePage, pages/mine/SpaceManagePage, pages/mine/DataManagePage, pages/mine/FaqPage, pages/mine/AboutPage, pages/mine/EmailFeedbackPage, pages/mine/DarkModePage ] }4.3 页面路径的规则页面路径的规则如下规则说明示例相对路径相对于ets/目录pages/SplashPage不带扩展名不需要.ets后缀正确pages/SplashPage区分大小写路径大小写敏感pages/SplashPagevspages/splashpage目录结构按功能目录组织pages/mine/AboutPage4.4 页面路径的组织方式“海风日记“的页面按功能模块组织目录pages/ ├── SplashPage # 闪屏页 ├── Index # 首页Tabs 导航框架 ├── onboarding/ # 引导页 │ └── OnboardingPage ├── login/ # 登录 │ ├── LoginPhonePage │ └── LoginNamePage ├── diary/ # 日记 │ ├── WriteDiaryPage │ ├── EditDiaryPage │ ├── DiaryDetailPage │ └── DiaryDetail2Page ├── calendar/ # 日历 │ └── CalendarYearPage ├── search/ # 搜索 │ └── SearchPage ├── tag/ # 标签 │ └── TagDetailPage ├── premium/ # 订阅 │ └── PremiumPage ├── privacy/ # 隐私 │ └── PrivacyPasswordPage ├── image/ # 图片 │ └── ImageViewerPage ├── mine/ # 个人中心 │ ├── ProfileInfoPage │ ├── PersonalSettingsPage │ ├── AccountSettingsPage │ ├── ... │ └── DarkModePage五、资源引用体系5.1 资源文件的存放位置resources/ ├── base/ │ ├── element/ │ │ ├── color.json ← 颜色资源 │ │ └── string.json ← 字符串资源 │ ├── media/ │ │ └── app_icon.png ← 图片资源 │ └── profile/ │ └── main_pages.json ← 页面配置5.2 字符串资源{ string: [ { name: module_desc, value: 海风日记 - 让每一天随海风飘散 }, { name: EntryAbility_desc, value: 海风日记主入口 }, { name: EntryAbility_label, value: 海风日记 } ] }5.3 颜色资源{ color: [ { name: start_window_background, value: #FAFAF7 } ] }5.4 资源引用的方式引用方式语法说明字符串$string:module_desc引用string.json中的字符串颜色$color:start_window_background引用color.json中的颜色图片$media:app_icon引用media/目录下的图片配置文件$profile:main_pages引用profile/目录下的 JSON 配置系统图标$r(sys.symbol.house)引用系统 Symbol 图标六、多设备适配6.1 deviceTypes 配置{ deviceTypes: [phone] }“海风日记“目前仅支持手机设备。如果需要支持更多设备{ deviceTypes: [ phone, tablet, 2in1 // 二合一设备 ] }6.2 资源限定词HarmonyOS 支持通过资源限定词适配不同设备resources/ ├── base/ ← 默认资源 ├── en_US/ ← 英语美国 ├── zh_CN/ ← 中文简体 ├── dark/ ← 深色模式 └── tablet/ ← 平板专用资源6.3 设备适配的最佳实践使用vp单位自适应不同屏幕密度使用%百分比自适应不同屏幕尺寸使用breakpoint响应式布局断点使用资源限定词不同语言、主题使用不同资源七、常见问题与排查7.1 页面路由无法跳转问题调用router.pushUrl()时提示页面不存在。原因页面未在main_pages.json中注册。解决方案检查并添加缺失的页面路径{ src: [ pages/mine/NewPage // 添加新页面 ] }7.2 Ability 启动失败问题应用启动时闪退提示 Ability 未找到。原因module.json5中的name或srcEntry配置错误。解决方案{ abilities: [ { name: EntryAbility, // 必须与代码类名一致 srcEntry: ./ets/entryability/EntryAbility.ets // 路径必须正确 } ] }7.3 资源引用无效问题$string:xxx或$color:xxx引用无效。原因资源名称拼写错误或资源文件中未定义。解决方案检查资源文件中的name字段{ string: [ { name: module_desc, // 引用时使用此名称 value: 海风日记 } ] }7.4 配置文件调试方法# 检查 module.json5 格式 hvigorw --mode module -p moduleentrydefault assembleHap # 查看 HAP 包中的资源 cd build/default/outputs/default/ unzip -l entry-default-unsigned.hap | grep module.json总结本文详细讲解了 HarmonyOS 应用开发中的两个核心配置文件module.json5模块配置定义模块类型、Ability 注册、设备类型等main_pages.json页面路由注册所有页面必须在此注册Ability 配置入口配置、启动窗口、意图过滤器资源引用体系字符串、颜色、图片、配置文件的引用方式多设备适配deviceTypes、资源限定词、响应式布局下一篇文章将深入讲解Entry 与 Component 装饰器分析组件声明、导出和状态管理的核心机制敬请期待。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源module.json5 配置文档Ability 配置指南资源文件使用指南海风日记项目源码[HarmonyOS 开发者官网](https://atomgit.com/openharmony/docs开源鸿蒙跨平台社区多设备适配指南HAP 包结构
