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

【OpenHarmony/HarmonyOS】从 Debug 到 ReleaseHvigor 构建、签名、混淆与敏感配置治理应用能在模拟器运行不代表已经具备发布条件。本文以 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.json5AppScope/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 任务体系根工程使用appTasksentry 模块使用hapTasksimport{ appTasks }fromohos/hvigor-ohos-plugin;exportdefault {system: appTasks, plugins: [] };import{ hapTasks }fromohos/hvigor-ohos-plugin;exportdefault {system: hapTasks, plugins: [] };构建前应锁定依赖、确认 SDK 和 Node 环境再分别验证 Debug 与 Release。Release 构建启用混淆后可能出现只在发布包中的问题因此不能用 Debug 成功代替 Release 验证。四、签名材料绝不能硬编码在仓库 签名通常涉及.p12密钥库.cer证书.p7bProfilekeyAliasstorePassword 和 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应用签名安全发布