企业官网建设流程全解析

前言

在 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 顶层配置项

二、模块类型详解

2.1 模块类型

HarmonyOS 支持三种模块类型：

2.2 entry 模块的特点

{ "module": { "type": "entry", // 入口模块 "deliveryWithInstall": true, // 随安装包交付 "installationFree": false // 非免安装 } }

entry 模块的特点：

1. 每个应用有且只有一个 entry 模块
2. 必须包含mainElement指定的入口 Ability
3. deliveryWithInstall通常为true
4. installationFree通常为false

2.3 feature 模块的特点

{ "module": { "type": "feature", // 功能模块 "deliveryWithInstall": false, // 按需安装 "installationFree": true // 支持免安装 } }

feature 模块的特点：

1. 一个应用可以有多个 feature 模块
2. 支持按需下载和安装
3. 支持免安装运行（需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 配置项详细说明

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 能够响应的意图：

四、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 页面路径的规则

页面路径的规则如下：

4.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 资源引用的方式

六、多设备适配

6.1 deviceTypes 配置

{ "deviceTypes": ["phone"] }

“海风日记“目前仅支持手机设备。如果需要支持更多设备：

{ "deviceTypes": [ "phone", "tablet", "2in1" // 二合一设备 ] }

6.2 资源限定词

HarmonyOS 支持通过资源限定词适配不同设备：

resources/ ├── base/ ← 默认资源 ├── en_US/ ← 英语（美国） ├── zh_CN/ ← 中文（简体） ├── dark/ ← 深色模式 └── tablet/ ← 平板专用资源

6.3 设备适配的最佳实践

1. 使用vp单位：自适应不同屏幕密度
2. 使用%百分比：自适应不同屏幕尺寸
3. 使用breakpoint：响应式布局断点
4. 使用资源限定词：不同语言、主题使用不同资源

七、常见问题与排查

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 module=entry@default assembleHap # 查看 HAP 包中的资源 cd build/default/outputs/default/ unzip -l entry-default-unsigned.hap | grep module.json

总结

本文详细讲解了 HarmonyOS 应用开发中的两个核心配置文件：

1. module.json5：模块配置，定义模块类型、Ability 注册、设备类型等
2. main_pages.json：页面路由注册，所有页面必须在此注册
3. Ability 配置：入口配置、启动窗口、意图过滤器
4. 资源引用体系：字符串、颜色、图片、配置文件的引用方式
5. 多设备适配：deviceTypes、资源限定词、响应式布局

下一篇文章将深入讲解@Entry 与 @Component 装饰器，分析组件声明、导出和状态管理的核心机制，敬请期待。

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

相关资源：

• module.json5 配置文档
• Ability 配置指南
• 资源文件使用指南
• 海风日记项目源码
• [HarmonyOS 开发者官网](https://atomgit.com/openharmony/docs
• 开源鸿蒙跨平台社区
• 多设备适配指南
• HAP 包结构