xref: /arkcompiler/ets_frontend/arkguard/README-cn.md

# Arkguard
Arkguard 是Javascript和Typescript的源码混淆工具。

# 在DevEco Studio中的用法
Arkguard已经被集成了到SDK中。可以在DevEco Studio中很方便地使用。Arkguard只能用于Stage模型
(不支持FA模型)。目前Arkguard只提供名称混淆的能力(因为其它混淆能力会劣化性能)。
使用Arkguard可以混淆以下名称:
* 参数名和局部变量名
* 顶层作用域的名称
* 属性名称

Arkguard默认使能对参数名和局部变量名的混淆。顶层作用域名称和属性名称的混淆是默认关闭的，
因为默认打开可能会导致运行时错误。你可以通过[混淆选项](#混淆选项)来开启它们。

创建一个新工程的时候，配置文件`build-profile.json5`中会自动生成以下内容:
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
  }
}
```
创建一个新的library的时候，还会额外生成`consumerFiles`属性:
```
"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["obfuscation-rules.txt"],
    }
    "consumerFiles": ["consumer-rules.txt"]
  }
}
```

要想开启混淆，需要满足下面的条件:
* 属性`ruleOptions.enable`的值为`true`，并且所有依赖的library的`ruleOptions.enable`属性是`true`
* 在release模式构建

属性`ruleOptions.files`中指定的混淆配置文件会在构建HAP或HAR的时候被应用。

属性`consumerFiles`中指定的混淆配置文件会在构建依赖这个library的工程或library时被应用。
这些混淆配置文件的内容还会被合并到HAR包中的`obfuscation.txt`文件。

当构建HAP或者HAR的时候，最终的混淆规则是自身的`ruleOptions.files`属性，依赖的library的`consumerFiles`属性，
以及依赖的HAR包中的`obfuscation.txt`文件的合并。如果构建的是HAR，`obfuscation.txt`是自身的`consumerFiles`属性，
依赖的library的`consumerFiles`属性，以及依赖的HAR包中的`obfuscation.txt`文件的合并。
构建HAP不会生成`obfuscation.txt`。详细合并的策略可以查看[混淆规则合并策略](#混淆规则合并策略)。

## 配置混淆规则
在创建工程或library的时候，DevEco Studio会自动生成`obfuscation-rules.txt`和`consumer-rules.txt`文件，
但是它们默认不会包含任何混淆规则。你可以在这些文件中写混淆规则，或者也可以将规则写在其它文件，
然后将文件路径放到`ruleOptions.files`和`consumerFiles`中，如下面的例子所示。
```
"buildOption": {
  "arkOptions": {
    "obfuscation": {
      "ruleOptions": {
        "enable": true,
        "files": ["obfuscation-rules.txt", "myrules.txt"],
      }
      "consumerFiles": ["consumer-rules.txt", "my-consumer-rules.txt"]
    }
  }
}
```

在混淆规则文件中，你可以写[混淆选项](#混淆选项)和[保留选项](#保留选项)。

### 混淆选项

`-disable-obfuscation`

关闭所有混淆。如果你使用这个选项，那么构建出来的HAR或HAR将不会被混淆。默认情况下，
Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随机的短名字)。

`-enable-property-obfuscation`

开启属性混淆。 如果你使用这个选项，那么所有的属性名都会被混淆，除了下面场景:
* 被`import/export`的类或对象的属性名不会被混淆。注意: 只有直接导出的类或对象的属性名不会被混淆。
比如下面例子中的属性名`data`不会被混淆。
    ```
    export class MyClass {
       data: string;
    }
    ```
对于间接导出的场景，比如`export MyClass`和`let a = MyClass; export a;`，如果你不想混淆它们的属性名，
那么你需要使用[保留选项](#保留选项)来保留这些属性名。另外，对于直接导出的类或对象的属性的属性名，比如下面例子中的`name`和`age`, 如果你不想混淆它们，那么你也需要使用[保留选项](#保留选项)来保留这些属性名。
    ```
    export class MyClass {
       person = {name: "123", age: 100};
    }
    ```
* ArkUI组件中的属性名不会被混淆。比如下面例子中的`message`和`data`不会被混淆。
    ```
    @Component struct MyExample {
        @State message: string = "hello";
        data: number[] = [];
        ...
    }
    ```
* 被[保留选项](#保留选项)指定的属性名不会被混淆。
* 系统API列表中的属性名不会被混淆。系统API列表是构建时从SDK中自动提取出来的一个名称列表。
* 字符串字面量属性名不会被混淆。比如下面例子中的`"name"`和`"age"`不会被混淆。
    ```
    let person = {"name": "abc"};
    person["age"] = 22;
    ```
    如果你想混淆字符串字面量属性名，你需要在该选项的基础上再使用`-enable-string-property-obfuscation`选项。比如
    ```
    -enable-property-obfuscation
    -enable-string-property-obfuscation
    ```
    注意：如果你的代码里面有字符串属性名包含特殊字符(除了`a-z, A-Z, 0-9, _`之外的字符)，比如`let obj = {"\n": 123, "": 4, " ": 5}`，我们建议不要开启`-enable-string-property-obfuscation`选项，因为当你不想混淆这些名字时，可能无法通过[保留选项](#保留选项)来指定保留这些名字。

`-enable-toplevel-obfuscation`

开启顶层作用域名称混淆。如果你使用这个选项，那么所有的顶层作用域的名称都会被混淆，除了下面场景:
* 被`import/export`的名称不会被混淆。
* 当前文件找不到声明的名称不会被混淆。
* 被[保留选项](#保留选项)指定的顶层作用域名称不会被混淆。
* 系统API列表中的顶层作用域名称不会被混淆。

`-compact`

去除不必要的空格符和所有的换行符。如果你使用这个选项，那么所有代码会被压缩到一行。

`-remove-log`

删除所有`console.*`语句。

`-print-namecache` filepath

将名称缓存保存到指定的文件路径。名称缓存包含名称混淆前后的映射。如果你使用了`-enable-property-obfuscation`或
`-enable-toplevel-obfuscation`选项，并且你希望未来进行增量编译(比如热修复)，那么你应该使用这个选项，
并且将缓存文件保管好。

`-apply-namecache` filepath

复用指定的名称缓存文件。名字将会被混淆成缓存映射对应的名字，如果没有对应，将会被混淆成新的随机段名字。
该选项应该在增量编译场景中被使用。

默认情况下，DevEco Studio会在临时的缓存目录中保存缓存文件，并且在增量编译场景中自动应用该缓存文件。

### 保留选项

保留选项只有在使用`enable-property-obfuscation`或`enable-toplevel-obfuscation`选项时发挥作用。

`-keep-property-name` [,modifiers,...]

指定你想保留的属性名。比如下面的例子:
```
-keep-property-name
age
firstName
lastName
```

**哪些属性名应该被保留?**

为了保障混淆的正确性，我们建议你保留所有不通过点语法访问的属性。

例子:
```
var obj = {x0: 0, x1: 0, x2: 0};
for (var i = 0; i <= 2; i++) {
    console.log(obj['x' + i]);  // x0, x1, x2 应该被保留
}

