目录

如何排查代码混淆导致功能异常问题以及常见报错案例

问题现象

本地调试debug包安装正常,但是使用release模式打包报错或使用release包安装测试有问题,具体表现包括但不限于以下几种场景:

背景知识

问题定位

排查功能异常步骤:

  1. 基于以下方式快速确定是否为混淆引起的异常:
    • 如果是以debug模式进行编译推包,说明该运行时异常不是由混淆引起的;
    • 如果是以release模式进行编译推包,可以在推包模块的build-profile.json5中,将enable设置为false则关闭混淆,执行clean,再次编译推包,如果运行时没问题,可以确定该异常是由混淆引起。
  2. 若确认是开启混淆后功能出现异常:
    • 混淆报错位置,通过混淆常见问题和报错栈还原进行排查具体报错位置。
    • 将报错位置配置白名单,配置白名单的主要场景为网络数据访问、json字段访问、动态属性访问、调用so库接口等不能混淆场景,需要使用-keep-property-name来保留指定的属性名称,可按照官方文档排查功能异常步骤来进行排查。
    • 根据ArkGuard混淆原理及功能修改混淆文件中配置,当存在多个混淆规则文件时,规则合并以及合并后的作用范围可参考混淆规则合并策略。
    • 若上述未排查出问题,怀疑文件损坏。排查如下路径内arkguard相关文件是否被更改:DevEco Studio > SDK > default > OpenHarmony > ets > build-tools > ets-loader > node_modules。

分析结论

修改建议

常见FAQ

Q:引入google-libphonenumber库导致crash怎么处理?

A:混淆会改变类名、方法名、变量名等,如果三方库依赖于某些特定的名字来工作,那么混淆后可能会导致这些依赖失效。关闭混淆,应用不再崩溃。

Q:打印日志如何设置阻断?

A:对于不同日志可使用以下方式:

Q:如何简化混淆配置过程?

A:HarmonyOS应用开发过程中,避免对特定类或方法进行混淆,开发者需要手动配置白名单规则。为了简化这一配置过程,建议开发者优先借助IDE的混淆助手来自动化处理部分配置工作,参考链接如下:通过混淆助手配置保留选项。

Q:debug包如何混淆?编译出来的hap包怎么查看是否混淆成功?

A:debug包不支持混淆,debug包以便于调试。只有release模式才能混淆。

在混淆结束后会生成中间产物,因此可以在编译产物build目录中找到混淆后的中间产物以查看混淆效果,同时可以找到混淆生成的名称映射表及系统API白名单文件。

Q:在不同源文件中,同样的写法new Object({[属性名]: 123}),查看编译后对应的文件,有的文件中的属性名会被混淆,有的属性名不会被混淆,这是什么原因呢?

属性userOftenAppData被混淆效果如下:

属性isFromChat未被混淆效果如下:

A:

  1. 首先在systemApiCache.json文件中排查未被混淆的属性是否与系统API重名,若与系统API重名,则不会被混淆。
  2. 其次确认未被混淆的属性名在项目中是否存在字符串字面量属性名,只要有一个字符串字面量属性名,那么所有的同名属性都不会被混淆。

Q:在main_pages.json文件里增加页面时会提示“A page configured in 'main_pages.json or build-profile.json5' must have one and only one '@Entry' decorator. ”。

A:main_pages.json文件中包含的页面都需要使用@Entry装饰器。对于未使用@Entry装饰器的页面,检查main_pages.json和工程级build-profile.json5文件中是否配置对应页面信息,有的话需要删除。

Q:新增一个模块提交代码到仓库,新建文件夹重新克隆仓库代码,编译报错,如图:

A:请排查其他模块级和项目级的build-profile.json5中是否存在混淆配置项,若不存在,建议新增模块的build-profile.json5中也删除obfuscation节点。

Q:应用打包时,APP包与HAP包的区别?

A:一个HarmonyOS工程的构建产物为APP包,APP包用于应用/服务发布上架应用市场,APP里编译的HAP包一般会比正常编HAP包小,编译APP包默认是非debug的,APP包里的HAP包是混淆过的,不包含调试信息;HAP是应用/服务可以独立运行在设备中的形态,也是应用安装的基本单位,在DevEco Studio工程目录中,一个HAP对应一个Module。应用打包时,每个Module生成一个.hap文件,一般编译HAP是debug模式,不会开启混淆,便于安装与调试。

Q:多模块引入中,需要保留HAR包中的选项,是否只需要在入口模块的obfuscation-rules.txt中配置保留选项?

A:是。

Q:多模块引入中,需要保留HAR包中的文件或者文件夹,此时相对路径filepath应该怎么填写?

A:filepath可以是文件或文件夹,若是文件夹,则文件夹下的文件及子文件夹中文件都不混淆。具体方式如下:

Q:开启混淆模式下,如何定位错误代码的具体行数?

A:在Release模式下,经过代码混淆的堆栈信息无法定位到源码的具体文件和行位置,不易于快速解决问题。针对该场景,DevEco Studio提供了Release模式下堆栈解析功能,利用Release模式下堆栈中的bundle路径,通过映射规则转换为具体的源码路径,从而提升解决问题的效率。

Release模式下堆栈解析功能操作方法如下:

  1. 单击菜单栏Code> Analyze Stack Trace。
  2. 在弹出的Analyze Stack Trace对话框中,粘贴应用的异常堆栈信息,单击OK。
  3. DevEco Studio将解析后的堆栈信息显示在底部的Stacktrace页签中,点击路径链接可快速定位到源码具体位置。