打包发布与签名配置

本文是《HarmonyOS NEXT 企业级开发实战：30篇打造智能记账APP》系列的第 28 篇，对应 Git Tag v0.2.8。本篇聚焦 HarmonyLedger 的打包发布流程，重点讲解 obfuscation-rules.txt 混淆规则文件、entry/build-profile.json5 构建配置、实际编译命令与输出，以及编译过程中常见的错误排查方案。

前言

当应用开发完成进入发布阶段时，打包编译 是最后一道关卡。很多开发者在 Debug 模式下一路畅通，切换到 Release 编译时却遇到各种莫名其妙的错误：混淆规则文件缺失、签名未配置、daemon 锁文件冲突……这些问题往往不是因为代码逻辑有误，而是构建配置不完整导致的。

本文将带你：

1. 理解 entry/build-profile.json5 中 obfuscation 混淆配置的作用
2. 创建并配置 obfuscation-rules.txt 混淆规则文件
3. 使用 hvigor 命令行完成实际编译打包
4. 排查编译过程中的常见错误
5. 掌握 Release 签名配置与产物验证

企业级核心原则：发布构建必须 可复现、可追溯、零警告。任何编译错误都应在 CI/CD 阶段拦截，绝不能带到应用市场。参考 HarmonyOS NEXT 开发者文档 了解官方约定。

---

一、需求分析

1.1 功能介绍

HarmonyLedger 的打包发布需要完成以下工作：

需求项	说明
核心目标	通过 hvigor 命令行编译生成 HAP 产物
混淆配置	配置 obfuscation-rules.txt，当前阶段 enable: false
签名配置	Debug 阶段无需签名，Release 阶段需配置证书材料
构建产物	entry/build/default/outputs/default/ 下的 HAP 文件
验收标准	编译成功输出 BUILD SUCCESSFUL

1.2 构建流程

开发者执行 hvigor 命令
  ↓
hvigor 读取 build-profile.json5 配置
  ↓
检查 obfuscation-rules.txt 文件是否存在
  ↓
编译 ArkTS 源码 → 生成 ABC 字节码
  ↓
打包资源文件 → 生成 HAP
  ↓
（Release 模式）签名 HAP
  ↓
输出构建结果

1.3 构建模式对比

构建模式	混淆	签名	用途
debug	不启用	可选	本地调试与模拟器运行
release	可配置	必须	上架发布与真机测试

关键提示：即使混淆 enable: false，obfuscation-rules.txt 文件也必须存在，否则编译会报错。这是最常见的打包坑点之一。

---

二、entry/build-profile.json5 配置详解

2.1 完整配置文件

entry/build-profile.json5 是主模块的构建配置文件，HarmonyLedger 的实际配置如下：

// entry/build-profile.json5
{
  "apiType": "stageMode",
  "buildOption": {
    "resOptions": {
      "copyCodeResource": {
        "enable": false
      }
    }
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      }
    }
  ],
  "targets": [
    {
      "name": "default"
    },
    {
      "name": "ohosTest"
    }
  ]
}

2.2 配置项说明

配置项	值	说明
apiType	stageMode	应用模型，HarmonyOS NEXT 仅支持 Stage 模型
buildOption.resOptions.copyCodeResource.enable	false	是否复制代码资源
buildOptionSet[0].name	release	构建模式名称
arkOptions.obfuscation.ruleOptions.enable	false	是否启用代码混淆
arkOptions.obfuscation.ruleOptions.files	["./obfuscation-rules.txt"]	混淆规则文件路径
targets	default, ohosTest	构建目标列表

2.3 obfuscation 配置解读

obfuscation 配置块是 Release 构建的核心，它决定了 ArkTS 代码在编译时是否进行混淆优化：

"obfuscation": {
  "ruleOptions": {
    "enable": false,           // 当前阶段关闭混淆
    "files": ["./obfuscation-rules.txt"]  // 规则文件路径（必须存在）
  }
}

