【OpenHarmony/HarmonyOS】从 Debug 到 Release：Hvigor 构建、签名、混淆与敏感配置治理-二趣网

【OpenHarmony/HarmonyOS】从 Debug 到 Release：Hvigor 构建、签名、混淆与敏感配置治理

应用能在模拟器运行，不代表已经具备发布条件。本文以 HarmonyOS Stage 工程为例，梳理产品配置、HAP 构建、签名、混淆和密钥治理，并特别说明哪些内容绝不能进入仓库或技术文章。📦

一、认识应用级与模块级配置

应用级build-profile.json5定义产品、SDK、签名和模块：

{"app": {"products": [ {"name":"default","targetSdkVersion":"6.0.0(20)","compatibleSdkVersion":"6.0.0(20)","runtimeOS":"HarmonyOS"}, {"name":"release","targetSdkVersion":"6.0.0(20)","runtimeOS":"HarmonyOS"} ],"buildModeSet": [ {"name":"debug"}, {"name":"release"} ] } }

模块级entry/build-profile.json5声明 Stage 模型、构建目标和 Release 混淆：

{"apiType":"stageMode","buildOptionSet": [ {"name":"release","arkOptions": {"obfuscation": {"ruleOptions": {"enable": true,"files": ["./obfuscation-rules.txt"] } } } } ] }

应用级回答“构建哪个产品并如何签名”，模块级回答“entry 模块如何编译和打包”。

二、AppScope 与 module.json5

AppScope/app.json5保存 Bundle Name 和版本：

{"app": {"bundleName":"tan.ke.chongji","versionCode": 1000001,"versionName":"1.0.1","icon":"$media:app_icon","label":"$string:app_name"} }

module.json5则配置 EntryAbility、手机/平板、横屏、页面列表、权限和备份扩展。发布前需要检查：

versionCode单调递增；
versionName与发布说明一致；
Bundle Name 与控制台应用一致；
只声明实际使用的权限；
图标、名称和启动背景使用 Release 资源；
备份内容符合隐私与业务预期。

三、Hvigor 任务体系

根工程使用appTasks，entry 模块使用hapTasks：

import{ appTasks }from'@ohos/hvigor-ohos-plugin';exportdefault {system: appTasks, plugins: [] };

import{ hapTasks }from'@ohos/hvigor-ohos-plugin';exportdefault {system: hapTasks, plugins: [] };

构建前应锁定依赖、确认 SDK 和 Node 环境，再分别验证 Debug 与 Release。Release 构建启用混淆后可能出现只在发布包中的问题，因此不能用 Debug 成功代替 Release 验证。

四、签名材料绝不能硬编码在仓库 🔐

签名通常涉及：

.p12密钥库；
.cer证书；
.p7bProfile；
keyAlias；
storePassword 和 keyPassword。

这些内容不应以明文或可逆密文直接提交到项目配置，更不能出现在 CSDN 代码截图中。即使密码看似经过编码，只要构建工具能直接读取，它仍属于凭据。

安全做法包括：

本地开发签名放在用户目录，不入库；
CI 使用密钥管理服务或受保护变量临时注入；
仓库只保留不含秘密的模板配置；
.gitignore排除证书、密钥库和本地 Profile；
日志对路径和凭据脱敏；
泄漏后立即吊销/轮换，而不是仅删除历史当前版本。

如果秘密曾进入 Git 历史，仅在最新提交删除并不够，旧提交仍可访问。需要按组织流程轮换密钥并清理历史。

五、开发配置与发布配置分离

推荐使用占位或环境注入：

{"name":"release","type":"HarmonyOS","material": {"certpath":"${RELEASE_CERT_PATH}","profile":"${RELEASE_PROFILE_PATH}","storeFile":"${RELEASE_STORE_FILE}"} }

具体变量机制应按 DevEco Studio/Hvigor 当前版本支持方式配置。重点是源码仓库不保存真实秘密。

还应为 Debug/Release 提供不同能力开关：

DEBUG:模拟设备发现、调试信息、性能面板、详细日志RELEASE:关闭模拟设备、关闭调试 HUD、日志脱敏、启用混淆

当前 P2P 会无条件添加模拟设备，发布前应纳入这一开关。

六、混淆不是安全边界

ArkTS Release 混淆可以提高反编译阅读成本、减小部分符号暴露，但不能保护硬编码 Token、短信密钥或签名密码。客户端拥有的秘密最终都可能被提取。

混淆后需重点验证：

反射或字符串引用的类名是否保留；
JSON 字段是否因重命名导致协议不兼容；
WebView、路由页面名和资源名是否正常；
第三方 SDK 要求的 keep 规则；
云数据库对象模型的字段映射；
日志和堆栈是否保留可排障能力。

七、依赖清单要保持单一且合法

根oh-package.json5中不应出现重复的dependencies键。JSON5 解析器可能采用最后一个值，导致前一个依赖块被静默覆盖。发布前应运行依赖解析和锁文件校验。

还要确认：

根工程与 entry 的 Hypium 版本是否有意不同；
声明的 Lottie 是否实际使用；
AGC Auth 依赖是否真的集成到 entry；
未使用依赖是否移除以减少包体和供应链风险；
锁文件与配置一致。

八、资源和包体治理

项目包含多份 WAV、图片和多语言资源。发布前检查：

大图是否压缩到合适尺寸；
BGM 是否使用适合的编码和码率；
未引用资源是否移除；
AppScope 与 entry 是否重复放置可合并资源；
启动图标在不同设备清晰；
文件名避免临时后缀和重复配置，例如带(1)的服务配置文件。

音频与 6MB 级图标很容易成为包体主要来源，优化收益通常比压缩几 KB ArkTS 更高。

九、发布日志必须脱敏

Release 包中不应输出：

用户手机号、OpenID、Token；
完整局域网 IP 与设备名；
云配置对象；
签名路径和证书信息；
用户头像 URI；
完整异常对象中可能包含的请求内容。

建议封装日志级别，Release 只保留必要错误码和匿名会话 ID。

十、发布前质量门禁 ✅

Debug 和 Release 均能干净构建；
单元测试、ohosTest 和关键真机流程通过；
所有语言资源完整；
模拟设备与调试 HUD 已关闭；
权限与隐私政策一致；
签名秘密不在仓库、产物日志和文章中；
混淆包完成启动、路由、游戏、结算测试；
包体、内存、启动时间和帧率达到目标；
弱网、无网、音频失败和存储损坏可降级；
版本号、图标、应用名和发布说明正确。

十一、产物管理

构建产物不应与源码混在一起长期提交。CI 可以：

为每次 Release 生成带版本和提交号的产物名；
保存 HAP/App、符号映射和测试报告；
对产物计算 SHA-256；
设置保留期限与访问权限；
记录使用的 SDK、依赖锁文件和签名证书版本。

这样出现线上问题时才能重建完全一致的包。

十二、总结 ✨

HarmonyOS 工程从可运行到可发布，需要补齐一整套工程边界：

理解应用级和模块级构建配置；
同时验证 Debug 与 Release；
版本、权限、资源和路由保持一致；
签名凭据通过安全渠道注入；
混淆只用于代码保护，不能替代秘密治理；
Debug 模拟能力必须在 Release 关闭；
依赖、包体、日志和产物都纳入门禁。

发布工程最重要的原则很朴素：凡是进入客户端、仓库、日志或文章的内容，都要假设最终可能被公开看到。📦

推荐标签：HarmonyOSOpenHarmonyHvigorHAP应用签名安全发布

企业官网建设流程全解析