大家好我是[晚风依旧似温柔]新人一枚欢迎大家关注~本文目录前言一、先弄清楚两个 build-profile.json5 管的不是同一层二、HarmonyOS 7 下需要关注什么版本问题三、为什么用 buildProfileFields 做这个实验四、搭一个最小实验1. 工程级 build-profile.json52. entry 模块级 build-profile.json5五、最终应该看到什么六、怎么查看最终配置而不是靠猜方法一生成 BuildProfile方法二使用 buildInfo 查看构建配置七、这个实验真正说明了什么1. “模块级优先”不是说工程级配置失效2. 工程级适合放公共配置模块级适合做差异化3. 不要只记“工程级 模块级”4. build-profile.json5 和 module.json5 不要混在一起八、实际项目中建议这样排查开发经验总结参考资料前言HarmonyOS 工程里有一个很容易让人产生疑问的地方项目根目录有build-profile.json5进入entry模块后又能看到一个build-profile.json5。两个文件都和构建有关甚至都能出现buildOption。那么问题来了同一个配置项在工程级和模块级都写了到底听谁的如果两边写的是不同配置又会不会丢失官方对这个问题给出的规则其实很明确工程级和模块级的buildOption会参与合并从完整的编译选项继承覆写关系看模块级buildOption的优先级高于工程级products中的buildOption。换成更直观的话说就是相同字段由更高优先级配置覆写不同字段则可以沿继承关系保留下来。这篇文章不扩展到复杂的多产品、多 Target 场景而是做一个最小实验利用buildProfileFields同时设置“同名字段”和“不同字段”再观察最终构建配置。这样比单纯背优先级更容易理解。【建议插图1DevEco Studio Project 视图中根目录 build-profile.json5 与 entry/build-profile.json5 的位置对比】一、先弄清楚两个 build-profile.json5 管的不是同一层先看一个典型工程结构MyApplication ├── AppScope ├── entry │ ├── src │ ├── build-profile.json5 ← 模块级 │ └── oh-package.json5 ├── build-profile.json5 ← 工程级 ├── oh-package.json5 └── hvigor根目录的build-profile.json5是工程级构建配置。在这里可以描述应用的products、模块列表、构建模式等模块目录下的build-profile.json5则描述当前模块的 Target、模块构建选项等。华为官方分别提供了工程级和模块级build-profile.json5的字段说明。这也是为什么两个文件不能简单理解成“重复配置”。工程级配置更适合表达整个 Product 或构建模式的公共要求模块级配置则可以继续针对某个具体模块细化。Hvigor 最终会按照规定的继承和覆写规则整合这些配置。如果进一步把buildOptionSet、Target 和命令行也算进来官方给出的整体继承覆写顺序是命令行配置 ↓ targets 中的 buildOption ↓ 模块级 buildOptionSet ↓ 模块级 buildOption ↓ 工程级 products 中的 buildOption ↓ 工程级 buildModeSet 中的 buildOption这里真正需要记住的不是一长串名字而是离具体构建目标越近的配置可以在规定的继承链上覆写更通用的配置。所以本文只比较“工程级 Product”与“模块级公共buildOption”时结论就是模块级 buildOption 工程级 products.buildOption需要注意这个结论有明确的比较范围。如果模块的targets[].config.buildOption或buildOptionSet又配置了相同字段还需要继续按照完整优先级判断不能简单套一句“模块级永远最高”。二、HarmonyOS 7 下需要关注什么版本问题截至本文整理时华为官方已经发布 HarmonyOS 7对应 API 版本为26.0.0。官方升级适配指南明确说明HarmonyOS 7.0 对应 API 26.0.0并建议升级到相应开发套件进行适配。不过这篇文章讨论的是DevEco Hvigor 编译构建配置不是某个运行时系统 API。因此这里没有需要申请的系统权限也不涉及某个 Kit、ArkUI 组件或 Phone/Foldable/Tablet 专属能力。不要为了文章以 HarmonyOS 7 为背景就给build-profile.json5生硬套一个“API 26 才支持”的结论。本文实验可以放在 HarmonyOS 7 / API 26.0.0 工程中进行但真正应该核对的是当前 DevEco Studio、Hvigor 及配置文件字段是否匹配而不是去module.json5里申请权限。另外从 26.0.0 开始HarmonyOS 开发套件 API 版本采用X.Y.Z的语义化版本格式这也是新工程中可能看到26.0.0而不是旧式版本表示的原因。三、为什么用 buildProfileFields 做这个实验直接找一个打包、Native 或混淆配置来验证优先级当然也可以但会引入很多额外变量。这里选择buildProfileFields原因是它本身就是官方提供的自定义编译参数能力开发者可以在build-profile.json5中增加自定义字段并通过生成的BuildProfile获取构建参数。官方资料同时给出了工程级、模块级自定义参数的使用方式。我们设计三个字段字段工程级模块级用途sameKeyfromProjectfromModule验证同名字段谁覆盖谁projectOnlyprojectValue不配置验证工程级字段能否被继承moduleOnly不配置moduleValue验证模块自己的字段能否加入最终配置这样只需要观察三个值就能把“覆写”和“继承”分开。四、搭一个最小实验假设工程只有一个entry模块Product 和 Target 都使用默认的default。这里不要直接拿下面代码覆盖自己项目里的整个配置文件因为实际工程通常还包含签名、模块列表、SDK 版本等内容。只需要把实验涉及的buildOption合并到现有对应位置。1. 工程级 build-profile.json5在根目录build-profile.json5的app.products中找到当前使用的defaultProduct在它的buildOption中增加{ app: { products: [ { name: default, // 这里保留工程原有的 signingConfig、 // compatibleSdkVersion、runtimeOS 等配置。 buildOption: { arkOptions: { buildProfileFields: { sameKey: fromProject, projectOnly: projectValue } } } } ] } // modules 等原有配置继续保留 }这一步定义两个工程级参数。sameKey故意准备与模块级发生冲突projectOnly则只在工程级出现。【建议插图2根目录 build-profile.json5 中 default Product 的 buildProfileFields 配置】2. entry 模块级 build-profile.json5然后进入entry/build-profile.json5在模块级buildOption中配置{ apiType: stageMode, buildOption: { arkOptions: { buildProfileFields: { sameKey: fromModule, moduleOnly: moduleValue } } } // targets 等模块原有配置继续保留 }这里也放两个参数。其中sameKey fromModule和工程级的sameKey fromProject发生冲突。而moduleOnly moduleValue只存在于模块级。现在实验条件就准备好了。五、最终应该看到什么按照官方的继承覆写规则对于本文限定的 ProductbuildOption与模块级公共buildOption两层配置预期合并结果应当是sameKey fromModule projectOnly projectValue moduleOnly moduleValue也就是参数最终值原因sameKeyfromModule同名配置发生覆写模块级优先级更高projectOnlyprojectValue模块级没有重新定义工程级配置被继承moduleOnlymoduleValue模块级新增字段正常进入最终配置注意这里说的是依据官方规则得到的预期结果不是声称本文已经在某台设备上完成真机测试。而且这个实验本身不需要真机因为我们验证的是编译配置合并不是设备运行行为。六、怎么查看最终配置而不是靠猜这里有两种很实用的观察方法。方法一生成 BuildProfile官方的自定义编译参数文档说明构建过程中可以生成BuildProfile类buildProfileFields中的自定义参数会进入对应构建配置。可以在 DevEco Studio 中选择相应模块后使用生成 Build Profile 的功能也可以按照官方文档提供的方式执行hvigorw GenerateBuildProfile然后检查对应模块生成目录中的BuildProfile.ets。我们真正关心的不是文件中其他自动生成字段而是搜索sameKey projectOnly moduleOnly如果当前工程配置与本文实验一致按照官方规则三个字段应分别对应fromModule projectValue moduleValue【建议插图3生成的 BuildProfile.ets 中 sameKey、projectOnly、moduleOnly 三个字段】方法二使用 buildInfo 查看构建配置较新的 Hvigor 还提供了buildInfo任务用来打印工程级或模块级build-profile.json5配置信息官方命令行文档说明该能力从hvigorw 5.18.4开始支持。因此使用前先确认本机hvigorw版本。满足版本条件时可以针对模块查看buildOption例如hvigorw buildInfo-pmoduleentry-pbuildOption需要机器可读结果时还可以结合官方提供的 JSON 输出参数。这种方式很适合排查复杂工程不用仅凭肉眼在两个甚至多个配置层之间来回寻找而是直接观察 Hvigor 整理后的构建信息。【建议插图4Terminal 中执行 buildInfo 后查看 entry 模块 buildOption 的输出】七、这个实验真正说明了什么1. “模块级优先”不是说工程级配置失效这是最容易出现的理解偏差。比如工程级buildProfileFields: { sameKey: fromProject, projectOnly: projectValue }模块级buildProfileFields: { sameKey: fromModule, moduleOnly: moduleValue }最终不是简单把工程级整个对象扔掉。需要区分“同一个配置项发生覆写”和“没有冲突的配置继续继承”。因此理解build-profile.json5时用“继承 覆写”比“谁把谁全部替换掉”更准确。2. 工程级适合放公共配置模块级适合做差异化如果一个配置希望多个模块共享可以优先考虑工程级配置某个模块确实需要不同值再在模块级进行覆盖。官方 FAQ 里也有一个很有代表性的场景当 HSP 使用了 HAP 未定义的自定义BuildProfileFields时可以在 HAP 中配置相同参数也可以将相同自定义参数配置到工程级build-profile.json5从而让其全局生效。这说明工程级配置并不是“没什么用的默认文件”它承担的恰恰是更公共的一层构建配置。3. 不要只记“工程级 模块级”一旦工程复杂起来还有buildModeSet products 模块 buildOption buildOptionSet targets.config.buildOption 命令行官方当前的构建模式实践中也明确区分了工程级与模块级配置并展示了 Product、buildMode、模块 buildOptionSet 等配置位置。所以遇到“明明修改了模块 buildOption为什么还是不是这个值”时下一步就应该检查buildOptionSet、Target 或命令行有没有更高优先级配置而不是继续修改工程级文件。4. build-profile.json5 和 module.json5 不要混在一起build-profile.json5主要属于编译构建配置。权限、Ability 等应用/模块声明则有自己的配置位置。本文实验完全不需要增加module.json5权限。看到一个功能“不生效”就到module.json5增加字段是配置类问题里很危险的一种排查方式字段属于哪个配置文件应当先以官方配置文件说明为准。八、实际项目中建议这样排查遇到构建参数与预期不一致可以按照下面的顺序缩小范围确认当前 Product、Target 和 Build Mode。不同 Product、Target、构建模式可能进入不同的配置分支。检查工程级products[].buildOption。先确认公共配置从哪里进入。检查模块级buildOption。看相同字段是否已经在模块中覆写。继续检查buildOptionSet和targets[].config.buildOption。它们的优先级还高于模块级公共buildOption。检查命令行参数。官方规则中命令行处于更高优先级某些参数可以对已经整合的配置进行定点覆写。不要只靠肉眼判断。能使用BuildProfile或当前 Hvigor 支持的buildInfo时直接查看最终构建信息。如果使用buildProfileFields时出现Property xxx does not exist on type typeof BuildProfile也可以优先检查当前模块build-profile.json5中是否真正配置了对应自定义字段。华为官方的编译构建 FAQ 对这类问题给出了专门的排查说明。开发经验总结两个build-profile.json5并不是重复文件而是 Hvigor 构建配置的不同层级。对本文最小场景可以把规则压缩成一句话工程级给公共值模块级做差异化 同名字段按优先级覆写不冲突字段沿继承关系保留。但到了真实项目不建议只背“模块级大于工程级”。完整的构建配置还可能受到buildModeSet、Product、模块buildOption、buildOptionSet、Target 以及命令行影响。真正可靠的办法是先确认当前构建组合再沿官方规定的继承覆写关系逐层检查。这个小实验还有一个很适合继续扩展的方向把sameKey再分别放进buildOptionSet和targets[].config.buildOption然后继续观察最终值。这样就能把一张抽象的“配置优先级图”变成自己工程里可以逐层复现的构建实验。参考资料《模块级build-profile.json5文件》华为开发者联盟链接HarmonyOS 官方文档模块级 build-profile.json5《工程级build-profile.json5文件》华为开发者联盟链接HarmonyOS 官方文档工程级 build-profile.json5《能力说明——灵活定制编译选项》华为开发者联盟链接HarmonyOS 官方文档灵活定制编译选项《获取自定义编译参数》华为开发者联盟链接HarmonyOS 官方文档获取自定义编译参数《实践说明——灵活定制编译选项》华为开发者联盟链接HarmonyOS 官方文档编译选项实践说明《应用升级适配指导——向26.0.0升级》华为开发者联盟链接HarmonyOS 7 / API 26.0.0 升级适配官方指南《版本号格式调整说明》华为开发者联盟链接HarmonyOS API 版本号格式官方说明《编译构建常见问题》华为开发者联盟链接HarmonyOS 官方编译构建 FAQ如果觉得有帮助别忘了点个赞关注支持一下~喜欢记得关注别让好内容被埋没
