!22241 bm工具安装失败说明文档

Merge pull request !22241 from jiangminsen/master

zh-cn/application-dev/tools/bm-tool.md

@@ -326,3 +326,243 @@ bm dump-shared -n com.ohos.lib
 # 显示指定应用指定模块依赖的共享库信息
 bm dump-dependencies -n com.ohos.app -m entry
 ```
+
+## 常见问题
+
+### 安装HAP时提示“code:9568320 error: no signature file”
+**问题现象**
+
+对HAP包签名后，在设备中运行HAP时提示“failed to install bundle. error: install no signature info”或“failed to install bundle. error: no signature file”。
+
+![示例图](figures/zh-cn_image_0000001389116960.png)
+
+**解决措施**
+
+该问题是由于签名工具与设备运行的镜像版本不匹配导致，需要开发者手动更新设备的镜像，可参考如下步骤进行更新。
+1. 获取[OpenHarmony 最新镜像文件](https://gitee.com/openharmony/docs/blob/master/zh-cn/release-notes/Readme.md)，下载对应开发板的镜像文件。
+2. 将下载的镜像文件烧录到开发板中，关于各开发板的烧录，可以使用DevEco Device Tool工具进行烧录，具体请参考[DevEco Device Tool使用指南](../../device-dev/quick-start/quickstart-ide-env-win.md)。
+3. 重新运行应用/服务。
+
+### 安装HAP时提示“code:9568347 error: install parse native so failed”错误
+**问题现象**
+
+在启动调试或运行C++应用/服务时，安装HAP出现错误，提示“error: install parse native so failed”错误信息。
+
+**解决措施**
+
+该问题可能是由于设备支持的Abi类型与C++工程中配置的Abi类型不匹配，请通过如下步骤进行解决。
+
+1. 将设备与DevEco Studio进行连接。
+2. 打开命令行工具，并进入SDK安装目录下的toolchains\{版本号}目录下。
+    ```
+    若不清楚OpenHarmony SDK安装目录，可单击File > Settings > SDK界面查看安装路径。
+    ```
+3. 执行如下命令，查询设备支持的Abi列表，返回结果为default/armeabi-v7a/armeabi/arm64-v8a/x86/x86_64中的一个或多个Abi类型。
+    ```
+    hdc shell
+    param get const.product.cpu.abilist
+    ```
+4. 根据查询返回结果，检查[模块级build-profile.json5](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/build_config-0000001052902431-V3#section6887184182020)文件中的“abiFilters”参数中的配置，规则如下：
+    * 若返回结果为default，请执行如下命令，查询是否存在lib64文件夹。
+      ```
+      cd /system/
+      ls
+      ```
+      ![示例图](figures/zh-cn_image_0000001609001262.png)
+      * 存在lib64文件夹：则“abiFilters”参数中需要包含arm64-v8a类型。
+      * 不存在lib64文件夹：则“abiFilters”参数中需要至少包含armeabi/armeabi-v7a中的一个类型。
+    * 若返回结果为armeabi-v7a/armeabi/arm64-v8a/x86/x86_64中的一个或多个，需要在“abiFilters”参数中至少包含返回结果中的一个Abi类型。
+
+### 安装HAP时提示“code:9568344 error: install parse profile prop check error”错误
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install parse profile prop check error”错误信息。
+
+![示例图](figures/zh-cn_image_0000001585361412.png)
+
+**解决措施**
+
+该问题可能是由于应用使用了应用特权，但应用的签名文件发生变化后未将新的签名指纹重新配置到设备的特权管控白名单文件install_list_capability.json中，请通过如下步骤进行解决。
+
+1. 获取新的签名指纹。
+
+    a. 在项目级build-profile.json5文件中，signingConfigs字段内的profile的值即为签名文件的存储路径。
+
+    b. 打开该签名文件（后缀为.p7b），打开后在文件内搜索“development-certificate”，将“-----BEGIN CERTIFICATE-----”和“-----END CERTIFICATE-----”以及中间的信息拷贝到新的文本中，注意换行并去掉换行符，保存为一个新的.cer文件，如命名为xxx.cer。
+
+    新的.cer文件格式如下图（仅作为格式示意，内容以实际为准）：
+
+    ![示例图](figures/zh-cn_image_0000001585521364.png)
+
+
+
+    c. 使用keytool工具（在DevEco Studio安装目录下的jbr/bin文件夹内），执行如下命令通过.cer文件获取证书指纹的SHA256值。
+      ```
+      keytool -printcert -file xxx.cer
+      ```
+    d. 将证书指纹中SHA256的内容去掉冒号，即为最终要获得的签名指纹。
+    
+    如SHA256值为下图（仅作为格式示意，内容以实际为准）：
+    ![示例图](figures/zh-cn_image_0000001635921233.png)
+
+    去掉冒号后的签名指纹为：5753DDBC1A8EF88A62058A9FC4B6AFAFC1C5D8D1A1B86FB3532739B625F8F3DB
+
+2. 获取设备的特权管控白名单文件install_list_capability.json。
+
+    a. 连接设备。
+
+    b. 执行如下命令查看设备的特权管控白名单文件install_list_capability.json。
+    ```
+    find /system -name install_list_capability.json
+    ```
+    HarmonyOS设备上install_list_capability.json的位置通常为以下几种，选取其中一个即可：
+    ```
+    /system/variant/phone/base/etc/app/install_list_capability.json
+    /system/etc/app/install_list_capability.json
+    ```
+    OpenHarmony设备上install_list_capability.json的位置通常为：
+    ```
+    /system/etc/app/install_list_capability.json
+    ```
+    c. 执行如下命令拉取install_list_capability.json。
+    ```
+    hdc shell mount -o rw,remount /
+    hdc file recv /system/variant/phone/base/etc/app/install_list_capability.json
+    ```
+
+3. 将步骤1获取到的签名指纹配置到install_list_capability.json文件的app_signature中，注意要配置到对应的bundleName下。
+![示例图](figures/zh-cn_image_0000001635641893.png)
+4. 将修改后的install_list_capability.json文件重新推到设备上，并重启设备。
+
+    ```
+    hdc shell mount -o rw,remount / 
+    hdc file send install_list_capability.json /system/variant/phone/base/etc/app/install_list_capability.json 
+    hdc shell chmod 777 /system/variant/phone/base/etc/app/install_list_capability.json 
+    hdc shell reboot
+    ```
+5. 设备重启后，重新安装新的应用即可。
+
+### 安装HAP时提示“code:9568305 error: dependent module does not exist”错误
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: dependent module does not exist”错误信息。
+
+![示例图](figures/zh-cn_image_0000001560338986.png)
+
+**解决措施**
+
+该问题是由于运行/调试的应用依赖的动态共享包（SharedLibrary）模块未安装导致安装报错，您可以通过如下方式进行解决：
+
+* 先安装依赖的动态共享包（SharedLibrary）模块，再在应用运行配置页勾选Keep Application Data，点击OK保存配置，再运行/调试。
+![示例图](figures/zh-cn_image_0000001560201786.png)
+
+* 在运行配置页，选择Deploy Multi Hap标签页，勾选Deploy Multi Hap Packages，选择依赖的模块，点击OK保存配置，再进行运行/调试。
+![示例图](figures/zh-cn_image_0000001610761941.png)
+
+### 安装HAP时提示“code:9568259 error: install parse profile missing prop”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install parse profile missing prop”错误信息。
+
+![示例图](figures/zh-cn_image_0000001559130596.png)
+
+**解决措施**
+
+出现该问题的原因是配置文件app.json5和module.json5中必填字段缺失。
+
+* 方法1：请参考[app.json5配置文件](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/app-configuration-file-0000001558277229-V3)和[module.json5配置文件](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/module-configuration-file-0000001506957668-V3)查看并补充必填字段。
+* 方法2：通过hilog日志判断缺失字段。
+
+    开启落盘命令：
+    ```
+    hilog -w start
+    ```
+
+    落盘位置：/data/log/hilog
+
+    打开日志查看“profile prop %{public}s is mission”。如“profile prop icon is mission”表示“icon”字段缺失。
+
+### 安装HAP时提示“code:9568258 error: install releaseType target not same”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install releaseType target not same”错误信息。
+
+![示例图](figures/zh-cn_image_0000001609976041.png)
+
+**解决措施**
+
+出现该问题的原因是设备上已安装的旧HAP和现在要安装的新HAP所使用的SDK中的releaseType值不一样。请先卸载设备上已安装的HAP，再安装新的HAP。
+
+### 安装HAP时提示“code:9568322 error: signature verification failed due to not trusted app source”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: signature verification failed due to not trusted app source”错误信息。
+
+![示例图](figures/zh-cn_image_0000001585042216.png)
+
+**解决措施**
+
+该问题是由于签名中未包含该调试设备的UDID，请通过如下步骤进行解决。
+
+* 使用[自动签名](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/signing-0000001587684945-V3#section18815157237)。在连接设备后，重新为应用进行签名。
+* 如果使用的是手动签名，对于HarmonyOS应用，请在AppGallery Connect中先将该调试设备[注册调试设备](https://developer.huawei.com/consumer/cn/doc/distribution/app/agc-help-harmonyos-debugapp-manual-0000001177608893#section7732152932911)并在[申请Profile文件](https://developer.huawei.com/consumer/cn/doc/distribution/app/agc-help-harmonyos-debugapp-manual-0000001177608893?ha_linker=eyJ0cyI6MTY4NzkzNDEzOTk1OSwiaWQiOiJhZjdhYzI0MDlkMGQ5MzQ1MzFlNDE3NDQ5MmY4MjJkMyJ9#section1774717395304)选择设备时添加该调试设备，重新申请Profile证书；对于OpenHarmony应用，请参考[OpenHarmony应用手动签名](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/hapsigntool-guidelines.md)，在UnsgnedDebugProfileTemplate.json文件中添加该调试设备的[UDID](https://developer.huawei.com/consumer/cn/doc/distribution/app/agc-help-harmonyos-debugapp-manual-0000001177608893#section1835412326017)。
+
+### 安装HAP时提示“code:9568289 error: install failed due to grant request permissions failed”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install failed due to grant request permissions failed”错误信息。
+
+![示例图](figures/zh-cn_image_0000001585201996.png)
+
+**解决措施**
+
+该问题是由于默认应用等级为normal，只能使用normal等级的权限，如果使用了system_basic或system_core等级的权限，将导致报错。
+
+对于HarmonyOS应用，请参考[使用ACL签名配置指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/signing-0000001587684945-V3?catalogVersion=V3#section157591551175916)完成ACL提权；对于OpenHarmony应用，请参考[修改应用权限等级](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-auto-configuring-signature-information-0000001271659465#section42735161005)修改签名模板。
+
+### 安装HAP时提示“code:9568297 error: install failed due to older sdk version in the device”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install failed due to older sdk version in the device”错误信息。
+
+![示例图](figures/zh-cn_image_0000001635521909.png)
+
+**解决措施**
+
+该问题是由于编译打包所使用的SDK版本与设备镜像版本不匹配。不匹配的场景包括：
+
+* 场景一：设备上的镜像版本低于编译打包的SDK版本，请更新设备镜像版本。查询设备镜像版本命令：
+  ```
+  hdc shell param get const.ohos.apiversion
+  ```
+  如果镜像提供的api版本为10，且应用编译所使用的SDK版本也为10，仍出现该报错，可能是由于镜像版本较低，未兼容新版本SDK校验规则，请将镜像版本更新为最新版本。
+
+* 场景二：对于需要运行在OpenHarmony设备上的应用，请确认runtimeOS已改为OpenHarmony。
+
+### 安装HAP时提示“code:9568332 error: install sign info inconsistent”
+**问题现象**
+
+在启动调试或运行应用/服务时，安装HAP出现错误，提示“error: install sign info inconsistent”错误信息。
+
+![示例图](figures/zh-cn_image_0000001635761329.png)
+
+**解决措施**
+
+该问题是由于设备上已安装的应用与新安装的应用中签名不一致。如果在**Edit Configurations**中勾选了“Keep Application Data”（不卸载应用，覆盖安装），并且重新进行了签名，将导致该报错。
+
+请卸载设备上已安装的应用，或取消勾选“Keep Application Data”后，重新安装新的应用。
+
+### 安装HAP时提示“code:9568257 error: fail to verify pkcs7 file”
+**问题现象**
+
+在启动调试或者运行应用/服务时，安装HAP出现错误，提示”error: fail to verify pkcs7 file“错误信息。
+
+![示例图](figures/zh-cn_image_00000016359212344.png)
+
+**解决措施**
+
+出现该问题的原因是应用当前使用的签名不符合HarmonyOS应用签名的要求。通常是由于当前使用的是OpenHarmony应用的签名，需替换为HarmonyOS应用的签名。
+
+请在[为应用/服务签名](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/signing-0000001587684945-V3)时勾选”Support HarmonyOS“，完成HarmonyOS应用签名后再次启动调试或者运行应用。
+
+![示例图](figures/zh-cn_image_00000016359212311.png)
\ No newline at end of file