HarmonyOS NEXT 企业级记账APP：打包发布与签名配置

打包发布与签名配置

本文是《HarmonyOS NEXT 企业级开发实战：30篇打造智能记账APP》系列的第28篇，对应 Git Tagv0.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 的打包发布需要完成以下工作：

1.2 构建流程

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

1.3 构建模式对比

关键提示：即使混淆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 配置项说明

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 混淆规则文件状态

最佳实践：无论是否启用混淆，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 命令参数说明

为什么用--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 编译耗时分析

五、工程级 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 工程级与模块级配置对比

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

六、Release 签名配置

6.1 签名材料准备

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

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-ncom.example.harmonyledger

七、编译常见错误排查

7.1 混淆规则文件缺失

这是最常见的编译错误：

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

修复命令：

# 在 entry 目录下创建混淆规则文件touchentry/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.

7.5 资源文件冲突

ERROR: Duplicate resource: icon_add

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

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

7.6 常见错误速查表

八、发布检查清单

8.1 发布前检查

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

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

8.2 编译产物验证

九、Git 提交

9.1 提交混淆规则文件

gitaddentry/obfuscation-rules.txtgitaddentry/build-profile.json5gitcommit-m"build: 添加混淆规则文件与构建配置 - 创建 obfuscation-rules.txt 占位文件 - 配置 entry/build-profile.json5 obfuscation ruleOptions - 修复 Release 编译混淆文件缺失错误"

9.2 版本打标

gittag-av0.2.8-m"v0.2.8 打包发布与签名配置"gitpush 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