同一个工程,两个构建产物:Product 和 Target 到底怎么配合工作的?【鸿蒙心迹】

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀
前言
不少开发者第一次打开 build-profile.json5 时,都会被 products 和 targets 这两个字段搞混。它们都和"构建"有关,名字也都像是"产物",但实际上承担的角色完全不一样。
这篇文章从一个最简单的需求出发:同一个工程,生成两个包名不同的 App——一个免费版,一个付费版。围绕这个需求,把 Product、Target、applyToProducts 的关系一次说清楚。
一、先搞清楚它们各自代表什么
Product(产品) 代表一个对外独立发布的终态版本。
你可以把它理解为:最终用户下载到手机上的那个 App 的"身份证"。一个 Product 对应一个独立的 Bundle Name(包名)、一套签名配置,以及一套发布用的应用元信息。
Target(目标) 代表一个模块的构建变体。
它不是发布单位,而是构建单位。同一个模块可以有多个 Target,每个 Target 可以拥有独立的源码路径、资源路径、配置文件。Target 通过 applyToProducts 字段,声明自己"属于"哪个 Product。
两者的关系可以简单描述为:
Product 是结果,Target 是描述如何构建这个结果的规则。构建时选择一个 Product,系统会去找这个模块中
applyToProducts指向该 Product 的 Target,用它的配置来参与构建。
二、整体结构在工程里是怎么分布的
多目标产物的配置分布在两个层级:
| 层级 | 文件 | 配置内容 |
|---|---|---|
| 工程级 | build-profile.json5(根目录) | 定义多个 Product,声明各模块参与哪个 Target |
| 模块级 | 模块名/build-profile.json5 | 定义各 Target 的具体源码、资源、配置路径 |
工程级负责"宏观调度"——声明有哪几个产品、每个模块对应哪个 Target;模块级负责"具体实现"——描述这个 Target 到底怎么构建。
三、动手搭一个最小实践场景
场景目标:
一个工程,包含一个 entry 模块,生成两个不同的 App:
default(免费版):包名com.example.myapp,使用默认源码paid(付费版):包名com.example.myapp.paid,使用独立的入口页面
目录结构规划:
MyProject/
├── build-profile.json5 ← 工程级
├── entry/
│ ├── build-profile.json5 ← 模块级
│ ├── src/
│ │ ├── main/
│ │ │ └── ets/pages/Index.ets ← 免费版入口
│ │ └── paid/
│ │ └── ets/pages/Index.ets ← 付费版独立入口
四、核心配置代码
4.1 工程级 build-profile.json5
这里定义两个 Product,并告诉工程:entry 模块的 default Target 归 default 产品,paid Target 归 paid 产品。
{
"app": {
"signingConfigs": [
{
"name": "default",
"type": "HarmonyOS",
"material": {}
}
],
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.0(12)",
"runtimeOS": "HarmonyOS",
"bundleName": "com.example.myapp"
},
{
"name": "paid",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.0(12)",
"runtimeOS": "HarmonyOS",
"bundleName": "com.example.myapp.paid"
}
],
"buildModeSet": [
{ "name": "debug" },
{ "name": "release" }
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
},
{
"name": "paid",
"applyToProducts": ["paid"]
}
]
}
]
}
这里需要关注的地方:
products 里每个条目的 name 字段,必须与 modules[].targets[].applyToProducts 里的字符串精确匹配。大小写都不能差。
bundleName 决定了这两个包在设备上是完全独立的两个 App,互不干扰,可以同时安装。
4.2 模块级 build-profile.json5(entry 模块)
模块级配置负责告诉构建系统,每个 Target 各自用什么源码目录。
{
"apiType": "stageModel",
"buildOption": {},
"targets": [
{
"name": "default"
// 不指定额外 sourceRoots,使用 src/main/ets 默认路径
},
{
"name": "paid",
"source": {
"sourceRoots": ["./src/paid/ets"]
}
}
]
}
关键点:
default Target 不写 source.sourceRoots,构建时会使用模块的默认源码路径(src/main/ets)。
paid Target 添加了 ./src/paid/ets 作为额外源码路径。这意味着 paid Target 可以访问 src/main/ets 里的公共代码,同时还能加载 src/paid/ets 里独立的页面文件。两个路径都会参与编译,优先级上独立路径中的文件可以覆盖同名文件。
4.3 两个版本的入口页面
免费版(src/main/ets/pages/Index.ets):
// 免费版入口,供 default Target 使用
@Entry
@Component
struct Index {
build() {
Column() {
Text('欢迎使用 MyApp 免费版')
.fontSize(24)
.fontWeight(FontWeight.Medium)
Text('升级付费版解锁全部功能')
.fontSize(14)
.fontColor('#888888')
.margin({ top: 8 })
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
付费版(src/paid/ets/pages/Index.ets):
// 付费版入口,供 paid Target 使用,覆盖同路径下的默认页面
@Entry
@Component
struct Index {
build() {
Column() {
Text('欢迎使用 MyApp 付费版')
.fontSize(24)
.fontWeight(FontWeight.Medium)
Text('全部功能已解锁')
.fontSize(14)
.fontColor('#4CAF50')
.margin({ top: 8 })
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
这两个文件路径相对各自的 sourceRoots 是相同的(都是 pages/Index.ets)。当构建 paid Target 时,src/paid/ets/pages/Index.ets 会覆盖 src/main/ets/pages/Index.ets。
4.4 如何切换 Product 进行构建
DevEco Studio 中:
工具栏右上角的 Run/Debug 配置下拉框旁边会出现 Product 选择器,切换到 paid 后点击运行,即可构建付费版。
也可以通过 Run → Edit Configurations 进入配置面板,在 Product 下拉框中选择目标产品。
【建议插图1:DevEco Studio 工具栏中 Product 下拉框切换 default 和 paid 的截图】
命令行构建:
# 构建免费版 HAP
hvigorw assembleHap --product default
# 构建付费版 HAP
hvigorw assembleHap --product paid
两次构建会生成独立的 .hap 文件,包名分别对应各自 Product 中配置的 bundleName。
【建议插图2:两次命令行构建后输出目录中两个独立 HAP 文件的对比截图】
五、几个关键点拆开看
5.1 Product 和 Target 不是一一对应的,但有约束
一个 Target 可以 applyToProducts 多个 Product,意味着这个 Target 的代码参与多个产品的构建。
但反过来:同一个模块中,一个 Product 只能对应一个 Target。这是硬性约束,配置时如果两个 Target 的 applyToProducts 都包含同一个 Product 名,构建会报错。
5.2 Target 的名称必须前后一致
工程级 modules[].targets[].name 和模块级 targets[].name 必须完全一致,包括大小写。两者通过这个字段互相关联,如果不匹配,构建时会找不到对应 Target 配置。
【建议插图3:工程级与模块级 build-profile.json5 中 Target 名称对应关系示意图】
5.3 source.sourceRoots 是追加,不是替换
这里容易产生误解。source.sourceRoots 配置的是额外的源码路径,并不会替换掉 src/main/ets 默认路径。
也就是说,配置了 sourceRoots: ["./src/paid/ets"] 的 Target,编译时会同时扫描 src/main/ets 和 src/paid/ets。两个目录下的代码都可以互相引用。如果两个路径下存在相同的文件路径,sourceRoots 中指定的路径优先级更高,会覆盖默认路径下的同名文件。
5.4 module.json5 也可以独立配置
如果两个版本需要在 module.json5 层面就有差异(比如声明不同的权限、不同的 Ability 入口),可以在模块级 Target 中指定独立的配置文件路径:
{
"targets": [
{
"name": "paid",
"source": {
"configPath": "./src/paid/module.json5"
}
}
]
}
这样 paid Target 构建时会使用 src/paid/module.json5 而不是默认的 src/main/module.json5。适合两个版本权限差异较大、Ability 结构不同的情况。
5.5 Product 的 bundleName 决定了它们是独立的 App
两个 Product 配置了不同的 bundleName,对设备来说就是完全独立的两个应用,可以同时安装、分别更新、各自拥有独立的数据目录。这是多产物方案和单纯用条件编译做分支的本质区别。
六、容易踩坑的地方
工程级 targets 和模块级 targets 是两回事
工程级 modules[].targets 只做"声明"和"归属关系登记",不描述构建细节。真正的构建细节(源码路径、资源路径、配置文件路径)都在模块级的 build-profile.json5 里。初次配置时容易把所有字段都堆到工程级,导致配置不生效。
没有为某个 Product 配置对应 Target
如果一个模块的所有 Target 的 applyToProducts 里都没有包含某个 Product 名,选择该 Product 构建时,这个模块不会参与构建,可能导致 App 缺少页面或功能,却没有明显的报错提示。
Target 名称写错了
工程级声明了 "name": "Paid"(大写 P),模块级定义了 "name": "paid"(小写 p),两者无法匹配。这种问题很隐蔽,表现为构建时找不到 Target 或者直接跳过,建议统一用小写加下划线的命名风格。
独立 module.json5 漏配必要字段
如果用 configPath 指定了独立的 module.json5,该文件必须是完整的配置,不会自动继承默认 module.json5 中的字段。漏掉 abilities、extensionAbilities 等关键配置会导致 App 无法启动。
七、排查思路
如果多目标产物配置后构建结果不符合预期,建议按下面顺序检查:
- 先看 Product 名称:工程级
products[].name是否和applyToProducts里的字符串完全一致(区分大小写); - 再看 Target 名称:工程级
modules[].targets[].name是否和模块级targets[].name完全一致; - 检查归属关系:是否每个 Product 在每个参与构建的模块中都有且仅有一个 Target 与之对应;
- 检查 sourceRoots 路径:路径是相对于模块根目录的,注意
./前缀不能遗漏; - 如果用了 configPath:确认该
module.json5是否包含了所有必填字段,不要以为会自动继承; - 用命令行验证:
hvigorw assembleHap --product <name>比 IDE 构建输出的错误信息更完整,方便定位问题。
开发经验总结
- Product 是发布单位,Target 是构建单位,两者通过
applyToProducts建立关联。 - 同一个模块,每个 Product 只能对应一个 Target,但一个 Target 可以归属多个 Product。
source.sourceRoots是追加逻辑,不会替换默认源码路径,同名文件按路径优先级覆盖。- 需要差异化
module.json5时,用source.configPath指定独立配置,但要保证该文件字段完整。 - 命令行
hvigorw assembleHap --product <name>是验证多产物配置是否生效最直接的方式。
如果你的工程中已经存在多个 Product,可以检查一下每个模块的 Target 覆盖是否完整——有没有某个模块遗漏了对某个 Product 的映射,这类配置缺失往往在调试阶段不容易被发现,到了 release 构建才暴露。
❤️ 如果本文帮到了你…
- 请点个赞,让我知道你还在坚持阅读技术长文!
- 请收藏本文,因为你以后一定还会用上!
- 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
更多推荐



所有评论(0)