HarmonyOS开发：代码混淆与ProGuard配置

📌 核心要点：深入理解HarmonyOS代码混淆原理，掌握obfuscation-rules.txt规则编写，解决反射与混淆的兼容难题，实现代码安全与包体积的双重优化。

一、背景与动机

你有没有想过，当你辛辛苦苦开发的应用发布到应用市场后，别人只需一个反编译工具就能看到你的核心业务逻辑？

在HarmonyOS生态中，ArkTS代码最终会被编译为方舟字节码（.abc文件），虽然比JavaScript的字节码更难直接阅读，但仍然存在被逆向分析的风险。代码混淆正是应对这一威胁的第一道防线——它通过重命名类名、方法名、属性名，让反编译后的代码变得难以理解。

但代码混淆的意义远不止安全防护。混淆后的代码通常更短小——getUserAuthenticationToken变成了a，calculateMonthlyPayment变成了b——这些名称缩短直接减小了字节码体积。在一个中大型项目中，代码混淆可以带来5%~15%的体积缩减。

然而，混淆也是一把双刃剑。配置不当会导致运行时崩溃——反射调用的类名被混淆了、序列化的属性名对不上了、动态加载的模块找不到了……这些问题往往在Debug模式下一切正常，Release模式下才暴露，排查起来令人抓狂。

本文将从原理到实战，带你系统掌握HarmonyOS的代码混淆配置，让你既能享受混淆带来的安全和体积红利，又能避开那些令人头疼的坑。

二、核心原理

2.1 代码混淆的工作流程

flowchart TB
    A[ArkTS源代码] --> B[编译器前端解析]
    B --> C[生成AST抽象语法树]
    C --> D{是否启用混淆?}
    D -->|否| E[直接生成字节码]
    D -->|是| F[混淆处理器介入]
    
    F --> G[名称混淆<br/>类名/方法名/属性名]
    F --> H[控制流混淆<br/>代码结构变换]
    F --> I[字符串加密<br/>常量字符串混淆]
    F --> J[死代码注入<br/>干扰代码插入]
    
    G --> K[混淆后AST]
    H --> K
    I --> K
    J --> K
    
    K --> L[生成混淆字节码]
    E --> M[生成SourceMap]
    L --> M
    
    M --> N[最终.abc文件]
    
    classDef sourceStyle fill:#E74C3C,stroke:#C0392B,color:#fff,font-weight:bold
    classDef processStyle fill:#3498DB,stroke:#2980B9,color:#fff
    classDef obfuscateStyle fill:#2ECC71,stroke:#27AE60,color:#fff,font-weight:bold
    classDef outputStyle fill:#9B59B6,stroke:#8E44AD,color:#fff
    
    class A sourceStyle
    class B,C processStyle
    class F,G,H,I,J,K obfuscateStyle
    class E,L,M,N outputStyle

2.2 HarmonyOS混淆的四层机制

HarmonyOS的代码混淆分为四个层次，每一层都有独立的开关和规则：

2.3 混淆规则文件体系

HarmonyOS的混淆规则通过多个文件协同工作：

项目根目录/
├── obfuscation-rules.txt          # 主混淆规则文件
├── consumer-rules.txt             # 消费者规则（库模块专用）
└── entry/
    └── obfuscation-rules.txt      # 模块级混淆规则

核心原则：obfuscation-rules.txt定义的是"我要混淆什么"，而-keep规则定义的是"我要保留什么"。混淆系统会在所有规则的基础上取并集——任何被-keep规则匹配到的名称都不会被混淆。

三、代码实战

3.1 基础示例：混淆规则配置文件

// obfuscation-rules.txt - HarmonyOS混淆规则配置

# ============================================
# 第一部分：启用混淆开关
# ============================================

# 启用属性名混淆（最基础的混淆）
-enable-property-obfuscation

# 启用顶层名称混淆（函数名、类名等）
-enable-toplevel-obfuscation

# 启用文件名混淆
-enable-filename-obfuscation

# 启用导出名称混淆
-enable-export-obfuscation

# 启用紧凑输出（移除空白和注释）
-compact

# ============================================
# 第二部分：保留规则（白名单）
# ============================================

# 保留Ability入口类名
-keep-class-name
EntryAbility
MainAbility
SplashAbility

# 保留序列化相关属性（JSON序列化依赖属性名）
-keep-property-name
userId
userName
token
sessionId
createTime
updateTime
status
message
code
data

