Release 构建——从混淆到 HAR 发布

一、Release 构建与 Debug 构建的区别

在 Hvigor 构建系统中，buildModeSet 定义了两种构建模式：

"buildModeSet": [
  { "name": "debug" },
  { "name": "release" }
]

Debug 构建：

• 无代码混淆
• 无资源压缩
• 包含调试符号
• 构建速度快
• 包体积大

Release 构建：

• 启用代码混淆
• 资源压缩优化
• 移除调试符号和日志
• 构建速度慢（需要混淆处理）
• 包体积小

Release 构建是发布到应用市场的必要步骤。未经混淆和压缩的包体积过大，不符合应用市场上架要求。

二、obfuscation-rules.txt 混淆规则

混淆配置在每个模块的 obfuscation-rules.txt 文件中。以 commonLib 模块为例：

# Obfuscation options:
# -disable-obfuscation: disable all obfuscations
# -enable-property-obfuscation: obfuscate the property names
# -enable-toplevel-obfuscation: obfuscate the names in the global scope
# -compact: remove unnecessary blank spaces and all line feeds
# -remove-log: remove all console.* statements
# -print-namecache: print the name cache that contains the mapping from old names to new names
# -apply-namecache: reuse the given cache file

# Keep options:
# -keep-property-name: specifies property names that you want to keep
# -keep-global-name: specifies names that you want to keep in the global scope

-enable-property-obfuscation
-enable-toplevel-obfuscation
-enable-filename-obfuscation
-enable-export-obfuscation

规则说明：

选项	说明	效果
-enable-property-obfuscation	混淆属性名	wordCardPage → a
-enable-toplevel-obfuscation	混淆顶层名称	WordCardPage → b
-enable-filename-obfuscation	混淆文件名	WordCardPage.ets → a.ets
-enable-export-obfuscation	混淆导出名	export function 名称变化
-compact	压缩代码	移除空格和换行
-remove-log	移除日志	删除所有 Logger/console 调用
-print-namecache	输出名称映射	用于调试错误堆栈

Keep 选项的使用场景：

某些类名或属性名不能混淆，因为它们需要被外部引用（如通过路由字符串导航）：

# 保留路由枚举值
-keep-global-name RouterMap
-keep-global-name MAIN_PAGE
-keep-global-name WORD_CARD_PAGE

混淆后的应用，如果出现崩溃，错误堆栈中的类名和函数名会被混淆（如变成 a、b、c）。因此需要保存每一次 Release 构建的 namecache 文件，用于反混淆分析崩溃日志。

三、Release 模式的资源压缩

在 Release 构建中，Hvigor 会自动对资源文件进行压缩：

1. PNG 压缩：使用有损/无损算法减少 PNG 文件大小
2. JSON 最小化：移除 JSON 文件中的空格和注释
3. 资源去重：合并相同内容的资源文件
4. 无用资源移除：自动移除未被引用的资源文件

资源压缩的效果通常在 20-50% 之间，具体取决于项目中图片资源的数量和类型。将 PNG 替换为 WebP 后，压缩率更高。

四、buildModeSet 的配置

buildModeSet 定义了哪些构建模式可用，以及每个模式的配置：

"buildModeSet": [
  {
    "name": "debug"
  },
  {
    "name": "release"
  }
]

在 DevEco Studio 中选择构建模式：

• Build → Build Hap(s)/APP(s) → Debug：debug 模式
• Build → Build Hap(s)/APP(s) → Release：release 模式

在命令行中选择构建模式：

# Debug 构建
hvigorw assembleHap --mode debug

# Release 构建
hvigorw assembleHap --mode release

五、HAR 包的发布流程

HAR（HarmonyOS Archive）包是模块的静态共享包。在 11 模块架构中，commonLib 可以发布为 HAR 包供其他项目使用。

HAR 包的构建：

hvigorw assembleHar --mode release

构建产物位于：

commons/commonLib/build/default/outputs/default/commonLib.har

HAR 包的发布步骤：

1. 版本号管理：在 oh-package.json5 中更新版本号
2. 混淆配置：确保混淆规则正确，公共 API 被保留
3. 构建：执行 release 模式的 HAR 构建
4. 测试验证：使用生成的 .har 文件测试引用项目
5. 发布：将 .har 文件上传到内部仓库或华为应用市场

HAR 包的引用方式：

// 方式一：本地文件引用
"commonlib": "file:../../commons/commonLib"

// 方式二：远程仓库引用
"commonlib": "npm:@scope/commonlib@1.0.0"

六、混淆后的调试技巧

混淆后的应用在调试时会遇到挑战。以下是常用的调试技巧：

1. 保留名称映射文件

在混淆规则中添加：

-print-namecache ./build/namecache.txt

构建后，namecache.txt 包含了混淆前后的名称映射，用于反混淆堆栈信息。

2. 仅对 Release 混淆

使用条件配置，在 Debug 模式下禁用混淆（在 hvigorfile.ts 中配置）。

3. 保留特定类不混淆

对于需要反射调用的类、路由枚举、序列化模型，使用 -keep-* 规则保留。

4. 日志处理

-remove-log 规则会删除所有 Logger 调用。如果需要在 Release 版本中保留某些日志（如崩溃采集日志），可以使用条件日志库。

七、总结

Release 构建是从开发到发布的关键步骤。在 11 模块架构中，obfuscation-rules.txt 控制了代码混淆的粒度，资源压缩减小了包体积，buildModeSet 隔离了开发和发布配置。HAR 包的发布流程为模块复用提供了标准化路径。正确理解和配置混淆规则，确保关键 API 不被混淆，是 Release 构建成功的保障。