【HarmonyOS Next之旅】DevEco Studio使用指南(三十五) -＞ 配置构建(二)_harmony stagemode import路径别名

目录

1 -> 定制HAP多目标构建产物

1.1 -> 定义产物的HAP包名

1.2 -> 定义产物的deviceType

1.3 -> 定义产物的distributionFilter

1.4 -> 定义产物preloads的分包

1.5 -> 定义产物的source源码集-pages

1.6 -> 定义产物的source源码集-sourceRoots

1.7 -> 定义产物的资源

1.8 -> 定义产物的icon、label、launchType

1.9 -> 定义C++工程依赖的.so文件

2 -> 构建定义的目标产物

3 -> 调试和运行指定的Target

1 -> 定制HAP多目标构建产物

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

定义目标产物target

每一个target对应一个定制的HAP，因此，在定制HAP多目标构建产物前，应提前规划好需要定制的target名称。例如，以ArkTS Stage模型为例，定义一个免费版和付费版，模块级build-profile.json5文件示例如下：

{ \"apiType\": \'stageMode\', \"buildOption\": { }, \"targets\": [ //定义不同的target { \"name\": \"default\", //默认target名称default }, { \"name\": \"free\", //免费版target名称 }, { \"name\": \"pay\", //付费版target名称 } ] }

按照上述target的定义，在编译构建时，会同时打包生成default、free和pay三个不同的HAP。

1.1 -> 定义产物的HAP包名

每一个target均可以指定产物命名。

{ \"apiType\": \"stageMode\", \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", \"output\": { \"artifactName\": \"customizedTargetOutputName-1.0.0\" //产物名称为customizedTargetOutputName-1.0.0 } }, { \"name\": \"free\", \"output\": { \"artifactName\": \"customizedTargetOutputName1-1.0.0\" //产物名称为customizedTargetOutputName1-1.0.0 } }, { \"name\": \"pay\", \"output\": { \"artifactName\": \"customizedTargetOutputName2-1.0.0\" //产物名称为customizedTargetOutputName2-1.0.0 } } ] }

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

1.2 -> 定义产物的deviceType

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

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

{ \"apiType\": \'stageMode\', \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", //未定义deviceType，默认支持config.json或module.json5中定义的设备类型 }, { \"name\": \"free\", \"config\": { \"deviceType\": [ //定义free支持的设备类型为phone  \"phone\" ] } }, { \"name\": \"pay\", \"config\": { \"deviceType\": [ //定义pay支持的设备类型为phone  \"phone\" ] } } ] }

1.3 -> 定义产物的distributionFilter

在未定义target的分发规则distributionFilter时，以module配置distroFilter/distributionFilter分发规则为准。

针对多target存在相同设备类型deviceType的场景，相同设备类型的target需要指定分发规则distributionFilter。

如果是FA工程，请将distributionFilter字段替换为distroFilter。

{ \"apiType\": \"stageMode\", \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", }, { \"name\": \"free\", \"config\": { \"distributionFilter\": { // 具体请参考distributionFilter标签 \"screenShape\": { // 屏幕形状枚举 \"policy\": \"include\", \"value\": [\"circle\"]  } } } }, { \"name\": \"pay\", \"config\": { \"distributionFilter\": {  \"screenShape\": { \"policy\": \"include\", \"value\": [\"rect\"]  } } } } ] }

1.4 -> 定义产物preloads的分包

对于元服务，每一个target均可以指定preloads的分包，也可以不定义。如果不定义，则以module.json5中的配置为准。

{ \"apiType\": \'stageMode\', \"showInServiceCenter\": true, \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", }, { \"name\": \"free\", }, { \"name\": \"pay\", \"config\": { \"atomicService\": {  \"preloads\": [ //指定preloads的分包 {  \"moduleName\": \"preloadSharedLibrary\" }  ] } } } ] }

1.5 -> 定义产物的source源码集-pages

对于source源码集的定制，由于Stage模型和FA模型的差异，Stage模型支持对pages源码目录的page页面进行定制，FA模型则支持对Ability源码目录下的page页面进行定制。

• 例如，Stage模型中的工程，在模块的pages目录下分别定义了Index.ets、Page1.ets和Page2.ets三个页面。其中default使用了Index.ets页面；free使用了Index.ets和Page1.ets页面；pay使用了Index.ets和Page2.ets页面，则示例代码如下所示：

{ \"apiType\": \'stageMode\', \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", \"source\": { //定义Stage模型中默认版target的pages源码文件 \"pages\": [ \"pages/Index\" ] } }, { \"name\": \"free\", \"config\": { \"deviceType\": [ \"phone\" ] }, \"source\": { //定义Stage模型中免费版target的pages源码文件 \"pages\": [ \"pages/Index\", \"pages/Page1\" ] } }, { \"name\": \"pay\", \"config\": { \"deviceType\": [ \"phone\" ] }, \"source\": { //定义Stage模型中付费版target的pages源码文件 \"pages\": [ \"pages/Index\", \"pages/Page2\" ] } } ] }

• 例如，FA模型中的工程，在模块的MainAbility中定义了index.ets、page1.ets和page2.ets，其中：default使用了index.ets 页面；free使用了index.ets和page1.ets页面；pay使用了index.ets和page2.ets页面。

{ \"apiType\": \'faMode\', \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", \"source\": { //定义FA模型中默认版target的pages源码文件 \"abilities\": [ {  \"name\": \".MainAbility\",  \"pages\": [ \"pages/index\"  ] } ], } }, { \"name\": \"free\", \"config\": { \"deviceType\": [ \"phone\" ] }, \"source\": { //定义FA模型中免费版target的pages源码文件 \"abilities\": [ {  \"name\": \".MainAbility\",  \"pages\": [ \"pages/index\", \"pages/page1\"  ] } ], } }, { \"name\": \"pay\", \"config\": { \"deviceType\": [ \"phone\" ] }, \"source\": { //定义FA模型中付费版target的pages源码文件 \"abilities\": [ {  \"name\": \".MainAbility\",  \"pages\": [ \"pages/index\", \"pages/page2\"  ] } ], } } ] }

1.6 -> 定义产物的source源码集-sourceRoots

在模块的主代码空间(src/main)下，承载着开发者编写的公共代码。如果开发者需要实现不同target之间的差异化逻辑，可以使用差异化代码空间(sourceRoots)。配合差异化代码空间的能力，可以在主代码空间中代码不变的情况下，针对不同的target，编译对应的代码到最终产物中。

概念说明

• packageName：当前模块的oh-package.json5中的name字段对应的值。
• sourceRoot： | ，其中是 src/main，可自定义，寻址优先级为 > 。
• sourcePath：在sourceRoot中的代码结构目录。
• sourceFileName：代码目录下的ets文件名。

例如以下工程目录：

entry
|--src
|----main
|------ets
|--------code
|----------test.ets
|----target
|------util
|--------util.ets
|--index.ets

• packageName为entry。
• sourceRoot为src/main、src/target。
• sourcePath为ets/code、util。
• sourceFileName为test.ets、util.ets。

规格限制

1. import xxx from \'/sourcePath/sourceFileName\' ：通过packageName的方式，省略sourceRoot，可以实现不同target下的差异化构建。

2. 支持hap、hsp、har（请注意：开启文件/文件夹名称混淆的har模块需要使用-keep-file-name指定sourceRoot，sourcePath，sourceFileName对应的文件/文件夹名称不被混淆）。

3. 不支持跨模块引用。

4. 不支持动态import。

编译时模块target的选择优先级说明

在模块编译的过程中，该模块使用的sourceRoots由当前模块编译时的target来决定。当前模块编译时选择target的优先级则为：命令行显式指定 > 直接引用方target > default。

如以下示例：

hap -> hsp -> har（->表示依赖）

其中hap和hsp存在三个target：default、custom、static，而har存在两个target：default、static。

• 执行编译命令：hvigorw -p module=hap@custom assembleHap，hap指定target为custom进行编译，那么三个模块编译时的target分别为：

  hap: custom，命令行显式指定；

  hsp: custom，命令行没有显式指定，则基于直接引用方查找，hsp的直接引用方为hap，hap的target为custom，hsp存在该target，则hsp的target为custom；

  har: default，命令行没有显式指定，则基于直接引用方查找，har的直接引用方为hsp，hsp的target为custom，har不存在该target，则har的target为default；

• 执行编译命令：hvigorw -p module=hap@custom,hsp@static assembleHap assembleHsp，hap指定target为custom，hsp则指定target为static进行编译，那么三个模块编译时的target分别为：

  hap: custom，命令行显式指定；

  hsp: static，命令行显式指定；

  har: static，命令行没有显式指定，则基于直接引用方查找，har的直接引用方为hsp，hsp的target为static，har存在该target，则har的target为static。

• 在当前依赖关系的基础上，添加依赖：hap -> har。执行编译命令：hvigorw -p module=hap@custom,hsp@static assembleHap assembleHsp。由于har没有显示指定target，且存在两个target不同的直接引用方（hap和hsp，对应的target分别为custom和static），所以编译过程中har的target只能二选一。基于这种场景，建议开发者显示指定模块的target进行编译：hvigorw -p module=hap@custom,hsp@static,har@static assembleHap assembleHsp assembleHar。

示例

1. 在entry模块的build-profile.json5中添加sourceRoots：

{ \"apiType\": \"stageMode\", \"buildOption\": {}, \"targets\": [ { \"name\": \"default\", \"source\": { \"sourceRoots\": [\"./src/default\"] // 配置target为default的差异化代码空间 } }, { \"name\": \"custom\", \"source\": { \"sourceRoots\": [\"./src/custom\"] // 配置target为custom的差异化代码空间 } } ]}

2. 在src目录下新增default/Test.ets和custom/Test.ets，新增后的模块目录结构：

entry
  |--src
    |--main
      |--ets
        |--pages
          |--Index.ets
    |--default
      |--Test.ets  // 新增
    |--custom
      |--Test.est  // 新增  

3. 在default/Test.ets中写入代码：

export const getName = () => \"default\"

4. 在custom/Test.ets中写入代码：

export const getName = () => \"custom\"

5. 修改src/main/ets/pages/Index.ets的代码：

import { getName } from \'entry/Test\'; // 其中entry为模块级的oh-package.json5中的name字段的值@Entry@Componentstruct Index { @State message: string = getName(); build() { RelativeContainer() { Text(this.message) } .height(\'100%\') .width(\'100%\') }}

6. 在工程级的build-profile.json5中配置targets：

{ \"app\": { \"signingConfigs\": [], \"products\": [ { \"name\": \"default\", \"signingConfig\": \"default\", \"compatibleSdkVersion\": \"5.0.2(14)\", \"runtimeOS\": \"HarmonyOS\", }, { \"name\": \"custom\", \"signingConfig\": \"default\", \"compatibleSdkVersion\": \"5.0.2(14)\", \"runtimeOS\": \"HarmonyOS\", } ], \"buildModeSet\": [ { \"name\": \"debug\", }, { \"name\": \"release\" } ] }, \"modules\": [ { \"name\": \"entry\", \"srcPath\": \"./entry\", \"targets\": [ { \"name\": \"default\", \"applyToProducts\": [ \"default\" ] }, { \"name\": \"custom\", \"applyToProducts\": [ \"default\" ] } ] } ]}

7. Sync完成后，选择entry的target为default，点击Run，界面展示default；选择entry的target为custom，点击Run，则界面展示custom。

1.7 -> 定义产物的资源

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

{ \"apiType\": \'stageMode\', \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", \"source\": { \"pages\": [  \"pages/Index\" ] }, \"resource\": { //定义默认版target使用的资源文件目录 \"directories\": [  \"./src/main/resources_default\" ] } }, { \"name\": \"free\", \"config\": { \"deviceType\": [  \"phone\" ] }, \"source\": {  \"pages\": [  \"pages/Index\",  \"pages/Page1\" ] }, \"resource\": { //定义免费版target使用的资源文件目录 \"directories\": [  \"./src/main/resources_default\",  \"./src/main/resources_free\" ] } }, { \"name\": \"pay\", \"config\": { \"deviceType\": [  \"phone\" ] }, \"source\": {  \"pages\": [  \"pages/Index\",  \"pages/Page2\" ] }, \"resource\": { //定义付费版target使用的资源文件目录，该功能在API 9及以上版本的工程中生效 \"directories\": [  \"./src/main/resources_default\",  \"./src/main/resources_pay\" ] } } ] }

请注意，如果target引用的多个资源文件目录下，存在同名的资源，则在构建打包过程中，将按照配置的资源文件目录顺序进行选择。例如，上述付费版target引用的资源中，resource_default和resource_pay中存在同名的资源文件，则resource_default中的资源会被打包到HAP中。

1.8 -> 定义产物的icon、label、launchType

针对每一个的target的ability，均可以定制不同的icon、label和launchType。如果不定义，则该target采用module.json5中module.abilities配置的icon、label，launchType默认为\"singleton\"。示例如下所示：

{ \"apiType\": \'stageMode\', \"buildOption\": { }, \"targets\": [ { \"name\": \"default\", \"source\": { \"abilities\": [ { \"name\": \"EntryAbility\", \"icon\":\"$media:layered_image\", \"label\":\"$string:EntryAbility_label\", \"launchType\": \"singleton\" } ] } }, { \"name\": \"free\", \"source\": { \"abilities\": [ { \"name\": \"EntryAbility\", \"icon\":\"$media:layered_image\", \"label\":\"$string:EntryAbility_label\", \"launchType\": \"multiton\" } ] } } ] }

1.9 -> 定义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\": [ //定义不同的target { \"name\": \"default\", \"config\": { \"buildOption\": { \"nativeLib\": { \"filter\": {  //按照.so文件的优先级顺序，打包最高优先级的function1.so文件  \"pickFirsts\": [ \"**/function1.so\"  ],  //排除不打包的function3.so文件  \"excludes\": [ \"**/function3.so\"  ],  //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件  \"enableOverride\": true } } } } }, { \"name\": \"vip\", \"config\": { \"buildOption\": { \"nativeLib\": { \"filter\": {  //按照.so文件的优先级顺序，打包最高优先级的function1.so文件  \"pickFirsts\": [ \"**/function1.so\"  ],  //排除不打包的function2.so文件  \"excludes\": [ \"**/function2.so\"  ],  //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件  \"enableOverride\": true } } } } } ]}

2 -> 构建定义的目标产物

每个target对应一个HAP，每个product对应一个APP包，在编译构建时，如果存在多product或多target时，您可以指定编译具体的包。

单击右上角的

图标，指定需要打包的Product及Target，然后单击Apply保存。例如选择\"ProductA\"中，entry模块对应的\"free\" Target。

• Product：选择需要构建的 APP 包。
• Build Mode：选择编译模式。
• Product Info：该APP包的BundleName和SigningConfig信息。
• Target Select：选择各个模块的Target，该Target需要包含在定义的Product中才能选择，如果未包含则显示\"No Target to apply\"。

然后执行编译构建APP/HAP的任务：

• 单击菜单栏的Build > Build Hap(s)/APP(s) > Build APP(s) ，构建指定的Product对应的APP。例如，按照上述设置，此时DevEco Studio将构建生成 ProductA 的 APP 包。default和ProductB的APP均不会生成。
• 单击菜单栏的Build > Build Hap(s)/APP(s) > Build Hap(s)，构建指定Product下的所有Target对应发的HAP。例如，按照上述配置，此时DevEco Studio将构建生成entry模块下default和free的HAP。

如果您想将某个模块下的指定target打包生成HAP，可以在工程目录中，单击模块名，然后再单击Build > Make Module ‘模块名 ’，此时DevEco Studio将构建生成模块下指定target对应的包。例如，按照上述配置，此时DevEco Studio将构建生成entry模块下free的HAP，不会生成default的HAP。

3 -> 调试和运行指定的Target

使用DevEco Studio调试或运行应用/元服务时，每个模块只能选择其中的一个target运行，可以通过单击右上角的

图标，指定需要调试或运行的Product下对应的Module Target，然后单击Apply保存。

说明

在选择需要调试或运行的target时，需要注意选择该target所属的Product，否则将找不到可调试和运行的target。

感谢各位大佬支持！！！

互三啦！！！