# 保留反射调用的方法名
-keep-property-name
onCreate
onDestroy
onWindowStageCreate
onWindowStageDestroy
onForeground
onBackground

# 保留UI组件的生命周期方法
-keep-property-name
aboutToAppear
aboutToDisappear
onPageShow
onPageHide
onBackPress

# 保留文件名（动态加载依赖文件名）
-keep-file-name
entryability
mainability
splashability

# 保留导出名称（HSP模块对外接口）
-keep-global-name
UserManager
NetworkManager
StorageManager
EventManager

# ============================================
# 第三部分：注释与调试
# ============================================

# 保留SourceMap文件（用于崩溃日志还原）
# 注意：Release构建应移除此行
# -keep-source-map

# 保留调试信息
# 注意：Release构建应移除此行
# -keep-debug-info

3.2 进阶示例：反射兼容与动态加载的混淆处理

反射和动态加载是混淆的"天敌"——它们在运行时通过字符串名称查找类或方法，一旦名称被混淆，查找就会失败。下面是一个完整的兼容处理方案：

// reflect_safe_config.ets - 反射兼容的混淆配置管理器
import { fileIo } from '@kit.CoreFileKit'

// 需要保留的名称收集器
class ObfuscationKeepCollector {
  private keepClassNames: Set<string> = new Set()
  private keepPropertyNames: Set<string> = new Set()
  private keepFileNames: Set<string> = new Set()
  private keepGlobalNames: Set<string> = new Set()

  // 收集Ability入口类名
  addAbilityNames(moduleJsonPath: string): void {
    const content = fileIo.readTextSync(moduleJsonPath)
    const moduleConfig = JSON.parse(content)
    
    // 解析abilities数组
    const abilities = moduleConfig.module?.abilities || []
    for (const ability of abilities) {
      if (ability.name) {
        // 提取类名（如"EntryAbility"从".EntryAbility"中）
        const className = ability.name.replace(/^\./, '')
        this.keepClassNames.add(className)
        this.keepFileNames.add(className.toLowerCase())
      }
    }
  }

  // 收集序列化类的属性名
  addSerializableClass(classDefinition: Record<string, Object>): void {
    // 遍历所有属性，收集需要保留的名称
    const prototype = Object.getPrototypeOf(classDefinition)
    const propertyNames = Object.getOwnPropertyNames(classDefinition)
    
    for (const name of propertyNames) {
      // 跳过内置属性
      if (name.startsWith('__') || name === 'constructor') continue
      this.keepPropertyNames.add(name)
    }
  }

  // 收集HSP导出接口名
  addHspExports(indexDtsPath: string): void {
    try {
      const content = fileIo.readTextSync(indexDtsPath)
      // 解析.d.ts文件中的export声明
      const exportPattern = /export\s+(?:class|interface|function|const|enum)\s+(\w+)/g
      let match: RegExpExecArray | null
      while ((match = exportPattern.exec(content)) !== null) {
        this.keepGlobalNames.add(match[1])
      }
    } catch (e) {
      console.warn(`解析HSP导出失败: ${indexDtsPath}`)
    }
  }

  // 收集路由配置中的名称
  addRouteNames(routeConfigPath: string): void {
    try {
      const content = fileIo.readTextSync(routeConfigPath)
      const routeConfig = JSON.parse(content)
      
      // 解析路由表
      const routes = routeConfig.router?.routes || []
      for (const route of routes) {
        if (route.name) {
          this.keepPropertyNames.add(route.name)
        }
        if (route.pageSrc) {
          // 提取页面文件名
          const pageName = route.pageSrc.split('/').pop()?.replace(/\.\w+$/, '')
          if (pageName) {
            this.keepFileNames.add(pageName.toLowerCase())
          }
        }
      }
    } catch (e) {
      console.warn(`解析路由配置失败: ${routeConfigPath}`)
    }
  }

