当前位置： 首页 > news >正文

03 module.json5 配置文件全解：能力声明、权限申请与设备支持

news 2026/7/9 3:10:47

03 module.json5 配置文件全解：能力声明、权限申请与设备支持

前言

图：03 module.json5 配置文件全解：能力声明、权限申请与设备支持 运行效果截图（HarmonyOS NEXT）

在 HarmonyOS NEXT Stage 模型中，module.json5是每个模块（Module）的"户口本"——它向系统声明了这个模块有什么能力（Ability）、请求了什么权限、支持什么设备。配置错误可能导致应用无法安装、权限申请失败或 HAP 在不兼容设备上崩溃。

本文以"鹿鹿·笔迹心理分析"的完整module.json5配置为例，逐字段解析每个配置项的含义、类型、可选值和实际影响。

官方文档·module.json5 配置说明：developer.huawei.com
项目源码仓库：harmony-app（GitHub）

图：module.json5 核心配置层级——module → abilities / extensionAbilities / requestPermissions

一、module.json5 文件位置与作用

1.1 文件位置

entry/ └── src/main/ └── module.json5 ← 就是这个文件

每个 Module（entry/feature/hsp）都有一个独立的module.json5，它描述了该 Module 的元数据。

1.2 与 app.json5 的区别

配置文件位置作用范围主要内容
AppScope/app.json5AppScope 目录整个应用（全局）应用包名、版本号、图标、标签
entry/module.json5每个 Module单个 ModuleAbility、权限、设备类型、页面路由

二、module.json5 完整配置解析

2.1 顶层结构

{"module":{"name":"entry","type":"entry","description":"$string:module_desc","mainElement":"EntryAbility","deviceTypes":["phone"],"deliveryWithInstall":true,"installationFree":false,"pages":"$profile:main_pages","abilities":[...],"extensionAbilities":[...],"requestPermissions":[...]}}

2.2 基础字段说明

字段类型说明项目值
namestringModule 名称，需唯一"entry"
typestringModule 类型"entry"（入口模块）
descriptionstring模块描述，支持资源引用"$string:module_desc"
mainElementstring应用启动时的入口 Ability"EntryAbility"
deviceTypesstring[]支持的设备类型列表["phone"]
deliveryWithInstallboolean是否随应用安装一起下载true
installationFreeboolean是否免安装（原子化服务）false
pagesstring页面路由配置文件引用"$profile:main_pages"

2.3 deviceTypes 设备类型

deviceTypes数组决定了应用支持的设备范围：

// 仅支持手机"deviceTypes":["phone"]// 支持手机+平板"deviceTypes":["phone","tablet"]// 支持手机+平板+智慧屏"deviceTypes":["phone","tablet","2in1","tv"]

支持的设备类型值：

值设备
"phone"智能手机
"tablet"平板电脑
"2in1"二合一设备（折叠屏/平板+键盘）
"tv"智慧屏/TV
"wearable"可穿戴设备（手表等）
"car"车机

提示："鹿鹿"项目当前仅支持phone。若要在平板上适配，需要额外实现响应式布局和多窗口支持。

三、abilities 配置详解

3.1 abilities 数组

abilities数组定义了 Module 中所有的UIAbility：

