鸿蒙5.0开发进阶：配置文件（工程级build-profile.json5文件）
往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）
-
鸿蒙开发核心知识点，看这篇文章就够了
-
最新版！鸿蒙HarmonyOS Next应用开发实战学习路线
-
鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
-
鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）
工程级build-profile.json5文件
配置文件结构
工程级build-profile.json5文件整体的结构如下。
app└── signingConfigs └── name └── material └── storePassword └── certpath └── keyAlias └── keyPassword └── profile └── signAlg └── storeFile └── type└── products └── name └── signingConfig └── bundleName └── buildOption └── packOptions └── buildAppSkipSignHap └── debuggable └── resOptions └── compression └── media └── enable └── filters └── method └── type └── blocks └── files └── path └── size └── resolution └── exclude └── path └── size └── resolution └── copyCodeResource └── enable └── excludes └── externalNativeOptions └── path └── abiFilters └── arguments └── cppFlags └── sourceOption └── workers └── nativeLib └── filter └── excludes └── pickFirsts └── pickLasts └── enableOverride └── select └── package └── version └── include └── exclude └── debugSymbol └── strip └── exclude └── headerPath └── collectAllLibs └── excludeFromHar └── excludeSoFromInterfaceHar └── napiLibFilterOption └── excludes └── pickFirsts └── pickLasts └── enableOverride └── arkOptions └── buildProfileFields └── types └── tscConfig └── targetESVersion └── autoLazyImport └── branchElimination └── apPath └── hostPGO └── strictMode └── noExternalImportByPath └── useNormalizedOHMUrl └── caseSensitiveCheck └── duplicateDependencyCheck └── harLocalDependencyCheck └── nativeCompiler └── removePermissions └── name └── runtimeOS └── arkTSVersion └── compileSdkVersion └── compatibleSdkVersion └── targetSdkVersion └── bundleType └── label └── icon └── versionCode └── versionName └── resource └── directories └── output └── artifactName └── vendor└── buildModeSet └── name └── buildOption└── multiProjectsmodules└── name└── srcPath└── targets └── name └── applyToProducts配置文件字段说明
工程级build-profile.json5文件包含以下字段。
字段名称
类型
是否必选
含义
app
对象
必选
编译配置信息。
modules
对象数组
必选
工程中包含的所有模块的信息，数组长度至少为1。
app
app是工程级的编译配置，包含签名、product等信息。
字段名称
类型
是否必选
含义
signingConfigs
对象数组
签名方案信息，可配置多个。
products
对象数组
可选
产品品类，可配置多个。如需配置多个，相关说明请参见配置多目标产物章节。
buildModeSet
对象数组
可选
构建模式集合，可配置多个。
multiProjects
布尔值
可选
当前工程是否支持多工程构建：
- true：支持。
- false（缺省默认值）：不支持。
字段名称
类型
是否必选
含义
name
必选
构建模式名称。默认生成debug，release和test三个名称，支持开发者自定义，其中test模式仅在执行ohosTest测试套件时使用。
buildOption
对象
可选
构建模式使用的具体配置信息。
modules
modules是一个对象数组，用于描述工程中包含的所有模块，数组长度至少为1。模块配置包括名称、路径和target-product关联配置。
字段名称
类型
是否必选
含义
name
字符串
必选
模块的名称。该名称需与module.json5文件中的module.name保持一致。
在FA模型中，对应的文件为config.json。
srcPath
字符串
必选
模块的源码路径，为模块根目录相对工程根目录的相对路径，允许模块根目录不在当前工程下。
说明
当前支持引用其他工程下的HAR和HSP模块。
targets
对象数组
可选
模块的target信息，用于定制多目标构建产物时，配置模块target和应用product之间的关联关系。
字段名称
类型
是否必选
含义
name
字符串
必选
target名称，在各个模块级build-profile.json5中的targets字段定义。HAR模块无需配置。
applyToProducts
字符串数组
可选
target关联的product。HAR模块无需配置。
modules字段示例：
{ \"modules\": [ { \"name\": \"entry\", \"srcPath\": \"./entry\", \"targets\": [ { \"name\": \"default\", \"applyToProducts\": [ \"default\" // 表示将该模块下的\"default\" Target打包到\"default\" Product中 ] } ] } ]}signingConfigs
signingConfigs是一个对象数组，用于配置签名方案，可配置多个。
字段名称
类型
是否必选
含义
name
字符串
必选
签名方案的名称，不允许为空字符串。
material
对象
必选
签名方案相关材料，如密码、证书等。
通过File > Project Structure... > Project > Signing Configs界面，进行自动签名后，material节点中的各配置项会自动填充。
type
字符串
可选
签名类型：
- HarmonyOS
- OpenHarmony
字段名称
类型
是否必选
含义
storePassword
字符串
必选
密钥库密码，以密文形式呈现。
certpath
字符串
必选
调试或发布证书文件地址，文件后缀为.cer。
keyAlias
字符串
必选
密钥别名信息。
keyPassword
字符串
必选
密钥密码，以密文形式呈现。
profile
字符串
必选
调试或发布证书Profile文件地址，文件后缀为.p7b。
signAlg
字符串
必选
密钥库signAlg参数。当前可配置值SHA256withECDSA。
storeFile
字符串
必选
密钥库文件地址，文件后缀为.p12。
signingConfigs字段示例：
{ \"app\": { \"signingConfigs\": [ { \"name\": \"default\", \"type\": \"HarmonyOS\", \"material\": { \"certpath\": \"D:\\\\SigningConfig\\\\debug_hos.cer\", \"storePassword\": \"******\", \"keyAlias\": \"debugKey\", \"keyPassword\": \"******\", \"profile\": \"D:\\\\SigningConfig\\\\debug_hos.p7b\", \"signAlg\": \"SHA256withECDSA\", \"storeFile\": \"D:\\\\SigningConfig\\\\debug_hos.p12\" } } ] }}products
products是一个对象数组，用于配置产品品类信息，可配置多个，如通用默认版、付费版、免费版等。。
字段名称
类型
是否必选
含义
name
字符串
必选
产品的名称，必须存在name为\"default\"的product。
signingConfig
字符串
可选
当前产品品类的签名方案名称，需要在signingConfigs.name中定义。
bundleName
字符串
可选
产品的包名。
buildOption
对象
可选
产品的编译构建配置。
runtimeOS
字符串
可选
产品的运行环境：
- HarmonyOS
- OpenHarmony
arkTSVersion
字符串
可选
ArkTS语法检查工具的版本号：1.0，1.1。
默认为当前ArkTS语法检查工具支持的最新版本。
仅API 11及以上版本工程支持。
compileSdkVersion
字符串/整型数值
可选
标识编译应用/元服务所使用的SDK版本。
- 运行环境是HarmonyOS时，字段类型为字符串，配置示例：5.0.3(15)
- 运行环境是OpenHarmony时，字段类型为整型数值，配置示例：15
说明
从DevEco Studio NEXT Developer Beta1（5.0.3.403）版本开始，该字段不需要显性配置，编译时默认使用配套的SDK版本。如果配置，只能配置为当前DevEco Studio配套的SDK版本，不允许配置为其他SDK版本。
compatibleSdkVersion
字符串/整型数值
必选
标识应用/元服务运行所需兼容的最低SDK版本，应用/元服务不能安装在低于该版本的设备。
targetSdkVersion
字符串/整型数值
可选
标识应用/元服务运行所需目标SDK版本，是系统提供的前向兼容手段。如果新SDK版本中API行为发生变更，将应用/元服务安装到新系统后，可通过该字段提供向前兼容手段，在新系统版本保持老的API行为。如未配置，默认与compileSdkVersion保持一致。
bundleType
字符串
可选
包的类型：
- app：应用
- atomicService：元服务
- shared：共享包
label
字符串
可选
应用/元服务名称。
说明
配置products中的label、icon、versionCode、versionName、resource字段后，编译构建时将根据此处的配置替换app.json5中的相关配置，常用于应用和元服务可分可合构建打包场景。
icon
字符串
可选
应用/元服务图标。
versionCode
整型数值
可选
版本号。
versionName
字符串
可选
版本名称。
resource
对象
可选
名称和图标对应的资源所在目录。
output
对象
可选
定制产品生成的应用包的配置。
vendor
字符串
可选
供应商。
字段名称
类型
是否必选
含义
directories
字符串数组
必选
资源地址路径。
字段名称
类型
是否必选
含义
artifactName
字符串
必选
自定义产品生成的应用包名称，可由数字、英文字母、中划线、下划线和英文句号（.）组成，支持输入版本号。
products字段示例：
{ \"products\": [ { \"name\": \"default\", \"signingConfig\": \"default\", \"bundleName\": \"com.example.myapplication\", \"compatibleSdkVersion\": \"5.0.3(15)\", \"runtimeOS\": \"HarmonyOS\", \"arkTSVersion\": \"1.1\", \"bundleType\": \"app\", \"label\": \"$string:app_name\", \"icon\": \"$media:application_icon\", \"versionCode\": 1000000, \"versionName\": \"1.0.0\", \"resource\": { \"directories\": [ \"./AppScope/resources\" ] }, \"output\": { \"artifactName\": \"customizedTargetOutputName-1.0.0\" }, \"vendor\": \"customizedProductVendorName\", } ]}buildOption
buildOption是构建使用的具体配置信息，buildModeSet和products下均支持配置buildOption。此外，模块级build-profile.json5中也支持配置buildOption。工程级别buildOption配置会与模块级别的buildOption进行合并。
字段名称
类型
是否必选
含义
packOptions
对象
可选
打包相关配置项。
debuggable
布尔值
可选
当前编译产物是否为可调试模式：
- true（缺省默认值）：可调试。
- false：不可调试。
当使用release的编译模式时，默认为false。
resOptions
对象
可选
资源编译配置项。
externalNativeOptions
对象
可选
Native编译配置项。
sourceOption
对象
可选
源码相关配置。使用不同的标签对源代码进行分类，以便在构建过程中对不同的源代码进行不同的处理。
nativeLib
对象
可选
Native 库（.so）相关配置。
napiLibFilterOption
对象
可选
NAPI库（.so）文件的筛选选项。标记为废弃，不建议使用，推荐使用nativeLib/filter。
arkOptions
对象
可选
ArkTS 编译配置。
strictMode
对象
可选
严格模式。
nativeCompiler
字符串
可选
指定Native编译时使用的编译器，包括：
- Original（缺省默认值）：原有的OpenHarmony Native编译器。
- BiSheng：使用毕昇编译器进行Native编译。
说明
- 从API 12开始支持。
removePermissions
对象数组
可选
编译HAP/HSP模块时，指定需要删除的依赖包中的冗余权限，模块本身的权限不会被删除。
packOptions
packOptions是打包相关配置项。
字段名称
类型
是否必选
含义
buildAppSkipSignHap
布尔值
可选
是否跳过生成签名HAP：
- true：跳过，即不生成签名HAP。
- false（缺省默认值）：不跳过，即生成签名HAP。
编译构建APP时，无需生成签名HAP，可将此参数修改为true，从而提升编译构建性能。
\"buildOption\": { \"packOptions\": { \"buildAppSkipSignHap\": true }}sourceOption
sourceOption是源码相关配置，使用不同的标签对源代码进行分类，以便在构建过程中对不同的源代码进行不同的处理。
字段名称
类型
是否必选
含义
workers
字符串数组
可选
指定使用node.js工作器的JS/TS源代码，源代码在构建过程中单独处理。
sourceOption字段示例：
\"buildOption\": { \"sourceOption\": { \"workers\": [ \"./src/main/ets/common/constants/CommonConstants.ets\" ] }}napiLibFilterOption
napiLibFilterOption是NAPI库（.so）文件的筛选选项，字段已废弃，不建议使用，推荐使用nativeLib/filter。
字段名称
类型
是否必选
含义
excludes
字符串数组
可选
排除的.so文件。罗列的NAPI库将不会被打包。
pickFirsts
字符串数组
可选
按照.so文件的优先级顺序，打包最高优先级的.so文件。
pickLasts
字符串数组
可选
按照.so文件的优先级顺序，打包最低优先级的.so文件。
enableOverride
布尔值
可选
是否允许当.so文件重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件：
- true：允许。
- false（缺省默认值）：不允许。
arkOptions
arkOptions是ArkTS编译配置。
字段名称
类型
是否必选
含义
buildProfileFields
对象
可选
用于ArkTS的构建配置。自定义类型，key可由数字、英文、下划线、中划线组成，value类型仅支持string、number、boolean。
types
字符串数组
可选
自定义类型，可配置包名或d.ts/d.ets文件路径。
tscConfig
对象
可选
与编译TS语法相关的配置选项。
autoLazyImport
布尔值
可选
编译时是否自动将符合lazy-import语法规范的import语句添加\"lazy\"关键字。仅支持在源码中添加\"lazy\"关键字，不包含依赖的字节码HAR包或HSP。
- true：添加。
- false（缺省默认值）：不添加。
说明
如果配置为true，编译时不会做场景识别，即源码中任何符合语法规范的import语句都会被添加\"lazy\"。
branchElimination
布尔值
可选
是否启用代码分支裁剪，减少编译产物大小，开启后，在release编译模式下，不会被执行到的代码分支会被裁剪掉，示例如下：
# 编译生成的BuildProfile文件export const DEBUG = false;export const VERSION_CODE = 100;# 开发者自定义的ets文件import { DEBUG } from \'BuildProfile\';import { VERSION_CODE } from \'BuildProfile\';if (DEBUG) {XXX} // 该分支会被裁剪掉else {XXX}if (VERSION_CODE){XXX} // 该语法发生了类型转换，不支持代码裁剪。if (VERSION_CODE === 100){XXX} // 若需要裁剪代码，使用该方式，显式指定判断条件为boolean类型。- true：启用（将导致使用\"ApplyChanges\"功能时，对const声明的常量的值进行的修改可能不生效）。
- false（缺省默认值）：不启用。
说明
- 仅支持API 11及以上的Stage模型。
- HAR模块仅字节码HAR配置生效，非字节码HAR配置不生效。
- 仅支持const声明的bool类型常量和const声明的string/number类型常量的判断表达式。
- 不支持间接导入，例如A文件中定义const变量A1，B文件导入A1，导出B1，ets导入B1进行判断，无法进行裁剪。
apPath
字符串
可选
说明
API 11及以上版本不再支持，即该字段配置后不再生效。
应用热点信息文件路径。
hostPGO
布尔值
可选
是否启用配置文件引导优化功能：
- true：启用。
- false（缺省默认值）：不启用。
从API 10开始废弃，由于partial模式可能存在兼容性问题，请使用Target AOT能力，不建议使用Host AOT。
字段名称
类型
是否必选
含义
targetESVersion
字符串
可选
指定TS语法编译产物的目标运行时EcmaScript版本，包括：
- ES2017
- ES2021（缺省默认值）。
arkOptions字段示例：
\"buildOption\": { \"arkOptions\": { \"buildProfileFields\": { \"targetData\": \"TargetData\", \"data\": \"DataTargetDefault\" }, \"tscConfig\": { \"targetESVersion\": \"ES2021\", }, \"autoLazyImport\": true, \"branchElimination\": true }}strictMode
strictMode用于定义严格模式。
字段名称
类型
是否必选
含义
noExternalImportByPath
布尔值
可选
是否严格检查绝对路径导入方式和相对路径跨模块导入方式。
- true：严格检查。
- false：不严格检查。
说明
从DevEco Studio NEXT Beta1（5.0.3.800）版本开始，当工程级build-profile.json5中useNormalizedOHMUrl配置为true时，noExternalImportByPath缺省默认值为true；当useNormalizedOHMUrl配置为false时，noExternalImportByPath缺省默认值为false。
useNormalizedOHMUrl
布尔值
可选
是否使用标准化的OHMUrl（OHMUrl的定义参考以下说明）格式，标准化的OHMUrl统一了原有OHMUrl的格式。使用集成态HSP和字节码HAR需使用标准化的OHMUrl格式。
- true：使用标准化的OHMUrl格式。
- false（缺省默认值）：不使用标准化的OHMUrl格式。
说明
- 从API 12开始支持。
- 一个ets文件在编译后会成为安装包的一部分，这个ets文件对应的字节码称为一个字节码段，OHMUrl是用来定位一个字节码段的标识。
- 若工程引用了HAR/HSP，需确保工程的useNormalizedOHMUrl配置和HAR/HSP的useNormalizedOHMUrl配置保持一致，同时配置为true或false。
- 从DevEco Studio NEXT Beta1（5.0.3.800）版本开始，当useNormalizedOHMUrl设置为true时，不允许通过相对路径跨模块或绝对路径导入文件，oh-package.json5中依赖的包使用的别名需要和依赖包的oh-package.json5的name保持一致。
caseSensitiveCheck
布尔值
可选
导入文件是否严格校验大小写，支持相对路径和软链接。
- true：严格校验。
- false（缺省默认值）：不严格校验。
duplicateDependencyCheck
布尔值
可选
是否校验本地HSP模块有无依赖相同的HAR。仅在Build App(s)起效。
- true：如果本地HSP模块依赖了相同的HAR（包括本地/远程、直接/间接），则编译报错。（注意：当依赖链中存在远程HSP，则该远程HSP及其依赖链不参与校验）。
- false（默认缺省值）：不启用校验。
harLocalDependencyCheck
布尔值
可选
是否对HAR产物启用本地依赖校验。
- true：如果oh-package.json中的dependencies、dynamicDependencies存在本地依赖，则编译报错。
- false（默认缺省值）：不启用校验。
说明
除HAR模块外，HSP模块编译时也会生成HAR产物，该配置同样生效。
strictMode字段示例：
\"buildOption\": { \"strictMode\": { \"noExternalImportByPath\": true, \"useNormalizedOHMUrl\": true, \"caseSensitiveCheck\": true, \"duplicateDependencyCheck\": true, \"harLocalDependencyCheck\": true, }}removePermissions
removePermissions是一个对象数组，用于编译HAP/HSP模块时，指定需要删除的依赖包中的冗余权限，模块本身的权限不会被删除。
字段名称
类型
是否必选
含义
name
字符串
必选
待删除的权限名称，需要包含在依赖包的module.json的requestPermissions中。
removePermissions字段示例：
\"buildOption\": { \"removePermissions\": [ { \"name\": \"ohos.permission.ABILITY_BACKGROUND_COMMUNICATION\" }, { \"name\": \"ohos.permission.ACCELEROMETER\" } ]}resOptions
resOptions是资源编译配置项。
字段名称
类型
是否必选
含义
compression
对象
可选
对工程预置图片资源进行纹理压缩的编译配置参数。
copyCodeResource
对象
可选
对模块的src/main/ets目录下的资源文件（非源码文件）拷贝的编译配置参数。
说明
该字段对不开启混淆的源码HAR不生效。
字段名称
类型
是否必选
含义
enable
布尔值
可选
是否将ets目录下的资源文件打包到产物中。
- true（缺省默认值）：打包。
- false：不打包。
excludes
字符串数组
可选
根据glob语法排除匹配到的文件，匹配到的文件不会被打包到产物中。当enable配置为false时excludes不生效。
copyCodeResource字段示例：
\"buildOption\": { \"resOptions\": { \"copyCodeResource\": { \"enable\": true, \"excludes\": [\'./entry/src/main/ets/component/big_picture.png\', \'**/*.yml\', \'**/subDir/**\'], } }}compression
compression是对工程预置图片资源进行纹理压缩的编译配置参数。
字段名称
类型
是否必选
含义
media
对象
可选
对资源目录下media目录的图片进行纹理压缩的配置参数。
filters
对象数组
可选
文件过滤配置参数。
说明
编译过程中会依次遍历图片文件，并与filters条件进行匹配，一旦匹配成功，则完成该图片的处理。当工程级和模块级同时配置时，先按照模块级的过滤条件匹配，一旦匹配成功，则忽略工程级的过滤条件；如果模块级的没有匹配成功，继续按工程级的条件进行匹配。
media
media是对资源目录下media目录的图片进行纹理压缩的配置参数。
字段名称
类型
是否必选
含义
enable
布尔值
可选
是否对media图片启用纹理压缩。
- true：启用。
- false（缺省默认值）：不启用。
说明
- 在linux系统的构建场景下，请确认系统环境已安装libGL1库。
- 对图片进行纹理压缩会改变文件名称和内容，在分层图标以及二次编辑的场景下会引起图片显示异常，请进一步使用filters排除掉这部分文件。
filters
filters是文件过滤配置参数。
字段名称
类型
是否必选
含义
method
对象
必选
纹理压缩的方式。
files
对象
可选
指定用来参与压缩的文件，与exclude字段配合使用。
exclude
对象
可选
从files中剔除掉不需要压缩的文件。
字段名称
类型
是否必选
含义
type
字符串
必选
转换类型。
- astc（Adaptive Scalable Texture Compression）：自适应可变纹理压缩，一种对GPU友好的纹理格式，可在设备侧更快地显示，有更少的内存占用。
- sut（SUper compression for Texture） ：纹理超压缩，可在设备侧更快地显示，有更少的内存占用，相比astc具备更大压缩率和更少ROM占用。
blocks
字符串
必选
astc/sut转换类型的扩展参数，决定画质和压缩率，当前仅支持\"4x4\"。
字段名称
类型
是否必选
含义
path
字符串数组
可选
指定“按路径匹配”的过滤条件，符合glob规范，格式为相对路径，配置示例：
\"path\": [ \"./entry/src/main/resources/base/media/big_picture.png\"]size
二维数组
可选
指定“按大小匹配”的过滤条件，格式为[min,max]，闭区间，表示大小从min到max之间的文件，配置示例：
\"size\"：[ [0, \'1k\'], // 0 ~ 1*1024 [\'1024\', \'2k\'], // 1024 ~ 2*1024 [\'3K\'] // 3*1024 ~ 无限大]- 每个数值可以填数字、字符串或字符串中带单位(大小写均可)。
- 单位K/k=1024，M/m=1024*1024，G/g=1024*1024*1024。
- 区间最大值可省略，表示无限大。
resolution
二维数组
可选
指定“按分辨率匹配”的过滤条件，配置示例：
resolution:[ [ { width:32, height:32 }, // 最小宽高 { width:64, height:64 }, // 最大宽高 ], // 分辨率在32*32到64*64之间的图片 [ { width:200, height:200 }, // 最小宽高 // 此处第2个不填表示最大宽高是无限大 ], // 分辨率大于200*200的图片]- width和height只能是数字。
- 最大宽高可以省略，表示无限大。
字段名称
类型
是否必选
含义
path
字符串数组
可选
同files/path。
size
二维数组
可选
同files/size。
resolution
二维数组
可选
同files/resolution。
compression字段示例：
\"buildOption\": { \"resOptions\": { \"compression\": { \"media\": { \"enable\": true // 是否对media图片启用纹理压缩 }, // 纹理压缩文件过滤，非必填，不填会压缩资源目录中的所有图片 \"filters\": [ { \"method\": { \"type\": \"sut\", // 转换类型 \"blocks\": \"4x4\" // 转换类型的扩展参数 }, // 指定用来参与压缩的文件，需要满足所有条件且不被exclude过滤的文件才会参与压缩 \"files\": { \"path\": [\"./**/*\"], // 指定资源目录中的所有文件 \"size\": [[0, \'10k\']], // 指定大小10k以下的文件 // 指定分辨率小于2048*2048的图片 \"resolution\": [ [ { \"width\": 0, \"height\": 0 }, // 最小宽高 { \"width\": 2048, \"height\": 2048 } // 最大宽高 ] ] }, // 从files中剔除掉不需要压缩的文件，需要满足所有过滤条件的文件才会被剔除 \"exclude\": { \"path\": [\"./**/*.jpg\"], // 过滤所有jpg文件 \"size\": [[0, \'1k\']], // 过滤大小1k以下的文件 // 过滤分辨率小于1024*1024的图片 \"resolution\": [ [ { \"width\": 0, \"height\": 0 }, // 最小宽高 { \"width\": 1024, \"height\": 1024 } // 最大宽高 ] ] } } ] } }}
