Stage模型配置踩坑：bundleName、权限与图标优先级解析

鸿蒙专家

在 HarmonyOS Stage 模型开发中，配置文件往往是新手最容易翻车的地方。
应用级配置集中在 AppScope/app.json5，模块级配置在 entry/src/main/module.json5，两者分工不同但存在交叉，搞混了就会导致图标不显示、应用名显示为包名、权限弹窗不弹出等问题。本文结合真实项目经验，梳理几个关键配置项的注意事项。

bundleName：应用身份证，发布前务必确认

app.json5 中的 bundleName 是系统唯一标识，采用反域名命名（如 com.example.demo），至少三段、每段只能英文数字下划线、首段字母开头、长度 7-128 字节。

2. {
3.   "app": {
4.     "bundleName": "com.zyl.ounting",
5.     "vendor": "example",
6.     "versionCode": 1000001,
7.     "versionName": "1.0.1"
8.   }
9. }

复制代码

发布后无法修改，上线前必须签字确认。常见错误包括连续点号、首段数字开头、不足三段等。另外 bundleName 还影响沙箱路径和数据隔离，同厂商应用建议共用二级域名前缀以便跨应用数据共享。

bundleType 默认值为 "app"，若开发元服务需显式配置为 "atomicService"，否则编译或上架会报错。API 19 新增 "appPlugin" 类型用于插件包，普通三方暂不需要。

图标和 label：优先级规则易混淆

DevEco Studio 5.0.3.800 之后，module.json5 中的 icon/label 不再强制配置。生效优先级如下：
- 有入口 UIAbility 时：先找 mainElement 指向的 UIAbility 配置 → 再找 module.json5 里第一个入口 UIAbility → 最后用 app.json5 的值。
- 无入口 UIAbility 时：直接使用 app.json5。

推荐做法：只在 app.json5 中配置 icon/label，模块不重复配，逻辑最清晰。若需桌面显示多个入口图标，则在 module.json5 中为每个 UIAbility 分别配置并添加 skills 中的 home 相关字段。

入口 UIAbility 的判断标准是 skills 中同时包含 "entity.system.home" 和 "ohos.want.action.home"，缺一不可。

资源引用注意：AppScope 目录下的资源会合入模块目录，若文件名重复则 AppScope 覆盖模块。定制模块图标时不要与 AppScope 资源重名。分层图标前景/背景图需放在 media 目录，并在 layered_image.json 中引用。

版本号：编码有门道

versionCode 是 32 位非负整数，推荐用分段编码（如 1000001 表示 1.0.1），便于迭代追溯。不推荐用时间戳，同一天多个 hotfix 易冲突。

versionName 展示给用户，推荐三段式 "A.B.C" 或四段式，长度不超过 127 字节。注意只能包含数字、字母、下划线、点号和花括号，不能出现 "-beta" 等字母，可通过 versionCode 奇偶区分 debug/release。

API 23 新增 buildVersion，用于 CI/CD 构建标识，与 versionName 维度不同。buildVersion 只能用数字和点号，最长 18 字节，不可相邻点号或以点号开头结尾。

deviceTypes：多 Module 的兼容性陷阱

在 module.json5 中指定模块支持的设备类型，如 ["phone","tablet"]。多 Module 工程下，所有模块的 deviceTypes 交集必须包含目标设备，否则安装报错 INSTALL_FAILED_INVALID_DEVICE_TYPE。建议所有模块配同一套设备类型。

注意 "default" 类型仅供调试或系统应用使用，不支持上架。

requiredDeviceFeatures 字段从 API 19 新增，声明必须的设备特性（如 camera:true），市场据此做设备分发过滤。

权限声明：区分 system_grant 与 user_grant

system_grant（如 INTERNET）只需声明 name，安装时自动授予。user_grant（如 LOCATION、CAMERA）必须提供 reason 和 usedScene。

2. {
3.   "name": "ohos.permission.LOCATION",
4.   "reason": "$string:permission_location_reason",
5.   "usedScene": {
6.     "abilities": ["EntryAbility"],
7.     "when": "inuse"
8.   }
9. }

复制代码

reason 使用字符串资源索引，且必须多语种，描述需具体明确（如“用于在地图上显示位置以便推荐餐厅”）。when 可选 "inuse" 或 "always"，非后台必要请用 "inuse"，否则审核严格。

多 HAP 场景下：entry 已声明的权限可在全应用共用；feature 单独声明的权限仅在该模块运行时生效。若 entry 和 feature 声明同一权限且 reason 不一致，以 entry 为准。

minAPIVersion 与 targetAPIVersion

这两个字段在 app.json5 中配置无效，实际需在 build-profile.json5 中设置 compatibleSdkVersion 和 targetSdkVersion。若 targetAPIVersion 过低，运行时访问新 API 可能抛异常；过高则需在代码中做兼容判断。

总结：Stage 模型配置文件看似简单，实则细节众多。建议新建项目时逐字段核对，特别是 bundleName 和权限声明，避免上线后返工。

热心网友1

感谢楼主的详细梳理！我最近正好在调 Stage 模型的配置文件，踩了图标不显示的坑，原来是因为在 module.json5 和 app.json5 里重复配了 icon/label，而且资源名冲突了。按你说的只配在 app.json5 里果然清爽多了。 bundleName 那段也提醒得及时，反域名命名确实容易漏掉下划线限制，我差点把首段写成数字。还有权限的 reason 必须多语种这个细节，之前没注意直接写了个中文字符串，差点上架被拒。 楼主总结得很到位，尤其是多 Module 下 deviceTypes 取交集这个陷阱，我之前的项目就是因为 feature 模块漏了 tablet 导致平板安装失败。收藏了，下次建项目就对照着核一遍。

热心网友1

楼主的总结非常到位，尤其是图标优先级那块，之前我确实踩过“模块配了icon但桌面不显示”的坑，后来才发现是skills里忘了同时加entity和action。权限reason用字符串资源引用也是容易被忽略的点，很多新手直接写中文字符串，上架审核就挂了。 另外关于versionCode分段编码，建议新手也注意一下位数，32位最大是21亿左右，如果团队发布频繁，最好留足余量，避免未来溢出。感谢分享，收藏了！

热心网友1

感谢楼主分享这么详细的 Stage 模型配置经验，特别是 bundleName 的命名规则和发布后不可修改的提醒，对新手非常实用。图标和 label 的优先级说明也很清晰，我之前就遇到过桌面不显示应用名的问题，现在回头看应该是 module.json5 配置冲突了。权限声明的 reason 多语种要求和 usedScene 的“inuse”推荐也很关键，这部分容易被忽略。整体非常有帮助，收藏了。