"abilities":[{"name":"EntryAbility","srcEntry":"./ets/EntryAbility.ets","description":"$string:EntryAbility_desc","icon":"$media:app_icon","label":"$string:EntryAbility_label","startWindowIcon":"$media:startIcon","startWindowBackground":"$color:start_window_background","exported":true,"launchType":"singleton","skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]}]

3.2 Ability 字段逐项说明

字段必须说明示例值
name✅Ability 名称，需唯一"EntryAbility"
srcEntry✅源码相对路径"./ets/EntryAbility.ets"
description推荐Ability 描述（本地化）"$string:EntryAbility_desc"
icon推荐任务栏图标"$media:app_icon"
label推荐任务栏标签（应用名）"$string:EntryAbility_label"
startWindowIcon推荐启动白屏时显示的图标"$media:startIcon"
startWindowBackground推荐启动白屏背景色"$color:start_window_background"
exported推荐是否允许其他应用拉起true（桌面入口）
launchType可选启动模式"singleton"（默认单实例）

3.3 skills（能力标签）

skills声明了 Ability 能够响应的 Intent（意图）。桌面图标入口必须声明：

"skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]
  • entity.system.home：表示这是桌面入口
  • action.system.home：表示响应桌面启动操作

桌面图标

skills 匹配

entity.system.home ✅

action.system.home ✅

启动 EntryAbility

3.4 launchType 启动模式

模式含义适用场景
singleton单实例（默认）主入口 Ability，全局唯一
standard标准（多实例）需要多个独立实例的场景
specified指定实例按条件选择或创建实例

四、requestPermissions 权限声明

4.1 鸿蒙权限模型

鸿蒙采用静态声明 + 动态授权的两阶段权限模型：

normal 普通权限

system_basic 系统基础权限

system_core 系统核心权限

module.json5 静态声明

应用安装时系统校验

权限等级?

安装即自动授予

运行时弹窗请求用户授权

需要系统签名，普通应用不可用

用户同意 → 权限生效

用户拒绝 → 功能降级

4.2 项目权限声明完整示例

"requestPermissions":[{"name":"ohos.permission.CAMERA","reason":"$string:camera_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.READ_IMAGEVIDEO","reason":"$string:storage_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.WRITE_IMAGEVIDEO","reason":"$string:write_storage_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.NFC_TAG","reason":"$string:nfc_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}}]

4.3 权限字段逐项说明

字段必须说明
name✅权限名称（官方定义的字符串常量）
reason✅（system_basic 级别必须）权限申请原因（用户可见），必须使用$string:资源引用
usedScene.abilities可选使用该权限的 Ability 列表
usedScene.when可选"inuse"（前台使用）或"always"（后台也需要）

4.4 项目用到的权限一览

权限级别用途使用时机
ohos.permission.CAMERAsystem_basic拍照功能进入 CapturePage 时
ohos.permission.READ_IMAGEVIDEOsystem_basic从相册选图使用相册功能时
ohos.permission.WRITE_IMAGEVIDEOsystem_basic保存图片到相册导出分析图片时
ohos.permission.NFC_TAGnormalNFC 碰一碰使用配对功能时

五、$profile 资源引用机制

5.1 main_pages 引用

"pages": "$profile:main_pages"中的$profile:前缀用于引用resources/base/profile/目录下的配置文件：

entry/src/main/resources/base/profile/ └── main_pages.json ← $profile:main_pages 指向此文件
// main_pages.json 完整示例{"src":["pages/LoginPage","pages/HomePage","pages/CapturePage","pages/AnalyzingPage","pages/ReportDetailPage"]}

5.2 其他 $ 前缀资源引用

引用格式作用示例
$string:xxx引用字符串资源"$string:app_name"
$media:xxx引用媒体资源（图片、SVG）"$media:app_icon"
$color:xxx引用颜色资源"$color:start_window_background"
$profile:xxx引用 profile JSON 配置文件"$profile:main_pages"
// resources/base/element/color.json{"color":[{"name":"start_window_background","value":"#F1ECE2"}]}

六、完整的 module.json5

6.1 项目完整配置

{"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.ets","description":"$string:EntryAbility_desc","icon":"$media:app_icon","label":"$string:EntryAbility_label","startWindowIcon":"$media:startIcon","startWindowBackground":"$color:start_window_background","exported":true,"launchType":"singleton","skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]}],"requestPermissions":[{"name":"ohos.permission.CAMERA","reason":"$string:camera_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.READ_IMAGEVIDEO","reason":"$string:storage_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.WRITE_IMAGEVIDEO","reason":"$string:write_storage_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}},{"name":"ohos.permission.NFC_TAG","reason":"$string:nfc_permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"inuse"}}]}}

6.2 配置常见错误

错误场景原因解决方案
应用安装后桌面无图标skills未声明entity.system.home检查 abilities 中的 skills 配置
权限弹窗未出现module.json5 中未声明权限在 requestPermissions 中添加对应权限
Camera 功能崩溃权限申请了但未在代码中动态请求使用requestPermissionsFromUser动态申请
模拟器上运行正常，真机崩溃模拟器跳过了某些权限检查确保所有权限都已声明并动态申请

七、动态权限申请代码

7.1 在代码中动态请求权限

仅在module.json5中声明权限还不够，system_basic级别的权限必须在代码中再次动态申请：

// CapturePage.ets — 进入相机前检查并申请权限import{abilityAccessCtrl,Permissions}from'@kit.AbilityKit';privateasynccheckAndRequestPermissions():Promise<boolean>{constpermissions:Permissions[]=['ohos.permission.CAMERA','ohos.permission.READ_IMAGEVIDEO'];constatManager=abilityAccessCtrl.createAtManager();// 检查权限状态constgrantStatus=awaitatManager.checkAccessToken(this.context.tokenID,'ohos.permission.CAMERA');if(grantStatus===abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED){returntrue;// 已有权限}// 请求权限constresult=awaitatManager.requestPermissionsFromUser(this.context,permissions);returnresult.authResults[0]===abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;}

八、注意事项与常见问题

8.1 开发注意事项

在实际开发过程中，需特别注意以下几点：

  • API 兼容性：部分接口仅在特定 HarmonyOS NEXT 版本中可用，需做版本条件判断
  • 权限模型：采用静态声明（module.json5）+ 动态申请（requestPermissionsFromUser）的两阶段授权
  • 生命周期：合理使用aboutToAppear()和aboutToDisappear()管理资源初始化与释放
  • 状态同步：跨页面数据通过 AppStorage 共享，组件内状态使用@State/@Prop/@Link装饰器

8.2 常见错误与解决方案

常见问题快速排查表：

问题类型排查方向参考方法
应用崩溃查看 hilog 错误日志hilog.error(TAG, "...", e.message)
状态丢失检查 AppStorage 键名拼写统一使用常量管理键名
动画不流畅避免在 animateTo 回调中执行 I/O动画与数据操作分离

总结

module.json5是鸿蒙应用模块的核心配置文件，关键要点：

  1. 基础字段：name、type、mainElement、deviceTypes是必须正确填写的基础配置
  2. abilities 配置：每个 UIAbility 都需要在此声明，桌面入口必须配置正确的skills
  3. 权限声明：所有需要的权限必须先在requestPermissions中静态声明，再在代码中动态申请
  4. **p r o f i l e 引用 ∗ ∗ ：通过 ‘ profile 引用**：通过 `profile引用∗∗：通过‘profile:main_pages` 引用页面路由配置，实现配置与代码分离

下一篇预告：第04篇 oh-package.json5 与依赖管理

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

相关资源：

  • module.json5 配置说明
  • abilities 配置详解
  • requestPermissions 说明
  • 权限申请开发指南
  • 第02篇 Stage模型
  • 第04篇 oh-package.json5
  • 第05篇 路由配置
  • HarmonyOS 应用配置最佳实践
http://www.jsqmd.com/news/1151641/

相关文章：

  • 从分布式视角看 SFT【直接提供考试答案给学生背下来，学生只能应对背过答案的考试试卷】、RL 以及OPD（On-Policy Distillation）【学生先自己做题，老师批改，学生修改提高能力】
  • Windows下关于flutter在cmd进行version或者doctor卡死的情况
  • 盲目扫描易踩红线，一文弄懂主动渗透和被动渗透
  • AI 赋能门诊场景：核心应用与实效展示
  • 平面变压器到底跑在什么频率上？
  • 基于STM32单片机智能温控风扇系统PWM调速 人体红外 蓝牙 成品31(设计源文件+万字报告+讲解)（支持资料、图片参考_相关定制）_
  • Capvidia宣布发布2026 R1软件版本，以增强MBD准备就绪能力、QIF工作流以及数字主线自动化
  • OpenAI text-embedding-3-large 模型实战：构建10万条PDF文档向量知识库
  • 【计算机大数据毕业设计案例】基于 Django 的宁波五金电商线上销售营销可视化平台的设计与实现 基于时序数据统计的宁波五金电商营销热度分析系统(程序+文档+讲解+定制)
  • ChatGPT 学术写作 Prompt 工程：10个指令覆盖论文全流程，实测提升效率40%
  • Linux动态壁纸革命：告别静态桌面，拥抱沉浸式视觉体验
  • 2026 桌面AI实战！从零开发菜谱小程序：30分钟完成原本一天的工作量
  • dp 与 hdmi
  • 工业预诊：10 未来：全厂自愈系统
  • 基于睡眠脑电数据的认知流形几何特征初探——对认知统一场论的间接验证（世毫九实验室原创研究）
  • web结课大作业成果展示
  • 【计算机大数据毕业设计案例】基于 Django 的微博热门事件数据采集与分析系统的设计与实现 基于舆情挖掘的微博热点事件智能分析系统(程序+文档+讲解+定制)
  • DLSS Swapper完整指南：如何一键智能管理游戏DLSS版本
  • 【199管理类联考】写作（第一轮复习）
  • React Fiber 渲染性能优化
  • 【大数据课程设计/毕业设计】基于电商大数据的宁波五金线上营销决策辅助系统的设计与实现 基于可视化展示的宁波五金电商推广运营分析系统【附源码、数据库、万字文档】
  • 多元线性回归案例：加州房价预测
  • Rust Bevy 0.13 到 0.14 升级踩坑指南
  • 变分推断 vs MCMC：3 大维度对比与贝叶斯计算选型指南
  • 从零构建Claude-MCP协同工作流：企业DevOps团队必须掌握的4层认证与审计规范
  • 2026 上海嘉定企业 GEO 优化服务商深度测评：本地制造企业优选企优托一网推罗琪
  • 游戏画面撕裂原理解析：从帧率、垂直同步到G-Sync/FreeSync 3种解决方案对比
  • 一盏灯里的“中国制造”——从代工到品牌
  • F12 Overrides/Sources 页面应用：5分钟实现JS文件本地替换与调试
  • AIGC 全流程解析：从剧本到视频的完整创作指南