  // 生成最终的混淆规则文件
  generateRules(outputPath: string): void {
    const lines: string[] = []

    // 开关
    lines.push('# 自动生成的混淆规则 - 由ObfuscationKeepCollector生成')
    lines.push('')
    lines.push('-enable-property-obfuscation')
    lines.push('-enable-toplevel-obfuscation')
    lines.push('-enable-filename-obfuscation')
    lines.push('-enable-export-obfuscation')
    lines.push('-compact')
    lines.push('')

    // 保留类名
    if (this.keepClassNames.size > 0) {
      lines.push('# 保留Ability入口类名')
      lines.push('-keep-class-name')
      for (const name of this.keepClassNames) {
        lines.push(name)
      }
      lines.push('')
    }

    // 保留属性名
    if (this.keepPropertyNames.size > 0) {
      lines.push('# 保留序列化/反射属性名')
      lines.push('-keep-property-name')
      for (const name of this.keepPropertyNames) {
        lines.push(name)
      }
      lines.push('')
    }

    // 保留文件名
    if (this.keepFileNames.size > 0) {
      lines.push('# 保留动态加载文件名')
      lines.push('-keep-file-name')
      for (const name of this.keepFileNames) {
        lines.push(name)
      }
      lines.push('')
    }

    // 保留全局名称
    if (this.keepGlobalNames.size > 0) {
      lines.push('# 保留HSP导出名称')
      lines.push('-keep-global-name')
      for (const name of this.keepGlobalNames) {
        lines.push(name)
      }
      lines.push('')
    }

    fileIo.writeTextSync(outputPath, lines.join('\n'))
    console.info(`混淆规则已生成: ${outputPath}`)
    console.info(`保留类名: ${this.keepClassNames.size}个`)
    console.info(`保留属性名: ${this.keepPropertyNames.size}个`)
    console.info(`保留文件名: ${this.keepFileNames.size}个`)
    console.info(`保留全局名: ${this.keepGlobalNames.size}个`)
  }
}

// 使用示例
function generateObfuscationRules() {
  const collector = new ObfuscationKeepCollector()

  // 收集Ability入口
  collector.addAbilityNames('/path/to/entry/src/main/module.json5')

  // 收集HSP导出接口
  collector.addHspExports('/path/to/library/Index.d.ts')

  // 收集路由名称
  collector.addRouteNames('/path/to/entry/src/main/resources/base/profile/route_config.json')

  // 生成混淆规则
  collector.generateRules('/path/to/entry/obfuscation-rules.txt')
}

3.3 完整示例：混淆调试与崩溃日志还原

混淆后最头疼的问题就是——崩溃日志里全是a.b.c，完全看不懂。下面是一个完整的崩溃日志还原工具：

// stacktrace_decoder.ets - 混淆崩溃日志还原工具
import { fileIo } from '@kit.CoreFileKit'

// SourceMap条目
interface SourceMapEntry {
  generatedLine: number       // 生成代码行号
  generatedColumn: number     // 生成代码列号
  originalFile: string        // 原始文件路径
  originalLine: number        // 原始代码行号
  originalColumn: number      // 原始代码列号
  originalName: string        // 原始名称
}

// 还原后的堆栈帧
interface DecodedStackFrame {
  rawLine: string             // 原始混淆行
  fileName: string            // 还原后的文件名
  className: string           // 还原后的类名
  methodName: string          // 还原后的方法名
  lineNumber: number          // 还原后的行号
}

// 崩溃日志还原器
class StackTraceDecoder {
  private sourceMapEntries: SourceMapEntry[] = []
  private nameMapping: Map<string, string> = new Map()

  // 加载SourceMap文件
  loadSourceMap(sourceMapPath: string): void {
    const content = fileIo.readTextSync(sourceMapPath)
    const sourceMap = JSON.parse(content)

    // 解析VLQ编码的mappings
    // 这里简化处理，实际需要完整的VLQ解码
    if (sourceMap.mappings) {
      this.parseMappings(sourceMap)
    }

    // 解析名称映射
    if (sourceMap.names) {
      for (let i = 0; i < sourceMap.names.length; i++) {
        this.nameMapping.set(`name_${i}`, sourceMap.names[i])
      }
    }
  }

  // 解析mappings（简化版）
  private parseMappings(sourceMap: Record<string, Object>): void {
    // 实际实现需要完整的SourceMap VLQ解码
    // 此处为示意代码
    const sources = sourceMap.sources as string[] || []
    const names = sourceMap.names as string[] || []
    
    // 将解析结果存入sourceMapEntries
    // 完整实现需要处理VLQ编码的mappings字段
    console.info(`已加载SourceMap: ${sources.length}个源文件, ${names.length}个名称映射`)
  }

