【HarmonyOS NEXT】配置文件：build-profile.json5
一、背景
鸿蒙开发中工程级与模块级都有build-profile.json5文件，不同层级下build-profile.json5文件却有所不同，总结整理下，加深对该文件的理解
二、工程级build-profile.json5文件
2.1、所在位置：
项目根目录下的build-profile.json5文件，属于全局统一配置
2.2、配置文件字段说明
详细可参考官网说明https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-profile-app#section1055314914518
字段名称 | 类型 | 可选/必选 | 含义 |
|---|---|---|---|
app | 对象 | 必选 | 编译配置信息。 |
modules | 对象数组 | 必选 | 工程中包含的所有模块的信息，数组长度至少为1。 |
三、模块级build-profile.json5文件
2.1、所在位置：
如entry/feature模块目录的build-profile.json5文件，属于模块个性化配置
2.2、配置文件字段说明
详细可参考官网说明https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-profile#section4772917715
四、核心关联性（继承 + 引用 + 覆盖）
两者说属于协作关系，工程级定全局规则，模块级按需调整
4.1. 配置继承：模块级默认继承工程级全局配置
如：工程级配置："targetSdkVersion": "6.0.1(21)"；模块级未配置该字段 →entry模块自动使用6.0.1(21)作为目标 SDK 版本
4.2. 配置引用：模块级可直接引用工程级的全局配置
如：签名配置；工程级在app.signingConfigs中定义全局签名模板，模块级通过名称引用无需重复
4.3. 配置覆盖：模块级可自定义配置，覆盖工程级规则
如果模块有特殊需求（如某模块需要更高的 SDK 版本），可在模块级配置中重写，优先级更高
五、两者的区别
| 维度 | 工程级 build-profile.json5（根目录） | 模块级 build-profile.json5（模块目录） |
|---|---|---|
| 作用域 | 全局生效，覆盖整个工程的所有模块 | 仅对当前模块生效，是模块专属配置 |
| 核心职责 | 定义工程级全局规则，统一管控所有模块 | 定义模块个性化规则，补充 / 覆盖全局配置 |
| 配置重点 | 1. 工程级签名配置（signingConfigs）2. 全局 SDK 版本（兼容 / 目标）3. 工程级构建模式（debug/release）4. 多模块共享的构建选项 | 1. 引用工程级签名配置（signingConfig）2. 模块专属 SDK 版本（覆盖全局）3. 模块构建目标（如hap/har）4. 模块个性化构建参数（如混淆、资源压缩） |
| 优先级 | 基础配置，可被模块级配置覆盖 | 更高优先级，模块级配置会覆盖工程级同名配置 |
| 是否必须 | 工程必须有（全局配置入口） | 模块可选（无则完全继承工程级配置） |