HarmonyKit | 鸿蒙开发build-profile.json5 SDK 版本与签名配置详解引言两万个字符的配置五个关键决策HarmonyKit 的配置文件加在一起不到 500 行但背后的决策逻辑远比代码量复杂。build-profile.json5是鸿蒙项目的总控制台——一个配置项的变更就可能影响 HAP 体积、API 可用范围、签名方式、编译警告和上架审核结果。这篇文章以 HarmonyKit 的实际配置为例从项目级到模块级逐层拆解build-profile.json5的每一个配置节点解释在什么场景下应该选择什么配置值以及错误的配置会带来什么后果。项目仓库https://atomgit.com/VON-/harmony-kit配置的三个层级在深入了解每个字段之前先建立全局视角。鸿蒙项目的构建配置分为三个层级层级文件位置作用域项目级./build-profile.json5所有模块共享的签名、产品、构建模式配置模块级./entry/build-profile.json5单个模块的构建选项、混淆规则、target 配置引擎级./hvigor/hvigor-config.json5hvigor 构建引擎本身的行为配置三个层级不是平等的——项目级配置规定可以做什么模块级配置选择怎么做引擎级配置以什么方式做。项目级 build-profile.json5 全解析HarmonyKit 的项目级配置完整如下{ app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.cer, keyAlias: debugKey, keyPassword: 0000001A9C..., profile: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.p7b, signAlg: SHA256withECDSA, storeFile: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.p12, storePassword: 0000001AA1... } } ], products: [ { name: default, signingConfig: default, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 6.0.2(22), runtimeOS: HarmonyOS, buildOption: { strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true } } } ], buildModeSet: [ { name: debug }, { name: release } ] }, modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ] }signingConfigs签名配置数组这个数组可以包含多个签名配置——典型场景是开发调试签名和生产发布签名分离signingConfigs: [ { name: debug, // 开发调试专用签名 type: HarmonyOS, material: { /* 自动生成的调试证书 */ } }, { name: release, // 生产发布专用签名 type: HarmonyOS, material: { /* AppGallery 签发的正式证书 */ } } ]HarmonyKit 目前只有一个default签名配置因为它还没有上架 AppGallery只使用 DevEco Studio 自动生成的调试证书。signingConfigs 的关键配置项解读name签名的逻辑名称被products[].signingConfig引用。type固定为HarmonyOS。material.certpath.cer证书文件的绝对路径。这是公钥证书用于验证签名。material.storeFile.p12密钥库文件路径。包含私钥和证书链是签名操作的核心。material.keyAlias密钥库中密钥的别名。默认debugKey。material.profile.p7bProvisioning Profile 文件路径。描述应用在设备上的运行权限。material.signAlg签名算法。SHA256withECDSA使用 ECDSA 椭圆曲线算法配合 SHA-256 哈希。material.keyPassword / storePassword密钥和密钥库的密码。调试证书的密码是固定的、自动生成的生产证书的密码需要自己保管。安全提醒keyPassword和storePassword是敏感信息。HarmonyKit 是开源项目调试密码虽然由 IDE 自动生成且不具有生产意义上的安全风险但我们仍需避免将这些值硬编码到公开的配置文件中。实际开发中密码可以从环境变量或加密的 keystore 中读取。products产品定义products数组让你可以为同一个应用定义多个产品变体。每个产品可以有不同的签名配置、SDK 版本和构建选项。HarmonyKit 只有一个default产品。多产品场景的例子products: [ { name: phone, // 手机版 signingConfig: release, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12), runtimeOS: HarmonyOS, buildOption: { /* ... */ } }, { name: tablet, // 平板版 signingConfig: release, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12), runtimeOS: HarmonyOS, buildOption: { /* ... */ } } ]targetSdkVersion vs compatibleSdkVersion两个 SDK 版本的区别这是整个 build-profile.json5 中最重要的配置也是最容易被误解的。HarmonyKit 将两者都设为6.0.2(22)但它们的含义完全不同targetSdkVersion告诉系统我为这个版本的 API 做了适配和测试。如果系统运行在更高的 API 版本上系统会启用兼容行为以确保应用正常工作。举例如果targetSdkVersion是 API 18但设备运行 API 22系统可能会对某些 API 行为做向后兼容——比如权限弹窗的样式、通知渠道的行为等。compatibleSdkVersion告诉系统我最低要求这个版本的 API低于此版本的设备无法安装。这是安装门槛。如果设置compatibleSdkVersion: 6.0.2(22)那么运行 API 21 或更低版本的设备将无法安装此应用。两者的关系是compatibleSdkVersiontargetSdkVersion。那么什么时候应该将 compatibleSdkVersion 设得比 targetSdkVersion 低当你的应用使用了 API 22 的新特性但对这些特性做了降级处理时。例如// API 22 引入了新的动画 APIif(deviceInfo.sdkApiVersion22){// 使用 API 22 的新动画animateTo({duration:300,curve:curves.springMotion()});}else{// 降级为 API 21 的普通动画animateTo({duration:300,curve:Curve.EaseOut});}这种情况下你可以设置targetSdkVersion: 6.0.2(22)但compatibleSdkVersion: 5.0.3(21)让更多设备可以安装你的应用只是低版本设备上的体验会退化。HarmonyKit 选择两者都为6.0.2(22)原因很简单项目使用了kit.UIDesignKitHDS 组件该 Kit 的最低要求就是 API 22。技术栈决定了兼容性下限。buildOption.strictMode严格模式HarmonyKit 开启了两项严格检查strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true }caseSensitiveCheck大小写敏感检查。开发环境通常是 macOS默认文件系统大小写不敏感但 HarmonyOS 设备上的文件系统可能是大小写敏感的。开启此检查可以避免开发环境正常真机运行时找不到文件的问题。一个常见的大小写问题// 开发环境能通过macOSimport{CopyButton}from../../components/copybutton;// 小写 b// 真机上可能找不到文件因为实际文件名是 CopyButton.ets开启caseSensitiveCheck: true后编译器会严格校验 import 路径的大小写与实际文件名完全一致。这是一个开局加一个配置后续少十个 bug的选项。useNormalizedOHMUrl强制使用标准化的 OHM URL 格式。OHM URL 是鸿蒙生态的统一模块引用格式格式为scope/package/path。开启此选项后// 允许标准 OHM URLimport{router}fromkit.ArkUI;// 也允许相对路径import{ToolCard}from../components/ToolCard;// 警告非标准路径格式import{ToolCard}from../components\\ToolCard;// 反斜杠这个选项主要防范 Windows 开发环境中的路径分隔符问题反斜杠 vs 正斜杠。strictMode 还包括以下可选检查useStateVarCheck检查State变量的使用是否符合规范noExternalImportByPath禁止通过绝对路径引用模块外部文件noEtsCodeInJsFile禁止在.js文件中使用.ets语法buildModeSet构建模式HarmonyKit 定义了两个构建模式buildModeSet: [ { name: debug }, { name: release } ]这两个模式对应的行为差异由 hvigor 内置插件处理行为debugrelease代码压缩关闭开启可配置代码混淆关闭取决于 obfuscation 配置SourceMap生成不生成HAP 签名调试签名生产签名日志输出保留可被优化掉在 HarmonyKit 开发中debug 模式用于本地开发和调试release 模式用于打包测试和上架准备。modules模块配置modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ]modules数组列出了项目中的所有模块entry、feature、HSP、HAR 等。HarmonyKit 只有一个 entry 模块。name模块的逻辑名称与module.json5中的module.name对应。srcPath模块目录相对于项目根目录的路径。targets模块的构建目标。每个 target 可以声明它适用于哪些 product通过applyToProducts。applyToProducts: [default]表示该 target 在构建default产品时生效。如果定义了多个 product如 phone 和 tablet可以指定不同的 target 应用到不同的 product。多模块项目的典型 modules 配置modules: [ { name: entry, srcPath: ./entry, targets: [ { name: phone, applyToProducts: [phone] }, { name: tablet, applyToProducts: [tablet] } ] }, { name: shared_ui, srcPath: ./shared_ui, // HSP 共享包 targets: [ { name: default, applyToProducts: [phone, tablet] } ] } ]模块级 build-profile.json5 解析HarmonyKit 的模块级配置{ apiType: stageMode, buildOption: { resOptions: { copyCodeResource: { enable: false } } }, buildOptionSet: [ { name: release, arkOptions: { obfuscation: { ruleOptions: { enable: false, files: [./obfuscation-rules.txt] } } } } ], targets: [ { name: default }, { name: ohosTest } ] }apiTypeAPI 模型类型固定为stageMode。Stage 模型是 HarmonyOS 3.1 推荐的应用模型。与旧的 FAFeature Ability模型相比Stage 模型提供了更好的生命周期管理、跨设备迁移和原子化服务支持。HarmonyOS 正在逐步淘汰 FA 模型。新项目应该统一使用 Stage 模型。buildOption.resOptions.copyCodeResourceresOptions: { copyCodeResource: { enable: false } }这个选项控制是否将 rawfile 目录中的代码文件.ets、.ts、.js视为代码资源并复制到资源包中。关闭它可以减小 HAP 体积不包含不必要的代码文件避免意外将源码暴露在可提取的应用包中加快资源处理阶段的构建速度HarmonyKit 不需要从 rawfile 动态加载代码如动态执行.abc文件所以关闭此选项。buildOptionSet按构建模式的选项覆盖buildOptionSet允许你为不同的构建模式debug/release设置不同的构建选项。HarmonyKit 只为 release 模式配置了选项buildOptionSet: [ { name: release, arkOptions: { obfuscation: { ruleOptions: { enable: false, files: [./obfuscation-rules.txt] } } } } ]代码混淆obfuscationHarmonyKit 在 release 模式下也关闭了混淆enable: false。这个决策有四个理由开源透明度HarmonyKit 是开源项目MIT License。混淆后的代码会让社区贡献者无法阅读理解源码违反开源精神。HAP 体积不大HarmonyKit 的 HAP 约 3MB远低于 100MB 上限。混淆带来的体积优化通常 10%-20%收益不高。调试成本release 模式下如果出现问题如 AppGallery 审核失败未混淆的代码便于通过错误堆栈定位问题。贡献者友好混淆后的代码对 APK 逆向难度提升有限HarmonyKit 没有核心算法需要保护却大大增加了贡献者阅读源码的成本。如果你需要开启混淆需要提供混淆规则文件obfuscation-rules.txt规则语法类似于 ProGuard。典型规则# 保留所有 export 的类名和方法名否则外部模块无法引用 -keep public class * { public *; } # 保留 UIAbility 子类系统通过类名查找 -keep class * extends UIAbility # 丢弃所有日志输出 -assumenosideeffects class hilog { public *** debug(...); public *** info(...); }targets模块构建目标targets: [ { name: default }, { name: ohosTest } ]defaulttarget 用于常规构建ohosTesttarget 用于自动化测试构建。在 DevEco Studio 中Run按钮使用defaulttargetRun Test按钮使用ohosTesttarget。HarmonyKit 的测试目录结构entry/src/ ├── main/ # 对应 default target ├── ohosTest/ # 对应 ohosTest targetUI 自动化测试 └── test/ # 本地单元测试配置变更的影响范围分析理解改了某个配置会影响什么比记住每个配置项更重要。以下是 HarmonyKit 开发中实际遇到的配置变更影响链场景修改 compatibleSdkVersioncompatibleSdkVersion: 6.0.2(22) → 5.0.0(12)影响链可以安装在更多设备上API 12 的设备都可以安装但kit.UIDesignKit中的某些 HDS 组件在 API 12 上不可用编译器不会报错因为编译 target 还是 API 22但真机运行时会崩溃需要在代码中添加运行时 API 版本检查场景修改 targetSdkVersiontargetSdkVersion: 6.0.2(22) → 5.0.1(18)影响链编译时只能使用 API 18 及以下版本的 API代码中使用的 API 22 新特性会报编译错误需要移除对新 API 的引用或降级实现kit.UIDesignKit中的 API 22 专属方法变得不可用场景将 release 的 obfuscation 改为 trueenable: false → true影响链release HAP 中类名、方法名被混淆为短名称a、b、c…HAP 体积减少约 10%-20%错误堆栈不再可读需要 mapping 文件还原社区贡献者不能直接通过阅读 release 产物理解代码需要保留 mapping 文件用于审核问题的堆栈还原配置文件的最佳实践基于 HarmonyKit 的开发经验总结以下最佳实践1. signingConfigs 至少包含 debug 和 release 两个配置不要图方便把 debug 证书用在 release 构建中。debug 证书由 IDE 自动生成有效期有限且不被 AppGallery 信任。release 构建必须使用 AppGallery 签发的正式证书。2. compatibleSdkVersion 不要随意调低compatibleSdkVersion越低兼容的设备越多是好事但你需要为所有低版本设备处理 API 差异是成本。一个合理的策略是将compatibleSdkVersion设置为项目所用 Kit 套件的最低支持版本。HarmonyKit 因为使用了kit.UIDesignKit所以最低版本就是 API 22。3. strictMode 全部开启caseSensitiveCheck和useNormalizedOHMUrl都是在编译阶段进行检查不影响运行时性能和 HAP 体积。开启它们等于免费获得了一层最佳实践校验。4. buildModeSet 至少包含 debug 和 release这是一个几乎所有项目都会保持的默认配置。只有在需要额外的构建模式时如 staging、beta才扩展数组。5. 代码文件不要进 rawfilecopyCodeResource: false应该是默认选择。只有当你确实需要从 rawfile 动态加载代码时才开启——比如实现热更新或插件化架构。配置即文档最后谈一个认知层面的观点build-profile.json5不仅是配置文件也是一种文档。一个新人打开项目他看到的第一个有信息量的东西除了 README就是build-profile.json5。通过它你能推断出这个应用用什么 SDK 版本是否有多个产品变体是否做代码混淆支持哪些设备因此配置文件的注释很重要。HarmonyKit 的配置虽然简洁但每个关键字段都有明确的场景对应——这不是为了配置而配置而是为了让所有协作者能在五分钟内理解项目的构建策略。项目仓库https://atomgit.com/VON-/harmony-kit
HarmonyKit | 鸿蒙开发：build-profile.json5 SDK 版本与签名配置详解
HarmonyKit | 鸿蒙开发build-profile.json5 SDK 版本与签名配置详解引言两万个字符的配置五个关键决策HarmonyKit 的配置文件加在一起不到 500 行但背后的决策逻辑远比代码量复杂。build-profile.json5是鸿蒙项目的总控制台——一个配置项的变更就可能影响 HAP 体积、API 可用范围、签名方式、编译警告和上架审核结果。这篇文章以 HarmonyKit 的实际配置为例从项目级到模块级逐层拆解build-profile.json5的每一个配置节点解释在什么场景下应该选择什么配置值以及错误的配置会带来什么后果。项目仓库https://atomgit.com/VON-/harmony-kit配置的三个层级在深入了解每个字段之前先建立全局视角。鸿蒙项目的构建配置分为三个层级层级文件位置作用域项目级./build-profile.json5所有模块共享的签名、产品、构建模式配置模块级./entry/build-profile.json5单个模块的构建选项、混淆规则、target 配置引擎级./hvigor/hvigor-config.json5hvigor 构建引擎本身的行为配置三个层级不是平等的——项目级配置规定可以做什么模块级配置选择怎么做引擎级配置以什么方式做。项目级 build-profile.json5 全解析HarmonyKit 的项目级配置完整如下{ app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.cer, keyAlias: debugKey, keyPassword: 0000001A9C..., profile: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.p7b, signAlg: SHA256withECDSA, storeFile: /Users/wangxinjie/.ohos/config/default_harmonykit_xxx.p12, storePassword: 0000001AA1... } } ], products: [ { name: default, signingConfig: default, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 6.0.2(22), runtimeOS: HarmonyOS, buildOption: { strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true } } } ], buildModeSet: [ { name: debug }, { name: release } ] }, modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ] }signingConfigs签名配置数组这个数组可以包含多个签名配置——典型场景是开发调试签名和生产发布签名分离signingConfigs: [ { name: debug, // 开发调试专用签名 type: HarmonyOS, material: { /* 自动生成的调试证书 */ } }, { name: release, // 生产发布专用签名 type: HarmonyOS, material: { /* AppGallery 签发的正式证书 */ } } ]HarmonyKit 目前只有一个default签名配置因为它还没有上架 AppGallery只使用 DevEco Studio 自动生成的调试证书。signingConfigs 的关键配置项解读name签名的逻辑名称被products[].signingConfig引用。type固定为HarmonyOS。material.certpath.cer证书文件的绝对路径。这是公钥证书用于验证签名。material.storeFile.p12密钥库文件路径。包含私钥和证书链是签名操作的核心。material.keyAlias密钥库中密钥的别名。默认debugKey。material.profile.p7bProvisioning Profile 文件路径。描述应用在设备上的运行权限。material.signAlg签名算法。SHA256withECDSA使用 ECDSA 椭圆曲线算法配合 SHA-256 哈希。material.keyPassword / storePassword密钥和密钥库的密码。调试证书的密码是固定的、自动生成的生产证书的密码需要自己保管。安全提醒keyPassword和storePassword是敏感信息。HarmonyKit 是开源项目调试密码虽然由 IDE 自动生成且不具有生产意义上的安全风险但我们仍需避免将这些值硬编码到公开的配置文件中。实际开发中密码可以从环境变量或加密的 keystore 中读取。products产品定义products数组让你可以为同一个应用定义多个产品变体。每个产品可以有不同的签名配置、SDK 版本和构建选项。HarmonyKit 只有一个default产品。多产品场景的例子products: [ { name: phone, // 手机版 signingConfig: release, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12), runtimeOS: HarmonyOS, buildOption: { /* ... */ } }, { name: tablet, // 平板版 signingConfig: release, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12), runtimeOS: HarmonyOS, buildOption: { /* ... */ } } ]targetSdkVersion vs compatibleSdkVersion两个 SDK 版本的区别这是整个 build-profile.json5 中最重要的配置也是最容易被误解的。HarmonyKit 将两者都设为6.0.2(22)但它们的含义完全不同targetSdkVersion告诉系统我为这个版本的 API 做了适配和测试。如果系统运行在更高的 API 版本上系统会启用兼容行为以确保应用正常工作。举例如果targetSdkVersion是 API 18但设备运行 API 22系统可能会对某些 API 行为做向后兼容——比如权限弹窗的样式、通知渠道的行为等。compatibleSdkVersion告诉系统我最低要求这个版本的 API低于此版本的设备无法安装。这是安装门槛。如果设置compatibleSdkVersion: 6.0.2(22)那么运行 API 21 或更低版本的设备将无法安装此应用。两者的关系是compatibleSdkVersiontargetSdkVersion。那么什么时候应该将 compatibleSdkVersion 设得比 targetSdkVersion 低当你的应用使用了 API 22 的新特性但对这些特性做了降级处理时。例如// API 22 引入了新的动画 APIif(deviceInfo.sdkApiVersion22){// 使用 API 22 的新动画animateTo({duration:300,curve:curves.springMotion()});}else{// 降级为 API 21 的普通动画animateTo({duration:300,curve:Curve.EaseOut});}这种情况下你可以设置targetSdkVersion: 6.0.2(22)但compatibleSdkVersion: 5.0.3(21)让更多设备可以安装你的应用只是低版本设备上的体验会退化。HarmonyKit 选择两者都为6.0.2(22)原因很简单项目使用了kit.UIDesignKitHDS 组件该 Kit 的最低要求就是 API 22。技术栈决定了兼容性下限。buildOption.strictMode严格模式HarmonyKit 开启了两项严格检查strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true }caseSensitiveCheck大小写敏感检查。开发环境通常是 macOS默认文件系统大小写不敏感但 HarmonyOS 设备上的文件系统可能是大小写敏感的。开启此检查可以避免开发环境正常真机运行时找不到文件的问题。一个常见的大小写问题// 开发环境能通过macOSimport{CopyButton}from../../components/copybutton;// 小写 b// 真机上可能找不到文件因为实际文件名是 CopyButton.ets开启caseSensitiveCheck: true后编译器会严格校验 import 路径的大小写与实际文件名完全一致。这是一个开局加一个配置后续少十个 bug的选项。useNormalizedOHMUrl强制使用标准化的 OHM URL 格式。OHM URL 是鸿蒙生态的统一模块引用格式格式为scope/package/path。开启此选项后// 允许标准 OHM URLimport{router}fromkit.ArkUI;// 也允许相对路径import{ToolCard}from../components/ToolCard;// 警告非标准路径格式import{ToolCard}from../components\\ToolCard;// 反斜杠这个选项主要防范 Windows 开发环境中的路径分隔符问题反斜杠 vs 正斜杠。strictMode 还包括以下可选检查useStateVarCheck检查State变量的使用是否符合规范noExternalImportByPath禁止通过绝对路径引用模块外部文件noEtsCodeInJsFile禁止在.js文件中使用.ets语法buildModeSet构建模式HarmonyKit 定义了两个构建模式buildModeSet: [ { name: debug }, { name: release } ]这两个模式对应的行为差异由 hvigor 内置插件处理行为debugrelease代码压缩关闭开启可配置代码混淆关闭取决于 obfuscation 配置SourceMap生成不生成HAP 签名调试签名生产签名日志输出保留可被优化掉在 HarmonyKit 开发中debug 模式用于本地开发和调试release 模式用于打包测试和上架准备。modules模块配置modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ]modules数组列出了项目中的所有模块entry、feature、HSP、HAR 等。HarmonyKit 只有一个 entry 模块。name模块的逻辑名称与module.json5中的module.name对应。srcPath模块目录相对于项目根目录的路径。targets模块的构建目标。每个 target 可以声明它适用于哪些 product通过applyToProducts。applyToProducts: [default]表示该 target 在构建default产品时生效。如果定义了多个 product如 phone 和 tablet可以指定不同的 target 应用到不同的 product。多模块项目的典型 modules 配置modules: [ { name: entry, srcPath: ./entry, targets: [ { name: phone, applyToProducts: [phone] }, { name: tablet, applyToProducts: [tablet] } ] }, { name: shared_ui, srcPath: ./shared_ui, // HSP 共享包 targets: [ { name: default, applyToProducts: [phone, tablet] } ] } ]模块级 build-profile.json5 解析HarmonyKit 的模块级配置{ apiType: stageMode, buildOption: { resOptions: { copyCodeResource: { enable: false } } }, buildOptionSet: [ { name: release, arkOptions: { obfuscation: { ruleOptions: { enable: false, files: [./obfuscation-rules.txt] } } } } ], targets: [ { name: default }, { name: ohosTest } ] }apiTypeAPI 模型类型固定为stageMode。Stage 模型是 HarmonyOS 3.1 推荐的应用模型。与旧的 FAFeature Ability模型相比Stage 模型提供了更好的生命周期管理、跨设备迁移和原子化服务支持。HarmonyOS 正在逐步淘汰 FA 模型。新项目应该统一使用 Stage 模型。buildOption.resOptions.copyCodeResourceresOptions: { copyCodeResource: { enable: false } }这个选项控制是否将 rawfile 目录中的代码文件.ets、.ts、.js视为代码资源并复制到资源包中。关闭它可以减小 HAP 体积不包含不必要的代码文件避免意外将源码暴露在可提取的应用包中加快资源处理阶段的构建速度HarmonyKit 不需要从 rawfile 动态加载代码如动态执行.abc文件所以关闭此选项。buildOptionSet按构建模式的选项覆盖buildOptionSet允许你为不同的构建模式debug/release设置不同的构建选项。HarmonyKit 只为 release 模式配置了选项buildOptionSet: [ { name: release, arkOptions: { obfuscation: { ruleOptions: { enable: false, files: [./obfuscation-rules.txt] } } } } ]代码混淆obfuscationHarmonyKit 在 release 模式下也关闭了混淆enable: false。这个决策有四个理由开源透明度HarmonyKit 是开源项目MIT License。混淆后的代码会让社区贡献者无法阅读理解源码违反开源精神。HAP 体积不大HarmonyKit 的 HAP 约 3MB远低于 100MB 上限。混淆带来的体积优化通常 10%-20%收益不高。调试成本release 模式下如果出现问题如 AppGallery 审核失败未混淆的代码便于通过错误堆栈定位问题。贡献者友好混淆后的代码对 APK 逆向难度提升有限HarmonyKit 没有核心算法需要保护却大大增加了贡献者阅读源码的成本。如果你需要开启混淆需要提供混淆规则文件obfuscation-rules.txt规则语法类似于 ProGuard。典型规则# 保留所有 export 的类名和方法名否则外部模块无法引用 -keep public class * { public *; } # 保留 UIAbility 子类系统通过类名查找 -keep class * extends UIAbility # 丢弃所有日志输出 -assumenosideeffects class hilog { public *** debug(...); public *** info(...); }targets模块构建目标targets: [ { name: default }, { name: ohosTest } ]defaulttarget 用于常规构建ohosTesttarget 用于自动化测试构建。在 DevEco Studio 中Run按钮使用defaulttargetRun Test按钮使用ohosTesttarget。HarmonyKit 的测试目录结构entry/src/ ├── main/ # 对应 default target ├── ohosTest/ # 对应 ohosTest targetUI 自动化测试 └── test/ # 本地单元测试配置变更的影响范围分析理解改了某个配置会影响什么比记住每个配置项更重要。以下是 HarmonyKit 开发中实际遇到的配置变更影响链场景修改 compatibleSdkVersioncompatibleSdkVersion: 6.0.2(22) → 5.0.0(12)影响链可以安装在更多设备上API 12 的设备都可以安装但kit.UIDesignKit中的某些 HDS 组件在 API 12 上不可用编译器不会报错因为编译 target 还是 API 22但真机运行时会崩溃需要在代码中添加运行时 API 版本检查场景修改 targetSdkVersiontargetSdkVersion: 6.0.2(22) → 5.0.1(18)影响链编译时只能使用 API 18 及以下版本的 API代码中使用的 API 22 新特性会报编译错误需要移除对新 API 的引用或降级实现kit.UIDesignKit中的 API 22 专属方法变得不可用场景将 release 的 obfuscation 改为 trueenable: false → true影响链release HAP 中类名、方法名被混淆为短名称a、b、c…HAP 体积减少约 10%-20%错误堆栈不再可读需要 mapping 文件还原社区贡献者不能直接通过阅读 release 产物理解代码需要保留 mapping 文件用于审核问题的堆栈还原配置文件的最佳实践基于 HarmonyKit 的开发经验总结以下最佳实践1. signingConfigs 至少包含 debug 和 release 两个配置不要图方便把 debug 证书用在 release 构建中。debug 证书由 IDE 自动生成有效期有限且不被 AppGallery 信任。release 构建必须使用 AppGallery 签发的正式证书。2. compatibleSdkVersion 不要随意调低compatibleSdkVersion越低兼容的设备越多是好事但你需要为所有低版本设备处理 API 差异是成本。一个合理的策略是将compatibleSdkVersion设置为项目所用 Kit 套件的最低支持版本。HarmonyKit 因为使用了kit.UIDesignKit所以最低版本就是 API 22。3. strictMode 全部开启caseSensitiveCheck和useNormalizedOHMUrl都是在编译阶段进行检查不影响运行时性能和 HAP 体积。开启它们等于免费获得了一层最佳实践校验。4. buildModeSet 至少包含 debug 和 release这是一个几乎所有项目都会保持的默认配置。只有在需要额外的构建模式时如 staging、beta才扩展数组。5. 代码文件不要进 rawfilecopyCodeResource: false应该是默认选择。只有当你确实需要从 rawfile 动态加载代码时才开启——比如实现热更新或插件化架构。配置即文档最后谈一个认知层面的观点build-profile.json5不仅是配置文件也是一种文档。一个新人打开项目他看到的第一个有信息量的东西除了 README就是build-profile.json5。通过它你能推断出这个应用用什么 SDK 版本是否有多个产品变体是否做代码混淆支持哪些设备因此配置文件的注释很重要。HarmonyKit 的配置虽然简洁但每个关键字段都有明确的场景对应——这不是为了配置而配置而是为了让所有协作者能在五分钟内理解项目的构建策略。项目仓库https://atomgit.com/VON-/harmony-kit