重要约束：files 数组中声明的文件路径是相对于 entry/ 目录的。即使 enable: false，hvigor 在编译时仍会检查这些文件是否存在。文件缺失会导致编译直接失败。

---

三、obfuscation-rules.txt 混淆规则文件

3.1 文件缺失导致的编译错误

当 entry/build-profile.json5 中声明了 "files": ["./obfuscation-rules.txt"] 但实际文件不存在时，执行编译会报如下错误：

ERROR: The obfuscation rule file './obfuscation-rules.txt' cannot be found.

> hvigor task failed.

这个错误信息非常明确：hvigor 在处理 Release 构建配置时，尝试加载 obfuscation-rules.txt 文件但找不到它。解决方法就是在 entry/ 目录下创建该文件。

3.2 创建混淆规则文件

在 entry/ 目录下创建 obfuscation-rules.txt 文件。由于当前阶段混淆已关闭（enable: false），文件内容可以是简单的占位注释：

# HarmonyLedger 混淆规则
# 目前 obfuscation enable: false，此文件为占位
# 启用混淆时在此添加保留规则

3.3 混淆规则语法（预留）

当后续版本启用混淆（enable: true）时，需要在 obfuscation-rules.txt 中添加保留规则，防止关键类名/方法名被混淆。HarmonyOS 的混淆规则语法借鉴了 ProGuard：

# HarmonyLedger 混淆规则（启用混淆时使用）

# 保留所有数据模型类（序列化需要反射）
-keep class com.example.harmonyledger.model.** { *; }

# 保留 Repository 类（单例方法名不能混淆）
-keep class com.example.harmonyledger.repository.** { *; }

# 保留 @Entry @Component 装饰的 struct（框架反射调用）
-keep @Entry @Component class * { *; }

# 保留 EntryAbility（模块入口）
-keep class com.example.harmonyledger.EntryAbility { *; }

3.4 混淆规则文件状态

状态	enable	文件内容	文件是否存在	编译结果
当前阶段	false	占位注释	必须存在	成功
启用混淆	true	保留规则	必须存在	成功
文件缺失	任意	无	不存在	失败

最佳实践：无论是否启用混淆，obfuscation-rules.txt 文件都应在项目初始化阶段创建并纳入版本控制。这样团队成员切换到 Release 构建时不会遇到文件缺失错误。

---

四、实际编译命令与输出

4.1 编译命令

HarmonyLedger 使用 DevEco Studio 内置的 hvigor 构建工具进行命令行编译。实际编译命令如下：

node /Applications/DevEco-Studio.app/Contents/tools/hvigor/hvigor/bin/hvigor.js assembleApp --no-daemon

4.2 命令参数说明

参数	说明
node	使用 Node.js 执行 hvigor 脚本
/Applications/DevEco-Studio.app/.../hvigor.js	hvigor 构建脚本完整路径
assembleApp	构建任务名，编译整个应用
--no-daemon	禁用 daemon 模式，避免锁文件冲突

为什么用 --no-daemon：在 CI/CD 环境或频繁切换项目时，hvigor daemon 可能残留锁文件导致下一次编译卡死。使用 --no-daemon 确保每次编译都是独立进程，避免锁冲突。

4.3 编译成功输出

编译成功时的实际输出如下：

> hvigor version: 5.0.0
> hvigor assembleApp: starting...
> hvigor assembleApp: success
> hvigor BUILD SUCCESSFUL in 5s 988ms

4.4 构建产物

编译成功后，HAP 产物位于以下路径：

entry/build/default/outputs/default/
├── entry-default-signed.hap      # 签名后的 HAP（如有签名配置）
└── entry-default-unsigned.hap    # 未签名的 HAP

4.5 编译耗时分析

阶段	耗时	说明
配置加载	~0.5s	读取 build-profile.json5
依赖解析	~1s	解析 oh-package.json5
ArkTS 编译	~2s	编译 .ets → ABC 字节码
资源打包	~1s	打包 resources + media
HAP 生成	~0.5s	生成最终产物
总计	~5s	首次编译略长，增量编译更快

---

五、工程级 build-profile.json5