  // 还原单行堆栈
  decodeStackLine(line: string): DecodedStackFrame {
    // 匹配HarmonyOS堆栈格式
    // 例如: "at a.b.c (entry/ets/pages/Index.abc:123:45)"
    const stackPattern = /at\s+(\S+)\s+\(([^:]+):(\d+):(\d+)\)/
    const match = line.match(stackPattern)

    if (!match) {
      return {
        rawLine: line,
        fileName: 'unknown',
        className: 'unknown',
        methodName: 'unknown',
        lineNumber: 0
      }
    }

    const obfuscatedName = match[1]      // 混淆后的名称，如 "a.b.c"
    const fileName = match[2]            // 文件名
    const lineNum = parseInt(match[3])   // 行号
    const colNum = parseInt(match[4])    // 列号

    // 还原名称
    const decodedName = this.decodeName(obfuscatedName)

    // 还原文件名
    const decodedFile = this.decodeFileName(fileName)

    // 还原行号
    const decodedLine = this.decodeLineNumber(lineNum, colNum)

    return {
      rawLine: line,
      fileName: decodedFile,
      className: decodedName.className,
      methodName: decodedName.methodName,
      lineNumber: decodedLine
    }
  }

  // 还原名称
  private decodeName(obfuscatedName: string): { className: string; methodName: string } {
    const parts = obfuscatedName.split('.')
    
    // 尝试从名称映射中还原
    const decodedParts = parts.map(part => {
      return this.nameMapping.get(part) || part
    })

    if (decodedParts.length >= 2) {
      return {
        className: decodedParts.slice(0, -1).join('.'),
        methodName: decodedParts[decodedParts.length - 1]
      }
    }

    return {
      className: '',
      methodName: decodedParts[0] || obfuscatedName
    }
  }

  // 还原文件名
  private decodeFileName(fileName: string): string {
    // 从SourceMap中查找原始文件名
    for (const entry of this.sourceMapEntries) {
      if (entry.originalFile) {
        return entry.originalFile
      }
    }
    return fileName
  }

  // 还原行号
  private decodeLineNumber(line: number, column: number): number {
    // 在SourceMap中查找最接近的映射
    let closestEntry: SourceMapEntry | null = null
    let minDistance = Infinity

    for (const entry of this.sourceMapEntries) {
      if (entry.generatedLine === line) {
        const distance = Math.abs(entry.generatedColumn - column)
        if (distance < minDistance) {
          minDistance = distance
          closestEntry = entry
        }
      }
    }

    return closestEntry ? closestEntry.originalLine : line
  }

  // 还原完整崩溃日志
  decodeCrashLog(crashLog: string): string {
    const lines = crashLog.split('\n')
    const decodedLines: string[] = []

    for (const line of lines) {
      if (line.trim().startsWith('at ')) {
        const decoded = this.decodeStackLine(line)
        decodedLines.push(
          `  at ${decoded.className}.${decoded.methodName} (${decoded.fileName}:${decoded.lineNumber})`
        )
      } else {
        decodedLines.push(line)
      }
    }

    return decodedLines.join('\n')
  }

  // 生成混淆前后对比报告
  generateComparisonReport(crashLog: string): string {
    const lines = crashLog.split('\n')
    const report: string[] = ['混淆前后对比报告', '='.repeat(60)]

    for (const line of lines) {
      if (line.trim().startsWith('at ')) {
        const decoded = this.decodeStackLine(line)
        report.push(`原始: ${line.trim()}`)
        report.push(`还原: at ${decoded.className}.${decoded.methodName} (${decoded.fileName}:${decoded.lineNumber})`)
        report.push('-'.repeat(40))
      }
    }

    return report.join('\n')
  }
}

// 使用示例：还原崩溃日志
function decodeCrashLog() {
  const decoder = new StackTraceDecoder()
  
  // 加载SourceMap
  decoder.loadSourceMap('/path/to/entry/build/default/outputs/default/entry-default-signed.hap.map')

  // 模拟混淆后的崩溃日志
  const obfuscatedLog = `
Error: TypeError: Cannot read property 'a' of undefined
    at a.b.c (entry/ets/pages/Index.abc:42:15)
    at d.e.f (entry/ets/pages/Index.abc:38:22)
    at g.h (entry/ets/models/UserManager.abc:156:8)
  `

  // 还原
  const decodedLog = decoder.decodeCrashLog(obfuscatedLog)
  console.info(decodedLog)

  // 生成对比报告
  const report = decoder.generateComparisonReport(obfuscatedLog)
  console.info(report)
}

四、踩坑与注意事项

坑点1：混淆后JSON序列化/反序列化失败

