HarmonyOS Next DevEco Studio 构建配置指南：多目标产物定制

1. 定制 HAR 多目标构建产物

每一个 HAR 模块均支持定制不同的 target，通过在模块中的 build-profile.json5 文件中实现差异化定制，当前支持设备类型 (deviceType)、资源 (resource)、buildOption 配置项 (如 C++ 依赖的.so、混淆配置、abi 类型、cppFlags 等)、源码集 (source) 的定制。

说明

当前版本，在 DevEco Studio 中编译时，仅支持编译 target 为 default 的模块。若需指定其他 target，需通过命令行来指定，并通过命令行来编译。

例如构建指定的自定义 target:free 的 har，可参考执行以下命令：

hvigorw --mode module -p product=default -p module=library@free -p buildMode=debug assembleHar

1.1. 定义产物的 deviceType

每一个 target 均可以指定支持的设备类型 deviceType，也可以不定义。如果不定义，则该 target 默认支持 config.json 或 module.json5 中定义的设备类型。

同时，在定义每个 target 的 deviceType 时，支持的设备类型必须在 config.json 或 module.json5 中已经定义。例如，在上述定义的 2 个 target 中，分别定义 default 默认支持所有设备类型，free 版本只支持 2in1 设备。

{
  "apiType": 'stageMode',
  "buildOption": { },
  "targets": [
    {
      "name": "default"
    },
    {
      "name": "free",
      "config": {
        "deviceType": ["2in1"]
      }
    }
  ]
}

1.2. 定义 C++ 工程依赖的.so 文件

在 C++ 工程中，可以对每个 target 依赖的.so 文件进行定制。例如某模块依赖了 function1.so、function2.so 和 function3.so 三个文件，其中 target 为 default 的产物依赖了 function1.so 和 function2.so；其中 target 为 vip 的产物依赖了 function1.so 和 function3.so，则示例代码如下所示：

{
  "apiType": 'stageMode',
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": [],
      "abiFilters": ["arm64-v8a", "x86_64"],
      "cppFlags": ""
    }
  },
  "targets": [
    {
      "name": "default",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              "pickFirsts": ["**/function1.so"],
              "excludes": ["**/function3.so"],
              "enableOverride": true
            }
          }
        }
      }
    },
    {
      "name": "vip",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              "pickFirsts": ["**/function1.so"],
              "excludes": ["**/function2.so"],
              "enableOverride": true
            }
          }
        }
      }
    }
  ]
}

1.3. 定义产物的资源

每个 target 使用的资源文件可能存在差异，在开发过程中，开发者可以将每个 target 所使用的资源存放在不同的资源目录下。其中，ArkTS 工程支持对 main 目录下的资源文件目录 (resource) 进行定制；JS 工程支持对 main 目录下的资源文件目录 (resource) 及 Ability 下的资源文件目录 (res) 进行定制。如下为 ArkTS 工程的资源文件目录定制示例：

{
  "apiType": 'stageMode',
  "buildOption": { },
  "targets": [
    {
      "name": "default",
      "resource": {
        "directories": ["./src/main/resources_default"]
      }
    },
    {
      "name": "free",
      "config": {
        "deviceType": ["2in1"]
      },
      "resource": {
        "directories": ["./src/main/resources_default", "./src/main/resources_free"]
      }
    }
  ]
}

2. 配置 APP 多目标构建产物

APP 用于应用/元服务上架发布，针对不同的应用场景，可以定制不同的 product，每个 product 中支持对 bundleName、bundleType、签名信息、icon 和 label 以及包含的 target 进行定制。

定义目标产物 product

每一个 product 对应一个定制的 APP 包，因此，在定制 APP 多目标构建产物前，应提前规划好需要定制的 product 名称。例如，定义 productA 和 productB。工程级 build-profile.json5 文件示例如下：

在定制 product 时，必须存在"default"的 product，否则编译时会出现错误。