5.1 工程根目录配置

除了模块级的 entry/build-profile.json5，工程根目录还有一份 build-profile.json5，负责工程级构建配置：

// build-profile.json5（工程根目录）
{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
        "targetSdkVersion": "6.1.1(24)"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    }
  ]
}

5.2 工程级与模块级配置对比

配置项	工程级	模块级
位置	工程根目录	entry/ 目录
职责	SDK 版本、签名、产物模式	混淆、资源选项、构建目标
signingConfigs	在此配置	引用工程级配置
buildModeSet	定义 debug/release	引用并扩展
obfuscation	不配置	在此配置

配置层级：工程级 build-profile.json5 定义全局构建策略，模块级 entry/build-profile.json5 定义模块特定配置。两者协同工作，模块级配置继承并覆盖工程级配置。

---

六、Release 签名配置

6.1 签名材料准备

上架应用市场前需要配置 Release 签名。签名材料包括：

材料	说明	获取方式
.cer 证书	开发者证书	AGC 平台申请
.p7b Profile	描述文件	AGC 平台申请
.p12 密钥库	密钥存储文件	DevEco Studio 生成
storePassword	密钥库密码	生成时设置
keyPassword	密钥密码	生成时设置

6.2 签名配置示例

在工程级 build-profile.json5 的 signingConfigs 中配置签名材料：

