目录

ArkGuard字节码混淆开启指南

为了避免后续修改代码影响现网问题分析定位，建议开发者在版本发布时，本地备份build/default/cache/default/default@XXXCompileArkTS/esmodule/release/obfuscation 路径下的全部内容； 有条件的可以直接备份release目录。

字节码混淆开启步骤

[h2]约束与限制

字节码混淆与源码混淆功能无法同时启用，开启字节码混淆后，源码混淆功能将自动关闭。

[h2]开启混淆步骤

从API version 20开始，字节码混淆能力已在系统中集成，可通过以下方式在DevEco Studio开启使用。

[h2]三种混淆配置文件

下表简要总结了三种配置文件的差异：

配置文件（示例） 配置类型 是否可修改配置 是否影响本模块的混淆 是否影响其他模块的混淆
obfuscation-rules.txt 自定义 是 是 否
consumer-rules.txt 自定义 是 否 是
obfuscation.txt 编译产物 不涉及，构建HAR或HSP时自动生成。 不涉及 是

[h2]混淆选项配置指导

  1. 开启-enable-toplevel-obfuscation选项，如果代码中有globalThis访问全局变量，会出现访问失败的情况，需要使用-keep-global-name来保留此全局变量名称。

  2. 待上述选项开启成功后，开启-enable-property-obfuscation

    1. 若代码中存在静态定义、动态访问的情况或者动态定义、静态访问的情况，需要使用-keep-property-name保留属性名称。示例：

      // file.ts
// 静态定义，动态访问：属性名在对象定义时是静态的，但访问时通过动态构建属性名（通常使用字符串拼接）来访问
const obj001 = {
  staticName: 5  // 静态定义属性
};
const fieldName = 'static' + 'Name';  // 动态构建属性名
console.info(obj001[fieldName]);  // 使用方括号语法动态访问属性
      // file.ts
// 动态定义，静态访问：属性名通过动态表达式在对象定义时确定，但访问时直接使用点语法（假设开发者知道属性名的结果）
const obj002 = {
  ['dynamic' + 'Name']: 5  // 动态定义属性
};
console.info(obj002.dynamicName + ''); // 使用点语法静态访问属性

    2. 若代码中使用点语法访问未在ArkTS/TS/JS代码中定义的字段，比如访问native实现的so库，字段固定的json文件与数据库等场景：

      1. 若在代码中引用so库的API，如import testNapi from 'library.so'; testNapi.foo()；需要使用-keep-property-name foo来保留属性名称foo。
      2. 若在代码中使用json文件中的字段，需要使用-keep-property-name保留json文件中的字段名称。
      3. 若在代码中使用数据库相关的字段，需要使用-keep-property-name保留数据库中的字段名称。

    3. 若构建HAR模块并发布给其他模块使用的情况，要在HAR模块中的consumer-rules.txt文件中将不能被二次混淆的属性使用-keep-property-name保留。consumer-rules.txt文件在构建HAR时会生成obfuscation.txt文件。此HAR被其它模块依赖时，DevEco Studio会解析obfuscation.txt文件，读取文件中的白名单。

    4. 验证应用功能，排查遗漏的场景。若应用出现功能异常，可依据混淆后的报错栈，在模块的 build/default/[...]/release/obfuscation/ 目录下查阅 nameCache.json（名称映射表）、config.json（混淆项与白名单）等产物，按查看混淆效果对照定位源码行并排查白名单。确定需保留的名称后，使用-keep-property-name进行保留。

  3. 待上述选项应用适配成功后，开启-enable-export-obfuscation选项。此选项开启后以下场景需要适配：

    1. 若构建HSP模块，它会提供接口及其属性给其它模块调用，因此需要将对外接口使用-keep-global-name来保留、将对外暴露的class/interface等语法中的属性使用-keep-property-name保留。
    2. 若构建HAR模块并发布给其他模块使用的场景，要在HAR模块中的obfuscation-rules.txt文件中将对外接口使用-keep-global-name来保留、将对外暴露的class/interface等语法中的属性使用-keep-property-name保留。
    3. 若在代码中引用so库的API，如import { napiA } from 'library.so'；需要使用-keep-global-name napiA来保留so接口名称napiA。
    4. 验证应用功能以及模块被依赖时的接口调用功能，排查遗漏的场景。若应用出现功能异常，可依据混淆后的报错栈，在模块的 build/default/[...]/release/obfuscation/ 目录下查阅 nameCache.json（名称映射表）、config.json（混淆项与白名单）等产物，按查看混淆效果对照定位源码行；并按需使用-keep-global-name、-keep-property-name等进行保留。

  4. 待上述选项应用适配成功后，开启-enable-filename-obfuscation选项。此选项开启后以下场景需要适配：

    1. 若代码中有动态import语句，如const path = './filePath'; import (path)，会出现文件引用失败的情况，需要使用-keep-file-name filePath来保留这个文件名。
    2. 若应用中有描述路由表信息的routerMap配置，其中的pageSourceFile字段标记页面在模块的路径，需要使用-keep-file-name来保留这个路径。
    3. 若代码中有传入ohmUrl进行页面跳转，如router.pushUrl({url: '@bundle:com.example.routerPage/Library/Index'})，使用-keep-file-name来保留这个路径。
    4. 验证应用功能，排查遗漏的场景。若应用出现功能异常，且报错栈中的路径为混淆后的路径，可以在模块中的build/default/[...]/release/obfuscation/nameCache.json文件中查询到原始路径，进而找到源码文件。另外，插件hstack支持自动还原混淆后的报错栈。在定位到需要保留的路径后，使用-keep-file-name来保留此路径。

说明

查看混淆效果

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

报错栈还原

经过混淆的应用程序中代码名称会发生更改，crash时打印的报错栈更难以理解，因为报错栈与源码不完全一致。开发人员可使用DevEco Studio命令工具Command Line Tools中的hstack插件来还原源码堆栈，进而分析问题。

反混淆工具需要使用应用编译过程中生成的sourceMaps.json文件以及混淆名称映射文件nameCache.json文件，因此请本地备份它们；为方便问题定位，建议备份release目录。