"app": {
  "signingConfigs": [],
  "products": [
    {
      "name": "default",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS"
    },
    {
      "name": "productA",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS"
    },
    {
      "name": "productB",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS"
    }
  ],
  "buildModeSet": [
    {"name": "debug"},
    {"name": "release"}
  ]
}

2.1. 定义产物的 APP 包名和供应商名称

每一个 product 均可以指定产物命名和供应商名称。

"app": {
  "signingConfigs": [],
  "products": [
    {
      "name": "default",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "output": {
        "artifactName": "customizedProductOutputName-1.0.0"
      },
      "vendor": "customizedProductVendorName"
    },
    {
      "name": "productA",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "output": {
        "artifactName": "customizedProductOutputNameA-1.0.0"
      },
      "vendor": "customizedProductVendorNameA"
    },
    {
      "name": "productB",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "output": {
        "artifactName": "customizedProductOutputNameB-1.0.0"
      },
      "vendor": "customizedProductVendorNameB"
    }
  ],
  "buildModeSet": [
    {"name": "debug"},
    {"name": "release"}
  ]
}

如果已配置签名，product 产物对应的 APP 包名为开发者定制的名称；如果未配置签名，product 产物对应的 APP 包名为定制的名称+unsigned。

2.2. 定义 product 的 bundleName

针对每个定义的 product，均可以定制不同的 bundleName，如果 product 未定义 bundleName，则采用工程默认的 bundleName。示例如下所示：

"app": {
  "signingConfigs": [],
  "products": [
    {
      "name": "default",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example00.com"
    },
    {
      "name": "productA",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example01.com"
    },
    {
      "name": "productB",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example02.com"
    }
  ],
  "buildModeSet": [
    {"name": "debug"},
    {"name": "release"}
  ]
}

2.3. 定义 product 的 bundleType

针对每个定义的 product，均可以定制不同的 bundleType。开发者可以通过定义每个 product 的 bundleType，分别定义产物类型：

• bundleType 值为 app，表示产物为应用；
• bundleType 值为 atomicService，表示产物为元服务。

如果 product 未定义 bundleType，则采用工程的 bundleType(即创建工程时选择的 Application/Atomic Service)。示例如下所示：

"app": {
  "signingConfigs": [],
  "products": [
    {
      "name": "default",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example00.com",
      "bundleType": "app"
    },
    {
      "name": "productA",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example01.com",
      "bundleType": "atomicService"
    },
    {
      "name": "productB",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example02.com",
      "bundleType": "atomicService"
    }
  ],
  "buildModeSet": [
    {"name": "debug"},
    {"name": "release"}
  ]
}

2.4. 定义 product 的签名配置信息

针对每个定义的 product，均可以定制不同的 signingConfig 签名文件，如果 product 未定义 signingConfig，则构建生成未签名的 APP 包。

通常情况下，您首先需要在签名配置界面或工程的 build-profile.json5 文件中配置签名信息。例如在 File > Project Structure > Project > Signing Configs 界面，分别配置 default、productA 和 productB 的签名信息。

签名信息配置完成后，再添加各个 product 对应的签名文件，示例如下所示：

您也可以提前在 product 中定义签名文件信息，然后在签名界面对每个 product 进行签名，确保配置的 product 签名文件与签名界面配置的签名文件保持一致即可。

"app": {
  "signingConfigs": [],
  "products": [
    {
      "name": "default",
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example00.com"
    },
    {
      "name": "productA",
      "signingConfig": "productA",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example01.com"
    },
    {
      "name": "productB",
      "signingConfig": "productB",
      "compatibleSdkVersion": "5.0.2(14)",
      "runtimeOS": "HarmonyOS",
      "bundleName": "com.example02.com"
    }
  ],
  "buildModeSet": [
    {"name": "debug"},
    {"name": "release"}
  ]
}

2.5. 定义 product 的 icon 和 label

针对每个定义的 product，均可以定制不同的 icon 和 label，如果 product 未定义 icon 和 label，则采用工程默认的 icon 和 label。示例如下所示：

说明