这是最常见的混淆坑。你的数据类UserProfile有个属性叫userName，混淆后变成了a。当你把对象序列化为JSON发送给服务器时，字段名变成了a，服务器不认识；当服务器返回userName字段时，反序列化也找不到对应的属性。解决方案：所有参与序列化的属性名必须加入-keep-property-name白名单。

坑点2：HSP模块的导出名称被混淆

HSP模块对外暴露的接口名如果被混淆，使用方就无法通过名称引用这些接口。比如HSP导出了UserManager类，混淆后变成了a，外部模块的import { UserManager } from 'library'就会报错。HSP模块必须使用-keep-global-name保留所有导出的名称，或者在consumer-rules.txt中声明消费者规则。

坑点3：动态路由页面文件名被混淆

HarmonyOS的路由系统通过文件路径加载页面，如router.pushUrl({ url: 'pages/DetailPage' })。如果启用了文件名混淆，DetailPage可能变成a3，路由跳转就会失败。所有参与路由跳转的页面文件名必须加入-keep-file-name白名单。

坑点4：混淆规则文件编码问题

obfuscation-rules.txt文件必须使用UTF-8编码保存。如果你的编辑器默认使用了GBK或其他编码，中文字符可能被错误解析，导致规则失效甚至构建失败。务必确认文件编码为UTF-8 without BOM。

坑点5：consumer-rules.txt与obfuscation-rules.txt的优先级混淆

很多开发者搞不清这两个文件的关系。简单来说：obfuscation-rules.txt是"我自己的混淆规则"，consumer-rules.txt是"我告诉引用方应该保留什么"。当一个HSP模块被其他模块引用时，引用方会自动应用HSP的consumer-rules.txt。如果你在HSP的obfuscation-rules.txt中写了keep规则，引用方是看不到的——必须写在consumer-rules.txt中。

坑点6：混淆后第三方SDK崩溃

第三方SDK通常依赖特定的类名和属性名进行反射调用。如果你的应用启用了混淆但忘记保留SDK需要的名称，SDK运行时就会崩溃。务必查阅每个第三方SDK的混淆要求，将它们指定的保留规则添加到你的混淆配置中。

坑点7：SourceMap文件丢失导致无法还原

SourceMap文件是混淆还原的唯一依据。如果SourceMap丢失，崩溃日志将永远无法还原到原始代码。每次Release构建后，务必将SourceMap文件备份到安全位置，并标注对应的版本号。建议在CI/CD流水线中自动备份SourceMap。

五、HarmonyOS 6适配说明

API差异表

行为变更

1. 默认混淆策略变更：HarmonyOS 6在创建新项目时，Release构建默认启用名称混淆和文件名混淆。开发者需要显式配置keep规则，而不是显式启用混淆。

2. 跨模块混淆一致性：当主模块和HSP模块同时启用混淆时，HarmonyOS 6确保跨模块引用的名称保持一致，避免了之前版本中"主模块混淆了但HSP没混淆"导致的运行时错误。

3. 新增字符串加密：-enable-string-encryption选项会对代码中的常量字符串进行加密，运行时解密。这进一步增加了逆向分析的难度，但也会带来微小的性能开销。

适配代码

// HarmonyOS 6混淆规则 - obfuscation-rules.txt

# 启用所有混淆选项
-enable-property-obfuscation
-enable-toplevel-obfuscation
-enable-filename-obfuscation
-enable-export-obfuscation
-compact

# HarmonyOS 6新增：字符串加密
-enable-string-encryption

# HarmonyOS 6新增：保留全局名称
-keep-global-name
EntryAbility
MainAbility

# HarmonyOS 6新增：保留动态加载类名
-keep-class-name
DynamicModuleLoader
PluginManager

# 保留序列化属性
-keep-property-name
userId
userName
token
avatarUrl
nickName

// HarmonyOS 6消费者规则 - consumer-rules.txt（HSP模块）
# 告知引用方必须保留的名称

-keep-global-name
MyLibrary
MyService
MyHelper

-keep-property-name
initialize
configure
execute

六、总结

三维度评价表

代码混淆不是"配完就忘"的工作，而是需要持续维护的配置。每次新增序列化类、引入第三方SDK、添加路由页面，都要同步更新混淆规则。建议在代码审查流程中加入混淆规则检查项，确保每次变更都不会遗漏keep规则。混淆做得好，代码安全有保障；混淆做得差，线上崩溃满天飞——选择权在你手中。