打包发布与签名配置本文是《HarmonyOS NEXT 企业级开发实战30篇打造智能记账APP》系列的第28篇对应 Git Tagv0.2.8。本篇聚焦 HarmonyLedger 的打包发布流程重点讲解obfuscation-rules.txt混淆规则文件、entry/build-profile.json5构建配置、实际编译命令与输出以及编译过程中常见的错误排查方案。前言当应用开发完成进入发布阶段时打包编译是最后一道关卡。很多开发者在 Debug 模式下一路畅通切换到 Release 编译时却遇到各种莫名其妙的错误混淆规则文件缺失、签名未配置、daemon 锁文件冲突……这些问题往往不是因为代码逻辑有误而是构建配置不完整导致的。本文将带你理解entry/build-profile.json5中obfuscation混淆配置的作用创建并配置obfuscation-rules.txt混淆规则文件使用 hvigor 命令行完成实际编译打包排查编译过程中的常见错误掌握 Release 签名配置与产物验证企业级核心原则发布构建必须可复现、可追溯、零警告。任何编译错误都应在 CI/CD 阶段拦截绝不能带到应用市场。参考 HarmonyOS NEXT 开发者文档 了解官方约定。一、需求分析1.1 功能介绍HarmonyLedger 的打包发布需要完成以下工作需求项说明核心目标通过 hvigor 命令行编译生成 HAP 产物混淆配置配置obfuscation-rules.txt当前阶段enable: false签名配置Debug 阶段无需签名Release 阶段需配置证书材料构建产物entry/build/default/outputs/default/下的 HAP 文件验收标准编译成功输出BUILD SUCCESSFUL1.2 构建流程开发者执行 hvigor 命令 ↓ hvigor 读取 build-profile.json5 配置 ↓ 检查 obfuscation-rules.txt 文件是否存在 ↓ 编译 ArkTS 源码 → 生成 ABC 字节码 ↓ 打包资源文件 → 生成 HAP ↓ Release 模式签名 HAP ↓ 输出构建结果1.3 构建模式对比构建模式混淆签名用途debug不启用可选本地调试与模拟器运行release可配置必须上架发布与真机测试关键提示即使混淆enable: falseobfuscation-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 配置项说明配置项值说明apiTypestageMode应用模型HarmonyOS NEXT 仅支持 Stage 模型buildOption.resOptions.copyCodeResource.enablefalse是否复制代码资源buildOptionSet[0].namerelease构建模式名称arkOptions.obfuscation.ruleOptions.enablefalse是否启用代码混淆arkOptions.obfuscation.ruleOptions.files[./obfuscation-rules.txt]混淆规则文件路径targetsdefault,ohosTest构建目标列表2.3 obfuscation 配置解读obfuscation配置块是 Release 构建的核心它决定了 ArkTS 代码在编译时是否进行混淆优化obfuscation: { ruleOptions: { enable: false, // 当前阶段关闭混淆 files: [./obfuscation-rules.txt] // 规则文件路径必须存在 } }重要约束files数组中声明的文件路径是相对于entry/目录的。即使enable: falsehvigor 在编译时仍会检查这些文件是否存在。文件缺失会导致编译直接失败。三、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-daemon4.2 命令参数说明参数说明node使用 Node.js 执行 hvigor 脚本/Applications/DevEco-Studio.app/.../hvigor.jshvigor 构建脚本完整路径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 988ms4.4 构建产物编译成功后HAP 产物位于以下路径entry/build/default/outputs/default/ ├── entry-default-signed.hap # 签名后的 HAP如有签名配置 └── entry-default-unsigned.hap # 未签名的 HAP4.5 编译耗时分析阶段耗时说明配置加载~0.5s读取 build-profile.json5依赖解析~1s解析 oh-package.json5ArkTS 编译~2s编译 .ets → ABC 字节码资源打包~1s打包 resources mediaHAP 生成~0.5s生成最终产物总计~5s首次编译略长增量编译更快五、工程级 build-profile.json55.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 平台申请.p7bProfile描述文件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-ncom.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 目录下创建混淆规则文件touchentry/obfuscation-rules.txt# 写入占位内容echo# HarmonyLedger 混淆规则entry/obfuscation-rules.txt7.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本地未安装对应 SDKDevEco Studio → SDK Manager 安装version mismatch配置版本与本地 SDK 不一致修改compatibleSdkVersion7.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 founddaemon 锁冲突删除锁文件或用--no-daemon-SDK not foundSDK 未安装SDK Manager 安装-Duplicate resource资源同名冲突删除重复资源-Cannot find name XXXArkTS 编译错误检查 import 与类型声明八、发布检查清单8.1 发布前检查上架应用市场前务必逐项检查以下内容obfuscation-rules.txt文件存在且内容正确entry/build-profile.json5配置完整Release 签名配置正确无 WARNversionCode/versionName已更新CHANGELOG.md已更新敏感信息已移除密钥、密码、调试日志.gitignore包含签名文件应用图标与启动屏适配完成所有页面无白屏崩溃深色模式全适配权限声明完整8.2 编译产物验证验证项命令/方法预期结果编译成功hvigor.js assembleApp --no-daemonBUILD SUCCESSFULHAP 生成ls entry/build/default/outputs/default/存在.hap文件签名验证hdc shell bm dump -n bundleName包含签名信息安装测试hdc install hap-path安装成功九、Git 提交9.1 提交混淆规则文件gitaddentry/obfuscation-rules.txtgitaddentry/build-profile.json5gitcommit-mbuild: 添加混淆规则文件与构建配置 - 创建 obfuscation-rules.txt 占位文件 - 配置 entry/build-profile.json5 obfuscation ruleOptions - 修复 Release 编译混淆文件缺失错误9.2 版本打标gittag-av0.2.8-mv0.2.8 打包发布与签名配置gitpush origin v0.2.89.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.8HarmonyOS NEXT 文档developer.harmonyos.comDevEco Studio 打包deveco-buildhvigor 构建工具hvigor代码混淆指南obfuscation鸿蒙应用市场app-galleryHarmonyLedger 仓库GitHub