harmonyos-best-practices-mcp 0.1.0

package/data/docs/bpta-app-asset-protection-design.md

@@ -0,0 +1,277 @@
+# 应用资产保护设计
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-app-asset-protection-design
+> 文档标识(fileName): bpta-app-asset-protection-design  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:39:21  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+本文档面向HarmonyOS应用的设计人员，介绍应用在资产保护方案设计中可能遇到的典型场景及推荐设计方案，并提供方案的关键点和参考案例。
+
+#### 典型业务场景
+
+HarmonyOS应用资产包括代码、用户数据、安全密钥。数据库资产在服务器侧，由应用自行保护。HarmonyOS系统提供保护机制。
+
+在当前APP开发过程中遇到的实际资产保护业务场景中，总结出以下典型场景，可供更多APP参考，设计资产保护业务方案：
+
+|  |  |  |
+| --- | --- | --- |
+| **场景编号** | **资产保护场景** | **简述** |
+| 1 | 保护应用代码 | 保护应用代码是为了防止恶意攻击者进行反向工程和盗用。未受保护的代码可能被攻击者获取、修改、复制或分发，导致知识产权被侵犯或应用程序被用于恶意目的，如盗取用户个人信息或进行其他违法活动。 |
+| 2 | 保护用户数据 | 用户数据包括个人信息、账户信息、交易记录、位置信息等。若未妥善保护，攻击者可能获取并恶意使用这些数据，如盗取身份信息、银行账户信息等。此外，用户数据保护是监管要求的重点，不当保护会损害应用及HarmonyOS系统的用户口碑。 |
+| 3 | 保护应用密钥 | 密钥用于加密和解密数据。密钥泄露导致数据泄露和安全问题。 |
+
+#### HarmonyOS安全能力整体架构
+
+## HarmonyOS安全能力概述
+
+HarmonyOS安全能力全景图如下：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1b/v3/ekI8tXUcSc2cUyM9ejS4DA/zh-cn_image_0000002194010336.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=E2E7026C7F0A7F792F6423E6507348BE7E67FBF67AA674320057601299A402BF "点击放大")
+
+**系统安全：**
+
+系统安全基于硬件构建安全可信根。多种技术从底层构建HarmonyOS系统安全底座。这些技术包括访问控制、漏洞防利用、系统完整性保护和网络安全保护。
+
+**应用安全生态：**
+
+HarmonyOS系统在系统安全底座之上，提供多种安全保护能力。这些能力覆盖应用资产保护的各种场景。HarmonyOS应用可以使用这些能力，保护应用全生命周期内的资产。
+
+**HarmonyOS应用：**
+
+HarmonyOS应用是自身应用资产的责任方。应用需要按需使用HarmonyOS系统提供的安全能力，并按照推荐的资产保护设计进行保护。
+
+## HarmonyOS资产保护关键技术介绍
+
+**代码混淆**
+
+移动应用的代码安全非常重要。DevEco Studio默认提供代码混淆能力。混淆后的JS、TS、ArkTS代码难以逆向分析。混淆功能支持对类、方法等名称进行混淆。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1d/v3/4MpA6rIXS8SvFy_RodIDgQ/zh-cn_image_0000002193850752.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=112BFC2760BCC8DD9A840BEE09FFD92955B05DEC1B5605E8EA6DAA2782D0E672 "点击放大")
+
+代码混淆方案基于源码混淆。源码转换为抽象语法树（AST），在AST上进行作用域和符号分析。混淆名称和属性，移除日志打印代码，合并语句，压缩代码体积。这些操作在保证运行时性能不变的前提下，有效保护开发者核心知识产权。
+
+混淆前：
+
+```
+function getAgeInfo() {
+  let age = 20;
+  let name = 'jack';
+  if (name) {
+    return age;
+  } else {
+    return -1;
+  }
+}
+
+console.log('' + getAgeInfo());
+```
+
+混淆后：
+
+```
+function getAgeInfo() {
+  let c = 0x14;
+  let b = 'jack';
+  if (b) {
+    return c;
+  } else {
+    return -0x1;
+  }
+}
+
+console['log']('' + getAgeInfo());
+```
+
+**应用加密**
+
+HarmonyOS系统提供端到端的应用代码保护机制。该机制以系统安全为基础，构建内核级应用生命周期内的代码安全保护能力。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0c/v3/jPC91h2IT3KwGBXYBajgBA/zh-cn_image_0000002193850744.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=19572F79C699C9BB6A94C40F8CF78094BBC5051E5AA7AB666037254E11A31874 "点击放大")
+
+开发者向应用市场提交上架申请。应用市场审核后，对上架应用进行代码加密。应用在设备上安装时，安装文件仍处于加密状态，有效保护应用程序。应用程序启动时，内核加载的文件按页解密执行。应用加密采用标准AES加密算法，提高应用程序的安全性。
+
+**应用包签名**
+
+开发者对应用安装包签名后，上架应用市场。应用市场进行上架检测和质量审核。满足上架要求的应用，由应用市场重签名。只有重签名的应用才允许在设备上安装。
+
+HarmonyOS系统对所有安装应用进行签名校验，确保来源可信和完整性。签名校验在应用安装时进行，签名校验失败则禁止安装。HarmonyOS系统使用根CA对应用安装包进行签名校验。签名证书采用证书链方式签署，从根CA开始。
+
+HarmonyOS系统使用根CA对应用程序安装包进行签名校验，应用安装包的签名证书都需要从根CA开始采用证书链的方式签署。
+
+对于调试应用的安装，HarmonyOS系统在校验安装包签名基础上，匹配应用调试Profile中的设备ID与当前设备ID。不匹配则禁止安装。
+
+对于发布应用的安装，HarmonyOS系统仅允许经过应用市场审核并通过重签名的安装包进行安装。
+
+**关键资产存储**
+
+关键资产存储（Asset Store）提供关键敏感隐私数据的本地加密存储。应用可以将高安全敏感的关键资产短数据（如APP账号密码、银行卡号等）在本地加密存储。加密密钥存储在安全的隔离区，只有合法应用才能访问并解密这些数据。具体的架构如下：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c6/v3/re1TdSoBR2qef5--F6U1bA/zh-cn_image_0000002193850760.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=A64C9A80FC2851A3C7AD25A38F465DADFF62B490C43A95A1D2F83BECA13FF929 "点击放大")
+
+除此之外，关键资产存储还支持以下安全措施：
+
+- 基于属主的访问控制： 所有的关键资产都受属主访问控制保护，业务无需设置。
+- 基于锁屏状态的访问控制：分为三种保护等级（安全性依次递增），开机后可访问、首次解锁后可访问、解锁时可访问，业务可根据实际情况设置任意一种，若不设置，则默认保护等级为“首次解锁后可访问”。
+- 基于锁屏密码设置状态的访问控制：在用户设置了锁屏密码后，关键资产才被允许访问。
+- 基于用户认证的访问控制：任意一种认证方式（指纹、人脸、PIN码）通过，均可授权本次关键资产的访问。
+
+**密钥管理**
+
+HarmonyOS通用密钥库系统（HarmonyOS Universal KeyStore，HUKS）是HarmonyOS提供的系统级密钥管理服务，支持密钥的全生命周期管理，包括密钥生成、存储、使用和销毁，同时提供密钥的合法性证明。HUKS基于系统安全能力，确保业务密钥的安全，业务无需自行实现相关功能。
+
+HUKS的核心安全设计如下。
+
+密钥不出安全环境：HUKS的核心特点是密钥全生命周期明文不出HUKS Core。在有硬件条件的设备上，如具备TEE（Trusted Execution Environment）或安全芯片的设备，HUKS Core运行在硬件安全环境中，确保即使REE（Rich Execution Environment）环境被攻破，密钥明文也不会泄露。
+
+系统级安全加密存储：基于设备根密钥加密业务密钥。有条件设备叠加用户口令加密。
+
+严格的访问控制：只有合法业务有权访问密钥，支持用户身份认证以满足高安全敏感场景下的密钥访问需求。
+
+密钥的合法性证明：为业务提供硬件厂商级别的证明，确保密钥未被篡改，确保存储在有硬件保护的HUKS Core中，并具备正确的密钥属性。
+
+密钥会话是HUKS中承载密钥使用的基础，主要用于初始化密钥信息和缓存业务数据。数据的密码学运算和密钥密文的加解密都在HUKS Core中进行，以确保密钥明文和运算过程的安全。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cb/v3/g69NVfr2Sm-XFnzRvdrjuA/zh-cn_image_0000002229336137.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=5790C9BC4555E8785888B79832BD3FBFA6EDEEAA0EF6487C8B0E63556847E359 "点击放大")
+
+#### 应用资产保护设计
+
+## 概述
+
+不同的资产保护场景需要的HarmonyOS系统安全能力各不相同，本章将按照常见场景设计相应的HarmonyOS安全保护方案。
+
+## 保护应用代码场景
+
+**场景描述**
+
+在HarmonyOS应用业务实现过程中，应用代码是最重要的资产和核心。保护不当可能导致严重的知识产权损失和安全攻击。
+
+在HarmonyOS开发中，应用代码分为C/C++实现的代码和JS、TS、ArkTS实现的代码，最终编译产物主要包括.so文件和.abc文件。.so文件反编译难度大，代码逆向困难，应用可按需决定是否进一步保护。.abc文件为ArkTS编译后的字节码，反编译难度小，容易逆向分析出核心代码，建议根据业务情况做一定保护。
+
+**HarmonyOS开发实现方案介绍**
+
+HarmonyOS系统整体代码资产保护策略：
+
+（1）开发阶段默认启用基础混淆，并支持与第三方商用混淆工具对接。
+
+（2）上架阶段对应用进行加密。
+
+（3）设备运行时对应用进行解密处理。
+
+其中代码混淆和应用加密方案的介绍在**[混淆加固](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-build-obfuscation)**和**[应用加密](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/code-protect)**章节。
+
+**业务实现中的关键点**
+
+**DevEco Studio默认开启基础代码混淆**
+
+为保护代码资产，编译器默认开启代码混淆功能，混淆参数名和局部变量名。建议保持混淆开启，除非有特殊情况。若需关闭代码混淆，可在模块级的build-profile.json5配置文件中进行设置。
+
+**官方提供的自定义混淆选项**
+
+DevEco Studio提供高阶混淆能力，开发者可通过以下步骤配置：
+
+1. 打开Stage模型的ArkTS工程。
+
+2. 打开模块级build-profile.json5文件，在obfuscation字段下配置混淆规则。
+
+3. 在混淆规则文件中，files字段配置混淆规则文件路径，高级混淆能力通过将混淆规则写入混淆规则文件实现。
+
+在混淆规则文件中，开发者可以写混淆选项和保留选项，具体的混淆选项参考[混淆配置](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-app-code-ob#section171089239254)，使用第三方安全加固厂商加固请参考[使用第三方加固](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-app-code-ob#section4564113173012)。
+
+**HarmonyOS提供应用加密机制**
+
+开发者向应用市场提交上架申请、选择加密并通过审核后，应用市场会对所有上架的应用做代码加密，具体加密的对象为应用包中的.abc文件，并在应用运行加载进内存时，在系统内核进行解密。目标是保护应用程序二进制代码安全，保护开发者知识产权，并避免应用脱离设备后仍能运行。
+
+应用加密主要通过以下三个关键能力实现：
+
+代码加密能力：基于abc文件的加密，兼容快速补丁修复，并采用代码签名机制。
+
+基于动态加载按页解密能力：在内核中按应用加载文件的内存页进行解密，提升解密效率。
+
+密钥分发：通过平台账号的访问控制和设备TEE的设备认证进行密钥分发。
+
+整套方案作为HarmonyOS系统应用安全的基础能力，由应用市场、HarmonyOS内核和终端设备实现，开发者无需进行任何配置和开发。
+
+第三方提供的应用安全加固保护
+
+HarmonyOS在系统提供的应用代码保护机制之外，同时也兼容三方提供的安全加固保护机制，在应用代码资产保护述求较高的场景下，建议在开启系统保护机制情况下，同时使能三方的加固保护，增强代码资产保护的纵深防御能力。部分[三方安全厂商](https://developer.huawei.com/consumer/cn/market/prod-list/a97c5f2de7df49f49c139a32125fa4c8/categoryL2_202404220005?categoryIdL3=categoryL3_202403120002)已支持HarmonyOS系统，具体方法请参考[使用第三方加固](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-app-code-ob#section4564113173012)。
+
+**案例参考**
+
+应用代码保护是系统应用安全的基本能力。不同垂类的应用对应用安全加固的要求和实现方式存在差异。以安全性要求最高的金融类应用为例，可以参考以下HarmonyOS应用的实际保护案例：
+
+|  |  |  |
+| --- | --- | --- |
+| **混淆** | 基础混淆 | 使用HarmonyOS官方Arkguard默认配置 |
+| 增强混淆 | 第三方提供，建议在安全要求较高的场景中选择开启，提高应用代码资产保护的纵深防御能力 |
+| **加密（应用市场）** | 代码加密 | 默认支持，需要上架时选择开启 |
+| **加壳** | 加壳 | **禁止** |
+| **其他加固** | 防调试 | 在HarmonyOS系统的基础上，第三方提供增强 |
+| 防篡改 | 在HarmonyOS系统基础上，三方提供增强 |
+
+**与业界方案特殊差异说明**
+
+平台的应用安全机制和生态情况不同，因此应用加固方案也有所不同。具体区别如下：
+
+|  |  |
+| --- | --- |
+| **操作系统** | **应用自保护策略** |
+| HarmonyOS | 应用加密（建议） + 基础混淆 + 高级混淆（三方提供商业源码级别的混淆工具，安全要求高的场景建议，但需要满足上架审核要求） |
+| 其他 | 加壳（主要）/应用加密（主要）+ 普通混淆/高级混淆（商业源码级别的混淆工具，但需要满足上架审核要求） |
+
+## 保护用户数据
+
+**场景描述**
+
+应用在用户使用过程中会产生用户数据，包括个人信息如姓名、地址、电话号码、电子邮件地址，以及使用过程中的行为数据，如使用时长、功能使用次数。这些数据需根据类型进行保护，以符合监管和隐私要求。本设计文档将用户数据分为普通用户数据和敏感个人数据两类，提供HarmonyOS开发中的保护能力和方案。应用可依据《个人信息保护法》或其他分类方法对数据进行分类。
+
+**HarmonyOS开发实现方案介绍**
+
+在HarmonyOS系统中，普通用户数据通过每个应用独立的应用沙箱进行隔离。应用沙箱保护机制确保应用无法访问除自身文件目录之外的其他应用或用户的数据。此外，所有应用的目录可见范围均经过权限隔离，仅自身和部分系统进程有权限访问，未授权的第三方应用无法访问。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/9a/v3/b5WQjJgFRBu0-9W-OiVSGQ/zh-cn_image_0000002194010332.png?HW-CC-KV=V1&HW-CC-Date=20260623T075630Z&HW-CC-Expire=86400&HW-CC-Sign=FB2FF2D8899B5176486643A3C1E4B3D01873D3AC5BDC4C3BD47EB6A1F1B35B5B "点击放大")
+
+除此之外，对于一些更加敏感的用户数据，如用户口令、身份证号、银行卡号等，HarmonyOS系统还提供关键资产存储服务，关键资产的安全存储，依赖底层的TEE可信执行环境。具体来说，关键资产的加/解密操作以及访问控制校验，都在安全环境中完成，即使系统被攻破，也能保证用户敏感数据不发生泄露。详细方案可以参考[Asset Store Kit简介](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/asset-store-kit-overview)。
+
+**业务实现中的关键点**
+
+**应用沙箱隔离及应用文件路径**
+
+应用沙箱限定了应用可访问的数据范围。在“应用沙箱目录”中，应用仅能访问自己的文件和必需的系统文件。因此，本应用的文件不会被其他应用访问，从而确保了应用文件的安全。
+
+开发指导可以参考[应用沙箱目录](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-sandbox-directory)。
+
+**关键资产存储服务使用**
+
+HarmonyOS系统通过Asset Store Kit为应用开发者提供关键资产的安全存储与管理服务。
+
+开发指导及相关案例可参考[Asset Store Kit（关键资产存储服务）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/asset-store-kit)。
+
+**与业界方案特殊差异说明**
+
+应用开发者可以参考业界的类似方案来设计和使用本能力。
+
+## 保护应用密钥
+
+**场景描述**
+
+在HarmonyOS中用于加密和解密数据的密钥是其非常重要且需要保护的资产之一。密钥的主要使用场景包括：
+
+- 数据加密: 应用密钥可以用于加解密重要数据；
+- 应用安全: 应用密钥可以用于保护应用免受恶意攻击；
+- 数据完整性验证: 应用密钥可以用于验证数据的完整性，确保数据在传输或存储过程中没有被篡改；
+- 应用身份验证: 应用密钥可以用于验证应用或服务器身份。
+
+开发指导及相关案例可参考[Universal Keystore Kit简介](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-overview)。
+
+**与业界方案特殊差异说明**
+
+本方案的核心层运行在硬件安全环境中，除此之外，与行业标准方案没有显著差异。
+
+#### 参考
+
+[鸿蒙生态应用安全技术白皮书](https://developer.huawei.com/consumer/cn/doc/guidebook/harmonyecoappsecurity-guidebook-0000001808819033)

package/data/docs/bpta-app-code-ob.md

@@ -0,0 +1,180 @@
+# 应用代码混淆
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-app-code-ob
+> 文档标识(fileName): bpta-app-code-ob  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:39:21  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+代码混淆技术可以增加代码的复杂性和模糊性，从而提高攻击者分析代码的难度。代码混淆有以下几个方面的作用：
+
+1. 保护知识产权：代码混淆防止他人轻易复制和窃取软件代码，增加逆向工程难度。
+2. 防止逆向工程：逆向工程是分析软件以了解其工作原理和实现细节的过程。代码混淆可增加逆向工程的难度，保护应用程序免受恶意修改或破坏。
+3. 提高安全性：代码混淆减少漏洞和安全风险，增加攻击者利用漏洞的难度。
+4. 降低反盗版和欺诈风险：混淆代码可增加攻击者破解软件许可验证系统或修改代码绕过付费机制的难度，从而减少盗版和欺诈。
+
+针对工程源码的混淆提高破解难度，缩短类和成员名称，减小应用大小。
+
+#### 混淆开启
+
+从DevEco Studio版本4.0 Beta1开始，hvigor插件提供代码混淆功能。开启混淆的条件如下：
+
+- 工程为Stage模型
+- 在Release编译模式下
+- 模块build-profile.json5文件中开启混淆配置
+
+  ```
+  "arkOptions": {
+    "obfuscation": {
+      "ruleOptions": {
+        "enable": true,
+        // ...
+      }
+    }
+  },
+  ```
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ce/v3/qsCZR9WST9O2C_5mmK2L9w/caution_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=6B0BC20A935A1E078797FF2193C44FBB3CB7E079EC71E77B9552AB212139B76D) 
+
+enable默认为false，默认不开启代码混淆功能。
+
+满足开启混淆的条件后，选择目标模块，点击Build -> Make Module开始编译。
+
+如果工程或模块是Static Library，则该工程或模块是一个HAR。
+
+构建[字节码HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-har#section16598338112415)时有以下三种方式：
+
+1. 以Debug模式构建HAR，会直接打包源码，不进行代码混淆。
+2. 以Release模式构建HAR，会编译、混淆并压缩代码。
+3. 构建字节码格式的HAR。开启混淆时，编译器会先对源码中间文件进行混淆，再生成abc字节码。
+
+**图1** DevEco Studio选择release编译模式
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/61/v3/RMFZ4M5_TJqB9RHPIwUz-A/zh-cn_image_0000002194010408.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=274B5B39FB49357A6DA1CCBB44594E368A725536C935E9D22F69D4CEA9A3F877 "点击放大")
+
+**图2** DevEco Studio指定模块编译
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c/v3/cWFq9Yc6Rry49pDdwCrLeg/zh-cn_image_0000002229336225.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=D672EF13D711231111CD922E035B75F632D4486A84063278A2354545CA4812C9 "点击放大")
+
+#### 混淆配置能力
+
+## 编译选项
+
+若按照上述编译流程开启代码混淆，在DevEco Studio 5.0.3.600之前的版本，默认仅混淆参数名和局部变量名。从DevEco Studio 5.0.3.600版本起，默认启用四项推荐的混淆选项：-enable-property-obfuscation、-enable-toplevel-obfuscation、-enable-filename-obfuscation和-enable-export-obfuscation。开发者可以根据需要进一步修改混淆配置。
+
+如果在流水线开启混淆并使用release构建模式，在编译参数加上 -p buildMode=release -p debuggable=false。
+
+## 混淆配置
+
+在每个模块下都能找到build-profile.json5文件，如下图所示。可以在此文件中配置是否开启混淆及混淆配置文件。
+
+**图3** 编译配置文件  
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/42/v3/Vm0tAGNhQzS1NKLjNXnzHw/zh-cn_image_0000002229336217.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=F77A8E574428E06DC612D64057FA161394340902764DBAF4AF74720BD1AE7174 "点击放大")
+
+新建工程时，每个模块下都有obfuscation-rules.txt文件，用于配置混淆。
+
+**图4** 混淆配置文件  
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/73/v3/lOQR2_cnSM25LA2roA-mDw/zh-cn_image_0000002229336209.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=29BA79E3B654BABC2771174F628E520C8B71C0DD4EA6EF0CCEF4DE295CA81045 "点击放大")
+
+在上图中，obfuscation-rules.txt文件中添加了-enable-property-obfuscation和-enable-toplevel-obfuscation开关，表示已启用属性混淆和顶层作用域名称混淆。
+
+DevEco Studio混淆现有选项及功能描述如下：
+
+|  |  |  |
+| --- | --- | --- |
+|  | 混淆自定义选项名称 | 功能简述 |
+| 混淆选项 | -disable-obfuscation | 关闭混淆 |
+| -enable-property-obfuscation | 属性混淆 |
+| -enable-toplevel-obfuscation | 顶层作用域名称混淆 |
+| -enable-filename-obfuscation | 文件名混淆 |
+| -enable-export-obfuscation | export导出名称与属性混淆 |
+| -compact | 代码压缩 |
+| -remove-log | 删除console.*方法 |
+| -print-namecache filepath | 指定路径输出namecache.json文件及内容 |
+| -apply-namecache filepath | 复用指定的名称缓存文件 |
+| -remove-comments | 删除注释 |
+| 保留选项 | -keep-property-name | 保留属性名 |
+| -keep-global-name | 保留顶层作用域和导出元素的名称 |
+| -keep-file-name | 保留指定的文件/文件夹的名称 |
+| -keep-dts | 读取指定.d.ts文件中的名称作为白名单 |
+| -keep-comments | 保留编译生成的声明文件中class, function, namespace, enum, struct, interface, module, type及属性上方的JsDoc注释 |
+| -keep | 保留指定相对路径中的所有名称（例如变量名、类名、属性名等） |
+| 通配符 | 名称类和路径类的保留选项支持通配符 |
+
+混淆选项具体的使用方法和样例代码可以参考[代码混淆](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation)。
+
+**混淆优化建议**
+
+开发人员混淆工程时，发现缓存文件或SDK中的文件中存在大量未混淆的源码名称。原因包括以下两类：
+
+- - 混淆选项开启较少；开启-enable-property-obfuscation、-enable-toplevel-obfuscation、-enable-export-obfuscation、-enable-filename-obfuscation选项。
+- - 源码名称与系统白名单、语言白名单重名；添加后缀避开白名单。
+
+## 混淆规则合并策略
+
+在编译一个模块时，生效的混淆规则是当前编译模块混淆规则和依赖模块混淆规则的合并结果。具体规则请参考：[混淆规则合并策略](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation#混淆规则合并策略)。
+
+#### 查看混淆结果
+
+开发人员在编译模块的build目录中可找到编译和混淆生成的缓存文件、名称映射表及系统API白名单文件。
+
+- 源码编译及混淆缓存文件目录：build/[…]/release/模块名
+- 混淆名称映射表及系统API白名单目录：build/[…]/release/obfuscation
+  - - 名称映射表文件：nameCache.json，记录源码名称映射。
+  - - 系统API白名单文件：systemApiCache.json，记录SDK接口与属性名称。
+
+  **图5** DevEco Studio编译产物与缓存文件  
+  ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/54/v3/hcGm5OsFTfq-RkcrFqGy4g/zh-cn_image_0000002194010432.png?HW-CC-KV=V1&HW-CC-Date=20260623T075631Z&HW-CC-Expire=86400&HW-CC-Sign=08D781449627DCD651F82F44EAA879ED5E39503F309EC1C337CD81EFF364BEDE)
+
+#### 调试
+
+代码经过混淆工具处理后，名称会发生更改，这可能导致运行时崩溃堆栈日志难以理解，因为堆栈与源代码不完全一致。如果未保留调试信息，行号及名称更改将导致无法准确定位问题。此外，启用-enable-property-obfuscation、-enable-toplevel-obfuscation等选项后，代码混淆可能会引发运行时崩溃或功能性错误。开发人员需要还原报错堆栈，排查并配置白名单以确保功能正常。
+
+## 函数调用栈还原
+
+经过混淆的应用程序中代码名称会发生更改，因此报错栈与源码不完全一致，crash时打印的报错栈会难以理解，如何处理请参考[报错栈还原](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation-guide#报错栈还原)。
+
+## 反混淆工具hstack
+
+hstack需要将Node.js配置到环境变量中，详细使用说明请参考[堆栈解析工具（hstack）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-command-line-hstack)。
+
+## 常见报错案例
+
+请参考[ArkGuard混淆常见问题](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation-questions)。
+
+#### 使用第三方加固
+
+在HarmonyOS提供的代码混淆能力之外，开发者还可以使用第三方安全厂商提供的高级混淆和加固能力。多家安全加固厂商已经启动了HarmonyOS开发，开发者可以根据需求选择这些安全厂商的服务。开发者需要与第三方安全厂商自行沟通合作方式和范围，本文档不做详细说明。具体的官方与第三方代码混淆能力的关系如下：
+
+|  |  |  |  |
+| --- | --- | --- | --- |
+| **特性** | **特性描述** | **HarmonyOS** | **三方** |
+| **名称混淆** | 混淆类、字段、属性、方法和文件名。 | √ | √ |
+| **控制混淆** | 混淆方法内的控制流以防御自动或手动代码分析，包括虚假控制流和控制流扁平化。 | × | √ |
+| **指令替换** | 通过将简单的算术和逻辑表达式转换为难以分析的代码来保护专有公式。 | × | √ |
+| **数据混淆** | 加密敏感字符串，以防止通过尝试搜索的黑客攻击，也用来加密类、asset文件、资源文件和Native库。 | × | √ |
+| **代码虚拟化** | 转换方法实现为随机生成虚拟机的指令序列。 | × | √ |
+| **调用隐藏** | 为访问敏感的APIs添加反射，比如用于签名校验和密码操作的标准APIs。 | × | √ |
+| **移除日志代码** | 移除logging、调试和测试代码，以阻止任何利用此信息的企图。 | × | √ |
+
+由于HarmonyOS代码签名、应用加密等安全机制的限制，以及应用市场上架审核的纯净安全要求，三方加固厂商提供的安全加固内容必须满足以下六点要求：
+
+1、不允许隐藏敏感系统API的调用，审核人员必须能够清晰地看到应用的特性。
+
+2、不允许混淆非自研的SDK。SDK应由SDK厂商自行进行混淆保护。如果非自研SDK被混淆，将会影响应用市场审核相关SDK的指纹信息。
+
+3、通过第三方安全加固的应用程序，必须确保不包含恶意行为，以免对生态系统造成影响。此要求为约束性条款，不遵守可能导致应用被下架。
+
+4、不允许使用第三方虚拟机，HarmonyOS系统通过代码签名等机制限制动态加载代码，这可能导致应用无法正常运行。
+
+5、不允许对方舟字节码文件进行篡改，此方法可能让应用无法正常运行，以及影响应用市场对应用的纯净安全进行审核。
+
+6、不允许对系统库使用hook技术，此方法影响应用市场对应用的纯净安全进行审核。
+
+#### 示例代码
+
+- [应用安全示例代码](https://gitcode.com/harmonyos_samples/BestPracticeSnippets/tree/master/Privacy)