目录

真机安装HAP包失败故障排查

报9568263错误：版本降级安装失败

[h2]问题现象

报9568263错误。

在HarmonyOS 开发者中心中配置了真机的udid，并应用了更新后的p7b文件、证书文件进行sign后重新打包，使用hdc命令始终无法安装新HAP包。其他机器均正常安装。

运行命令hdc install xxx.hap的报错信息如下：

[Info]App install path:xxx.hap, queuesize:0, msg:error: failed to install bundle. code:9568263 error: install version downgrade.

[h2]定位过程

查看日志返回的错误信息code:9568263 error: install version downgrade。正在安装的应用的版本号versionCode小于系统已安装的该应用的版本号。

[h2]分析结论

由报错信息可以看到是待安装应用的版本号小于已安装的同应用的版本号。卸载旧版本重新安装即可。

[h2]修改建议

报9568283错误：API版本不兼容

[h2]问题现象

报9568283错误。

先安装老包，修改build-profile.json5中的API版本后，再安装新包，报错如下：

Install Failed: error: failed to install bundle.
code:9568283.
error: install releaseType compatible not same.

[h2]定位过程

检查修改API版本前后的两个包对应的打包产物的versionCode、apiReleaseType、minAPIVersion、targetAPIVersion的一致性。打包产物查看路径：工程目录build/default/outputs/default/，找到对应.hap包后，打开module.json文件可核对相关字段。

[h2]分析结论

由于只修改了API版本号，两个版本的versionCode相同，但apiReleaseType、minAPIVersion、targetAPIVersion两个产物中的值不都分别一致，导致报错。

[h2]修改建议

修改app.json5中的versionCode值，使新包中的值大于老包中的值。

多入口ability导致运行报错

[h2]问题现象

项目配置了多个入口ability，运行项目报错，错误信息如下图：

[h2]定位过程

  1. 检查项目中各个模块的module.json5是否配置了skills字段，配置了该字段则表示该模块为入口ability。确认项目的正确入口ability是哪个，一个项目只需要一个主入口即可。
  2. 检查IDE运行项目时的命令是否正确，如：hdc shell aa start -a EntryAbility -b com.example.myapplication中的入口模块EntryAbility是否与项目主入口ability相同。

[h2]分析结论

由于项目配置了多个入口ability，IDE运行项目时的默认入口ability错误，导致项目运行时启动报错。

[h2]修改建议

报9568320错误：缺少签名文件

[h2]问题现象

运行项目出现如下报错信息。

Install Failed: error: failed to install bundle.
code:9568320.
error: no signature file.

根据错误码9568320提供的处理方案无法解决问题。

[h2]定位过程

检查工程级build-profile.json5文件中配置是否正确，是否缺少字段。

[h2]分析结论

工程级build-profile.json5文件的products配置项中缺少signingConfig字段。

[h2]修改建议

在工程级build-profile.json5文件的products配置项中增加signingConfig字段的配置信息，例如："signingConfig": "default"。

修改包名后安装失败

[h2]问题现象

项目修改包名后安装失败，报错信息如下：

hvigor ERROR: Failed :entry:default@SignHap...
hvigor ERROR: BundleName in the project configuration does not match that in the SigningConfigs.
Detail: Open the project-level build-profile.json5 file. Change the bundleName value.
to that in the SigningConfigs. Otherwise, go to the app.json5 file and change the bundleName value there.
at /Users/hmn/Desktop/xxx/ztyhm/build-profile.json5.
hvigor ERROR: BUILD FAILED in 18 s 719 ms.

[h2]定位过程

根据报错提示"BundleName in the project configuration does not match that in the SigningConfigs."可知：修改包名后需要同步修改签名信息。

[h2]分析结论

修改包名后，需要同步修改签名信息。

[h2]修改建议

在工程级build-profile.json5中把signingConfigs属性值删除，同步信息后重新签名。

多设备部署卸载重装报错

[h2]问题现象

多设备部署时选择卸载重装，实际卸载的设备与预期不一致，且部分设备重新安装时报9568263错误。

[h2]定位过程

DevEco Studio在部署应用时，检测到设备上已存在相同bundleName的应用包，会执行卸载命令hdc uninstall <包名>。第一个设备上已存在与正在安装应用bundleName相同的应用，因此执行了卸载操作。第二个设备也执行了卸载操作，但已安装应用的VersionCode大于正在安装应用的VersionCode，导致重新安装时报9568263错误。

[h2]分析结论

多设备部署时，DevEco Studio会对每个检测到相同bundleName应用的设备执行卸载操作。当某设备上已安装应用的VersionCode高于正在安装应用的VersionCode时，卸载后重新安装会报9568263错误。

[h2]修改建议