本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、文件概述

module.json5是鸿蒙应用的核心配置文件，位于模块的src/main/目录下，用于定义模块的基本信息、能力配置、设备兼容性等。它是HAP（Harmony Ability Package）打包和运行的基础。

二、核心配置项详解

1. 基础属性

{
  "module": {
    "name": "entry",                  // 模块名称（唯一，≤31字节，仅英文）
    "type": "entry",                  // 模块类型：entry/feature/har/shared
    "srcEntry": "./ets/entryability", // 代码路径（≤127字节）
    "description": "$string:module_desc", // 描述（支持资源引用）
    "mainElement": "EntryAbility",    // 入口Ability名称（≤255字节）
    "deviceTypes": ["phone", "tablet"], // 支持的设备类型（必填）
    "deliveryWithInstall": true,      // 是否随应用安装（true/false）
    "installationFree": false,        // 是否支持免安装特性
    "pages": "$profile:main_pages"    // 页面配置文件路径（UIAbility必填）
  }
}

注意：

• type为entry时表示主模块，feature表示动态特性模块
• installationFree需与原子化服务配置一致 

2. Ability配置

"abilities": [
  {
    "name": "EntryAbility",           // Ability名称（唯一）
    "srcEntry": "./ets/EntryAbility.ets", // 入口文件路径
    "launchType": "singleton",        // 启动模式：singleton/multiton/specified
    "icon": "$media:icon_app",        // 图标资源
    "label": "$string:app_name",      // 显示名称
    "startWindowIcon": "$media:icon", // 启动页图标
    "startWindowBackground": "$color:bg", // 启动页背景
    "exported": true,                 // 是否允许跨应用调用
    "skills": [                       // 定义Ability的能力
      {
        "entities": ["entity.system.home"],
        "actions": ["action.system.home"]
      }
    ]
  }
]

特殊场景：

• 配置"continueType": ["continueType1"]可支持任务续接 
• metadata字段可定义扩展元信息（如快捷方式） 

3. 权限配置

"requestPermissions": [               // 运行时申请的权限
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:reason",       // 申请原因（需资源文件定义）
    "usedScene": {
      "abilities": ["EntryAbility"],  // 使用该权限的Ability
      "when": "inuse"                 // 使用时机：always/inuse
    }
  }
],
"definePermissions": [                // 系统级权限定义（仅系统应用）
  {
    "name": "ohos.permission.PROVIDER",
    "grantMode": "system_grant",      // 授权方式：system_grant/user_grant
    "availableLevel": "normal"        // 权限级别：system_core/system_basic/normal
  }
]

4. 扩展配置

• 进程隔离：

  "process": "com.example.process",  // 自定义进程名（≤31字节）
  "isolationMode": "isolationFirst"   // 进程隔离策略

• 共享库依赖：

  "dependencies": [                   // 动态共享库HSP依赖
    {
      "bundleName": "com.shared.lib",
      "versionCode": 1
    }
  ]

• 原子化服务：

"atomicService": {                  // 原子化服务特有配置
  "preloads": [{
    "moduleName": "feature"
  }]
}

三、特殊标签说明

1. pages配置

• 必须使用$profile:前缀引用资源文件 
• 支持window子标签配置设计宽度（如"designWidth": 720） 
• 示例：

"pages": "$profile:main_pages",
// 对应的main_pages.json内容：
{
  "src": ["pages/index", "pages/detail"],
  "window": {
    "designWidth": 750,
    "autoDesignWidth": false
  }
}

2. metadata用途

• 配置分发过滤规则：

  "metadata": [{
    "name": "distributionFilter",
    "resource": "$profile:filter_config"
  }]

• 定义快捷方式（Shortcuts）：

  "metadata": [{
    "name": "ohos.ability.shortcuts",
    "resource": "$profile:shortcuts_config"
  }]

3. HSP模块配置

{
  "name": "sharedLib",
  "type": "shared",                  // 动态共享库类型
  "targetModuleName": "entry",       // 目标模块名（覆盖配置）
  "targetPriority": 50               // 优先级（1-100）
}

四、完整示例

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "process": "com.example.main",
    "mainElement": "MainAbility",
    "deviceTypes": ["phone", "tablet", "2in1"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/MainAbility.ets",
        "launchType": "singleton",
        "description": "$string:main_ability_desc",
        "icon": "$media:icon",
        "label": "$string:app_name",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:white",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts",
            "resource": "$profile:shortcuts"
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_reason",
        "usedScene": {
          "abilities": ["MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

五、注意事项

1. 命名规范：

   • name、mainElement等字段不支持中文 
   • 资源引用需使用$type:name格式（如$string:app_name） 

2. 版本兼容：

   • virtualMachine字段由IDE自动生成（如"ark2.0"） 
   • OpenHarmony 5.0+新增atomicService等标签 

3. 调试技巧：

   • 使用ohos test命令验证配置文件 
   • 设备类型需与app.json5中的bundleType匹配 

4. 常见错误：

   • 缺少pages配置会导致UIAbility无法启动 
   • installationFree与deliveryWithInstall冲突会引发安装失败