Object.defineProperty(obj, 'y', {});  // y 应该被保留
console.log(obj.y);

obj.s = 0;
let key = 's';
console.log(obj[key]);        // s 应该被保留

obj.u = 0;
console.log(obj.u);           // u 可以被正确地混淆

obj.t = 0;
console.log(obj['t']);        // 在开启字符串字面量属性名混淆时t和't'会被正确地混淆，但是我们建议保留

obj['v'] = 0;
console.log(obj['v']);        // 在开启字符串字面量属性名混淆时'v'会被正确地混淆，但是我们建议保留
```

`-keep-global-name` [,modifiers,...]

指定要保留的顶层作用域的名称。比如，
```
-keep-global-name
Person
printPersonName
```

**哪些顶层作用域的名称应该被保留?**

在Javascript中全局变量是`globalThis`的属性。如果在代码中使用`globalThis`去访问全局变量，那么该变量名应该被保留。

例子:
```
var a = 0;
console.log(globalThis.a);  // a 应该被保留

function foo(){}
globalThis.foo();           // foo 应该被保留

var c = 0;
console.log(c);             // c 可以被正确地混淆

function bar(){}
bar();                      // bar 可以被正确地混淆

class MyClass {}
let d = new MyClass();      // MyClass 可以被正确地混淆
```

`-keep-dts` filepath

保留指定路径的`.d.ts`文件中的名称。这里的文件路径可以是一个目录，这种情况下目录中所有`.d.ts`文件中的名称都会被保留。
如果在构建HAR时使用了这个选项，那么文件中的名称会被合并到最后的`obfuscation.txt`文件中。

### 注释

可以使用`#`在混淆规则文件中进行注释。每行以`#`开头的文本会被当做是注释，比如下面的例子:
```
# white list for MainAbility.ets
-keep-global-name
MyComponent
GlobalFunction

-keep-property-name # white list for dynamic property names
firstName
lastName
age
```
构建HAR时，注释不会被合并到最后的`obfuscation.txt`文件中。

### 混淆规则合并策略
一个工程中经常会有许多混淆规则文件，这些文件来自于:
* 主工程的`ruleOptions.files` (这里主工程我们指的是正在构建的工程)
* 本地依赖的library中的`consumerFiles`选项中指定的文件
* 远程依赖的HAR包中的`obfuscate.txt`文件

当构建主工程的时候，这些文件中的混淆规则会按照下面的合并策略(伪代码)进行合并:
```
let `listRules` 表示上面提到的所有混淆规则文件的列表
let finalRule = {
    disableObfuscation: false,
    enablePropertyObfuscation: false,
    enableToplevelObfuscation: false,
    compact: false,
    removeLog: false,
    keepPropertyName: [],
    keepGlobalName: [],
    keepDts: [],
    printNamecache: string,
    applyNamecache: string
}
for each file in `listRules`:
    for each option in file:
        switch(option) {
            case -disable-obfuscation:
                finalRule.disableObfuscation = true;
                continue;
            case -enable-property-obfuscation:
                finalRule.enablePropertyObfuscation = true;
                continue;
            case -enable-toplevel-obfuscation:
                finalRule.enableToplevelObfuscation = true;
                continue;
            case -compact:
                finalRule.compact = true;
                continue;
            case -remove-log:
                finalRule.removeLog = true;
                continue;
            case -print-namecache:
                finalRule.printNamecache = #{指定的路径名};
                continue;
            case -apply-namecache:
                finalRule.applyNamecache = #{指定的路径名};
                continue;
            case -keep-property-name:
                finalRule.keepPropertyName.push(#{指定的名称});
                continue;
            case -keep-global-name:
                finalRule.keepGlobalName.push(#{指定的名称});
                continue;
            case -keep-dts:
                finalRule.keepDts.push(#{指定的路径});
                continue;
        }
    end-for
end-for
```
最后使用的混淆规则来自于对象`finalRule`。

如果构建的是HAR，那么最终的`obfuscate.txt`文件内容来自于主工程和本地依赖的library的`consumerFiles`选项，
以及依赖的HAR的`obfuscate.txt`文件的合并。合并策略和上面一样，除了以下的不同:
* `-keep-dts`选项会被转换成`-keep-global-name`和`-keep-property-name`。
* `-print-namecache`和`apply-namecache`选项会被忽略，不会出现在最后的`obfuscate.txt`文件中。