{
  "app": {
    "signingConfigs": [
      {
        "name": "release",
        "material": {
          "certpath": "./signature/release.cer",
          "storePassword": "${STORE_PASSWORD}",
          "keyAlias": "HarmonyLedger",
          "keyPassword": "${KEY_PASSWORD}",
          "profile": "./signature/HarmonyLedger.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "./signature/release.p12"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "release",
        "compatibleSdkVersion": "5.0.0(12)"
      }
    ]
  }
}

安全提示：密码不应硬编码在配置文件中。推荐使用环境变量 ${STORE_PASSWORD} 引用，并将 .p12、.cer、.p7b 文件加入 .gitignore。

6.3 签名验证

签名配置完成后，编译生成的 HAP 文件包含数字签名。可通过以下命令验证：

# 查看签名信息
hdc shell bm dump -n com.example.harmonyledger

---

七、编译常见错误排查

7.1 混淆规则文件缺失

这是最常见的编译错误：

ERROR: The obfuscation rule file './obfuscation-rules.txt' cannot be found.

错误现象	原因	解决方案
obfuscation-rules.txt cannot be found	文件不存在	在 entry/ 目录创建该文件
obfuscation file path invalid	路径错误	确认路径相对于 entry/ 目录

修复命令：

# 在 entry 目录下创建混淆规则文件
touch entry/obfuscation-rules.txt
# 写入占位内容
echo "# HarmonyLedger 混淆规则" > entry/obfuscation-rules.txt

7.2 签名未配置警告

Release 编译时如果未配置签名，会输出 WARN 但不阻断编译：

WARN: signingConfigs is empty, the HAP will be unsigned.

说明：此警告在本地测试阶段可以忽略，未签名的 HAP 可通过 hdc install 安装到调试设备。但上架应用市场时必须配置有效签名。

7.3 daemon 锁文件冲突

当 hvigor daemon 异常退出时，可能残留锁文件导致下次编译卡死：

ERROR: Another hvigor daemon is running.
ERROR: Lock file found: .hvigor/daemon.lock

修复方案：

# 方案一：使用 --no-daemon 参数绕过
node /Applications/DevEco-Studio.app/Contents/tools/hvigor/hvigor/bin/hvigor.js assembleApp --no-daemon

# 方案二：删除锁文件
rm -f .hvigor/daemon.lock

# 方案三：清理整个 hvigor 缓存
rm -rf .hvigor/

7.4 SDK 版本不匹配

ERROR: compatibleSdkVersion '5.0.0(12)' is not supported.

错误现象	原因	解决方案
SDK not found	本地未安装对应 SDK	DevEco Studio → SDK Manager 安装
version mismatch	配置版本与本地 SDK 不一致	修改 compatibleSdkVersion

7.5 资源文件冲突

ERROR: Duplicate resource: icon_add

原因：resources/base/media/ 和 resources/dark/media/ 中存在同名资源文件。

解决：确保同一资源名在不同限定词目录中内容一致，或删除重复资源。

7.6 常见错误速查表

错误码	错误信息	根因	解决方案
-	obfuscation-rules.txt cannot be found	混淆规则文件缺失	创建文件
-	signingConfigs is empty	未配置签名	配置签名材料（WARN 不阻断）
-	daemon.lock found	daemon 锁冲突	删除锁文件或用 --no-daemon
-	SDK not found	SDK 未安装	SDK Manager 安装
-	Duplicate resource	资源同名冲突	删除重复资源
-	Cannot find name 'XXX'	ArkTS 编译错误	检查 import 与类型声明

---

八、发布检查清单

8.1 发布前检查

上架应用市场前，务必逐项检查以下内容：

• obfuscation-rules.txt 文件存在且内容正确
• entry/build-profile.json5 配置完整
• Release 签名配置正确（无 WARN）
• versionCode / versionName 已更新
• CHANGELOG.md 已更新
• 敏感信息已移除（密钥、密码、调试日志）
• .gitignore 包含签名文件
• 应用图标与启动屏适配完成
• 所有页面无白屏崩溃
• 深色模式全适配
• 权限声明完整

8.2 编译产物验证

验证项	命令/方法	预期结果
编译成功	hvigor.js assembleApp --no-daemon	BUILD SUCCESSFUL
HAP 生成	ls entry/build/default/outputs/default/	存在 .hap 文件
签名验证	hdc shell bm dump -n <bundleName>	包含签名信息
安装测试	hdc install <hap-path>	安装成功

---

九、Git 提交

9.1 提交混淆规则文件

git add entry/obfuscation-rules.txt
git add entry/build-profile.json5
git commit -m "build: 添加混淆规则文件与构建配置

- 创建 obfuscation-rules.txt 占位文件
- 配置 entry/build-profile.json5 obfuscation ruleOptions
- 修复 Release 编译混淆文件缺失错误"

9.2 版本打标

git tag -a v0.2.8 -m "v0.2.8 打包发布与签名配置"
git push origin v0.2.8

9.3 CHANGELOG

## [v0.2.8] - 2026-07-27
### Added
- entry/obfuscation-rules.txt 混淆规则占位文件
- entry/build-profile.json5 obfuscation ruleOptions 配置
### Fixed
- 修复 Release 编译报错：obfuscation-rules.txt cannot be found
### Notes
- 本篇为系列第 28 篇，对应 v0.2.8
- 混淆当前 enable: false，后续版本按需启用

---

附录：运行效果截图

总结

本文完整介绍了 HarmonyLedger 的 打包发布与签名配置，涵盖 entry/build-profile.json5 混淆配置、obfuscation-rules.txt 规则文件创建、实际编译命令与输出、Release 签名配置、常见编译错误排查等核心内容。通过本篇你可以：

• 理解 obfuscation.ruleOptions 配置的作用与文件路径约束
• 创建 obfuscation-rules.txt 文件解决混淆文件缺失错误
• 使用 hvigor 命令行完成应用编译打包
• 排查 daemon 锁冲突、签名未配置、SDK 不匹配等常见错误
• 完成发布前检查清单与版本打标

下一篇预告：继续推进 HarmonyLedger 系列的源码复盘与后续规划，敬请期待。

---

如果这篇文章对你有帮助，欢迎在下方投票点赞，你的支持是我持续创作的动力！也欢迎收藏关注，不错过后续更新。

---

相关资源

• 本篇源码：GitHub Tag v0.2.8
• HarmonyOS NEXT 文档：developer.harmonyos.com
• DevEco Studio 打包：deveco-build
• hvigor 构建工具：hvigor
• 代码混淆指南：obfuscation
• 鸿蒙应用市场：app-gallery
• HarmonyLedger 仓库：GitHub