HarmonyOS7 module.json5 配置全解：Ability 注册与权限

文章目录

• • 前言
  • 文件长什么样
  • 逐字段讲解
  • [注册一个新 Ability 的正确步骤](#注册一个新 Ability 的正确步骤)
  • • 代码实现
  • 权限怎么加才规范
  • • 核心代码
  • 常见误区（小白必踩）
  • [完整可运行示例：module.json5 真配置](#完整可运行示例：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 的正确步骤

我踩过"只建了文件却忘了注册"的坑，结果跳转直接报错。正确流程：

1. 在 ets/ 下建 SecondAbility.ts，类名为 SecondAbility。
2. 在 module.json5 的 abilities 数组里加一项，name 写 SecondAbility，srcEntry 指到文件路径。
3. 如果要从别的 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 就可能起不来或桌面上找不到图标。