文章目录
- 前言
- 文件长什么样
- 逐字段讲解
- 注册一个新 Ability 的正确步骤
- 代码实现
- 权限怎么加才规范
- 核心代码
- 常见误区（小白必踩）
- 完整可运行示例：module.json5 真配置
- 完整示例
- 写在最后
前言
module.json5是每个 HarmonyOS 模块的"身份证"。Ability 怎么注册、图标长啥样、要哪些权限，全写在这一个文件里。
我刚学时最怕动它，生怕写错一个字段 app 就起不来。后来发现它其实很有规律。这篇文章我把最常用的配置项逐个拆开讲，你照着改就行，不用背。
文件长什么样
{ "module": { "name": "entry", "type": "entry", "mainElement": "EntryAbility", "deviceTypes": ["phone", "tablet"], "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ts", "description": "$string:EntryAbility_desc", "icon": "$media:icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:startIcon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ], "requestPermissions": [ { "name": "ohos.permission.INTERNET", "reason": "$string:internet_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "always" } } ] } }逐字段讲解
| 字段 | 作用 | 说明 |
|---|---|---|
name | 模块名 | 一般entry |
type | 模块类型 | entry（入口）/feature（特性） |
mainElement | 启动 Ability | 写你入口 Ability 名 |
deviceTypes | 支持设备 | phone/tablet/tv等 |
abilities[].name | Ability 名 | 要和代码里类名一致 |
abilities[].srcEntry | 代码路径 | 指到你的 .ts 文件 |
abilities[].exported | 是否可被外部拉起 | 入口一般true |
abilities[].skills | 启动能力 | entity.system.home表示桌面图标入口 |
requestPermissions | 申请的权限列表 | 每个权限要写理由 |
注册一个新 Ability 的正确步骤
我踩过"只建了文件却忘了注册"的坑，结果跳转直接报错。正确流程：
- 在
ets/下建SecondAbility.ts，类名为SecondAbility。 - 在
module.json5的abilities数组里加一项，name写SecondAbility，srcEntry指到文件路径。 - 如果要从别的 app 拉起它，
exported设true；否则false（更安全）。
代码实现
{ "name": "SecondAbility", "srcEntry": "./ets/secondability/SecondAbility.ts", "exported": false }漏了注册是最常见的"Ability 找不到"错误。记住：建 Ability 文件 ≠ 能用，必须在 json5 里登记。
权限怎么加才规范
权限分"普通"和"敏感"。敏感权限（如定位、通讯录）光在requestPermissions写还不够，运行时还要弹窗动态申请（下一篇讲）。这里先说配置：
核心代码
"requestPermissions": [ { "name": "ohos.permission.INTERNET", "reason": "$string:net_reason" }, { "name": "ohos.permission.LOCATION", "reason": "$string:loc_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } } ]reason是给用户看的申请理由，写清楚"为什么需要"，否则上架会被拒。when: "inuse"表示仅使用时申请；always表示安装/启动时。尽量用inuse，对用户更友好。
常见误区（小白必踩）
| 误区 | 说明 |
|---|---|
| 建了 Ability 不登记 | 只建.ts文件忘了在module.json5的abilities里注册，跳转直接报"找不到"。 |
exported乱设 | 能被外部拉起的设true，否则false更安全；设错可能桌面上找不到图标或被人乱拉起。 |
敏感权限不写reason | 上架会被拒，每个权限都要写清"为什么需要"。 |
下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲，改一改文末「动手改一改」里的参数，亲眼看看效果。
完整可运行示例：module.json5 真配置
这是「Ability 注册 + 权限声明」的最小可用配置。和代码一起看才完整。
完整示例
// entry/src/main/module.json5（节选关键字段） { "module": { "name": "entry", "type": "entry", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ts", "description": "$string:EntryAbility_desc", "icon": "$media:icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:startIcon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ], "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.CAMERA" } ] } }你会看到什么：这段配置注册了一个名为EntryAbility的入口，声明了桌面图标、启动窗口背景，并预申请了「联网」和「相机」两个权限。编译后，应用图标出现在桌面，且首次用到相机时会弹出系统授权框。
动手改一改：
- 删掉
requestPermissions里的INTERNET，再发起网络请求，观察报错——理解「声明即契约」。 - 把
exported改成false，其它应用将无法拉起这个 Ability。 - 在
abilities里复制一份并改名，体验「一个模块多个入口」。
写在最后
module.json5看着吓人，其实就是"登记册"：Ability 来登记一下，权限来登记一下。你只要记住建了 Ability 必须登记、敏感权限要写理由，基本不会再踩配置坑。
建议把你项目的 json5 打开，对着上面的表格逐项核对一遍——尤其exported和skills，这两处错一个，app 就可能起不来或桌面上找不到图标。
