在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的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 无法启动。

七、排查思路

如果多目标产物配置后构建结果不符合预期,建议按下面顺序检查:

  1. 先看 Product 名称:工程级 products[].name 是否和 applyToProducts 里的字符串完全一致(区分大小写);
  2. 再看 Target 名称:工程级 modules[].targets[].name 是否和模块级 targets[].name 完全一致;
  3. 检查归属关系:是否每个 Product 在每个参与构建的模块中都有且仅有一个 Target 与之对应;
  4. 检查 sourceRoots 路径:路径是相对于模块根目录的,注意 ./ 前缀不能遗漏;
  5. 如果用了 configPath:确认该 module.json5 是否包含了所有必填字段,不要以为会自动继承;
  6. 用命令行验证: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,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