products 中的 icon 和 label 字段在编译时会替换 app.json5 中对应的字段，app.json5 和 module.json5 均可以配置这两个字段。

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "icon":"$media:default_icon",
        "label":"$string:default_name"
      },
      {
        "name": "productA",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "icon":"$media:productA_icon",
        "label":"$string:productA_name"
      },
      {
        "name": "productB",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "icon":"$media:productB_icon",
        "label":"$string:productB_name"
      }
    ],
    "buildModeSet": [
      {"name": "debug"},
      {"name": "release"}
    ]
  },
  ...
}

2.6. 定义 product 中包含的 target

可以选择需要将定义的 target 分别打包到哪一个 product 中，每个 product 可以指定一个或多个 target。

同时每个 target 也可以打包到不同的 product 中，但是同一个 module 的不同 target 不能打包到同一个 product 中 (除非该 module 的不同 target 配置了不同的 deviceType 或 distributionFilter/distroFilter)。

例如，前面定义了 default、free 和 pay 三个 target，现需要将 default target 打包到 default product 中；将 free target 打包到 productA 中；将 pay target 打包到 productB 中，对应的示例代码如下所示：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "bundleName": "com.example00.com"
      },
      {
        "name": "productA",
        "signingConfig": "productA",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "bundleName": "com.example01.com"
      },
      {
        "name": "productB",
        "signingConfig": "productB",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "bundleName": "com.example02.com"
      }
    ],
    "modules": [
      {
        "name": "entry",
        "srcPath": "./entry",
        "targets": [
          {
            "name": "default",
            "applyToProducts": ["default"]
          },
          {
            "name": "free",
            "applyToProducts": ["productA"]
          },
          {
            "name": "pay",
            "applyToProducts": ["productB"]
          }
        ]
      }
    ]
  }
}

3. 多产物构建 target

**align target：**编译构建时，优先级最高的 target。工程配置 align target 后，如果模块中存在 align target，那么将自动选择 align target 进行构建。align target 作用范围是整个工程，只能配置一个，支持命令行和配置文件两种方式。

• 命令行方式示例如下：

hvigorw -c properties.ohos.align.target=target1 assembleHap

• 在 hvigor-config.json5 配置文件中添加 ohos.align.target，示例如下：

"properties": { 'ohos.align.target': 'target1' }

**fallback target：**当模块不存在指定的 target 时会选用 default 进行构建，但如果不想用 default 进行构建，那么可以配置 fallback target，当找不到指定 target 时，如果模块中存在 fallback target，则使用 fallback target 进行构建。fallback target 作用范围是整个工程，可配置多个，配置多个时按数组顺序先命中的生效。

• 命令行方式示例如下：

hvigorw -c properties.ohos.fallback.target=target1,target2 assembleHap

• 在 hvigor-config.json5 配置文件中添加 ohos.fallback.target，示例如下：

"properties": { 'ohos.fallback.target': ['target1', 'target2'] }

说明

• align target 和 fallback target 配置方式命令行优先级高于配置文件。
• 使用配置文件配置 align target 和 fallback target，仅支持 DevEco Studio 界面 Build 菜单栏功能，不支持 Run 菜单栏功能，可通过 hdc 命令行工具进行推包运行、调试。

多个 target 的优先级顺序为：align target > 命令行指定模块 target > 父级模块 target > fallback target > default。

举例说明：

工程依赖 entry->lib1->lib2，需要构建多个产品 A、B、C，工程中 target 配置如下：

entry: A、B、default lib1: B、C、default lib2: A、C、default

指定 align target 为 A，fallback target 为 C。那么构建 hap 时的编译命令为：

hvigorw --mode module -p module=entry -c properties.ohos.align.target=A -c properties.ohos.fallback.target=C assembleHap

编译的 target 选择就是：entry@A, lib1@C, lib2@A。

说明

以上所有说明仅针对非 ohosTest 模式。在 ohosTest 模式下，依赖的 target 固定为 default，其他 target 均不生效。