鸿蒙应用配置权威指南：包名、图标、版本与权限实战原创

ft9938596

发布于 2025-6-18 08:54

浏览

0收藏

作为鸿蒙开发的基础必修课，正确配置应用的包名、图标、版本和权限是确保应用上架和运行的关键。

一、包名配置的核心规则

1.1 命名规范与原则

包名作为应用的唯一标识符，必须遵循反向域名命名法，具体要求：

格式要求：由小写字母、数字和点号组成，如com.huawei.harmony.app
长度限制：不超过255个字符，建议控制在64字符以内
唯一性：需在华为开发者联盟控制台提前查询可用性

1.2 多模块包名策略

在多模块项目中，建议采用层级化包名结构：

com.example.harmonyapp         # 主模块包名
com.example.harmonyapp.feature1 # 功能模块1
com.example.harmonyapp.feature2 # 功能模块2

1.3 配置示例

{
  "app": {
    "bundleName": "com.example.myharmonyapp",
    "vendor": "ExampleTech",
    "version": {
      "name": "1.0.5",
      "code": 105
    }
  }
}

二、视觉标识配置深度解析

2.1 图标配置体系

鸿蒙应用图标需提供多尺寸适配，标准尺寸包括：

48px × 48px（小尺寸）
72px × 72px（中等尺寸）
96px × 96px（大尺寸）
192px × 192px（ launcher 图标）

2.2 动态图标配置

支持根据设备主题动态切换图标：

{
  "app": {
    "icon": {
      "light": "$media:icon_light",
      "dark": "$media:icon_dark"
    },
    "label": "$string:app_name"
  }
}

2.3 标签国际化配置

在resources/base/strings/strings.json中定义多语言标签：

{
  "app_name": "我的应用",
  "app_name_en": "My Harmony App"
}

通过$string:app_name引用默认语言，$string:app_name_en引用英文标签

三、版本声明与设备适配

3.1 版本号规范

采用三段式版本号+数字版本码：

主版本号.次版本号.修订号（如1.2.3）
版本码为数字，用于程序内部识别（如123）

3.2 设备类型声明

在config.json中声明支持的设备类型：

{
  "deviceType": [
    "phone",
    "tablet",
    "wearable",
    "tv"
  ]
}

各设备类型对应能力差异需在开发中特别处理

四、权限配置与安全实践

4.1 权限分类与申请

鸿蒙权限分为四类：

普通权限：系统自动授予，如网络访问
危险权限：需要用户明确授权，如位置信息
系统权限：需系统签名，如底层硬件访问
特殊权限：如通知栏访问

4.2 危险权限申请流程

在config.json中声明：

{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.ACCESS_FINE_LOCATION",
        "reason": "$string:permission_location_usage",
        "usedScene": {
          "ability": [
            "com.example.ability.MapAbility"
          ],
          "when": "inUse"
        }
      }
    ]
  }
}

运行时动态申请：

import featureAbility from '@ohos.ability.featureAbility';
import permission from '@ohos.permission';

async function requestLocationPermission() {
  const context = featureAbility.getCurrentAbility().getContext();
  const result = await permission.requestPermissionsFromUser(
    context,
    ['ohos.permission.ACCESS_FINE_LOCATION']
  );
  if (result[0].granted) {
    // 权限已授予
  } else {
    // 处理权限拒绝
  }
}

4.3 权限最佳实践

最小权限原则：仅申请必要权限
分级申请：核心功能优先申请，辅助功能延迟申请
权限说明：在reason字段清晰说明权限用途
异常处理：处理权限申请失败和用户拒绝场景

五、完整配置文件示例

{
  "app": {
    "bundleName": "com.example.harmonyapp",
    "vendor": "ExampleInc",
    "version": {
      "name": "2.1.0",
      "code": 210
    },
    "label": "$string:app_name",
    "icon": {
      "light": "$media:icon_light",
      "dark": "$media:icon_dark"
    }
  },
  "deviceType": [
    "phone",
    "tablet",
    "car"
  ],
  "module": {
    "package": "com.example.harmonyapp.entry",
    "name": ".MainAbility",
    "reqPermissions": [
      {
        "name": "ohos.permission.READ_USER_STORAGE",
        "reason": "$string:permission_storage_read",
        "usedScene": {
          "ability": [
            "com.example.ability.MediaAbility"
          ],
          "when": "inUse"
        }
      },
      {
        "name": "ohos.permission.ACCESS_NETWORK_STATE",
        "reason": "$string:permission_network"
      }
    ]
  }
}

六、配置常见问题与解决方案

问题现象	可能原因	解决方案
应用安装失败	包名已存在	更换包名或在控制台查询可用性
图标显示异常	尺寸不规范或路径错误	检查图标尺寸和资源路径
权限申请失败	配置文件未声明或签名错误	确认权限声明和应用签名正确
多设备适配问题	deviceType配置不当	根据设备能力调整配置