往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)
工程级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
└── multiProjects
modules
└── name
└── srcPath
└── targets
└── name
└── applyToProducts
配置文件字段说明
工程级build-profile.json5文件包含以下字段。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象 | 必选 | 编译配置信息。 | |
对象数组 | 必选 | 工程中包含的所有模块的信息,数组长度至少为1。 |
app
app是工程级的编译配置,包含签名、product等信息。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象数组 | 可选 | 签名方案信息,可配置多个。 | |
对象数组 | 可选 | 产品品类,可配置多个。如需配置多个,相关说明请参见配置多目标产物章节。 | |
对象数组 | 可选 | 构建模式集合,可配置多个。 | |
multiProjects | 布尔值 | 可选 | 当前工程是否支持多工程构建:
|
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
name | 字符串 | 必选 | 构建模式名称。默认生成debug,release和test三个名称,支持开发者自定义,其中test模式仅在执行ohosTest测试套件时使用。 |
对象 | 可选 | 构建模式使用的具体配置信息。 |
modules
modules是一个对象数组,用于描述工程中包含的所有模块,数组长度至少为1。模块配置包括名称、路径和target-product关联配置。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
name | 字符串 | 必选 | 模块的名称。该名称需与module.json5文件中的module.name保持一致。 在FA模型中,对应的文件为config.json。 |
srcPath | 字符串 | 必选 | 模块的源码路径,为模块根目录相对工程根目录的相对路径,允许模块根目录不在当前工程下。
|
对象数组 | 可选 | 模块的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 | 字符串 | 必选 | 签名方案的名称,不允许为空字符串。 |
对象 | 必选 | 签名方案相关材料,如密码、证书等。 通过File > Project Structure... > Project > Signing Configs界面,进行自动签名后,material节点中的各配置项会自动填充。 | |
type | 字符串 | 可选 | 签名类型:
|
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
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 | 字符串 | 可选 | 产品的包名。 |
对象 | 可选 | 产品的编译构建配置。 | |
runtimeOS | 字符串 | 可选 | 产品的运行环境:
|
arkTSVersion | 字符串 | 可选 | ArkTS语法检查工具的版本号:1.0,1.1。 默认为当前ArkTS语法检查工具支持的最新版本。 仅API 11及以上版本工程支持。 |
compileSdkVersion | 字符串/整型数值 | 可选 | 标识编译应用/元服务所使用的SDK版本。
说明 从DevEco Studio NEXT Developer Beta1(5.0.3.403)版本开始,该字段不需要显性配置,编译时默认使用配套的SDK版本。如果配置,只能配置为当前DevEco Studio配套的SDK版本,不允许配置为其他SDK版本。 |
compatibleSdkVersion | 字符串/整型数值 | 必选 | 标识应用/元服务运行所需兼容的最低SDK版本,应用/元服务不能安装在低于该版本的设备。 |
targetSdkVersion | 字符串/整型数值 | 可选 | 标识应用/元服务运行所需目标SDK版本,是系统提供的前向兼容手段。如果新SDK版本中API行为发生变更,将应用/元服务安装到新系统后,可通过该字段提供向前兼容手段,在新系统版本保持老的API行为。如未配置,默认与compileSdkVersion保持一致。 |
bundleType | 字符串 | 可选 | 包的类型:
|
label | 字符串 | 可选 | 应用/元服务名称。 说明 配置products中的label、icon、versionCode、versionName、resource字段后,编译构建时将根据此处的配置替换app.json5中的相关配置,常用于应用和元服务可分可合构建打包场景。 |
icon | 字符串 | 可选 | 应用/元服务图标。 |
versionCode | 整型数值 | 可选 | 版本号。 |
versionName | 字符串 | 可选 | 版本名称。 |
对象 | 可选 | 名称和图标对应的资源所在目录。 | |
对象 | 可选 | 定制产品生成的应用包的配置。 | |
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进行合并。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象 | 可选 | 打包相关配置项。 | |
debuggable | 布尔值 | 可选 | 当前编译产物是否为可调试模式:
当使用release的编译模式时,默认为false。 |
对象 | 可选 | 资源编译配置项。 | |
对象 | 可选 | Native编译配置项。 | |
对象 | 可选 | 源码相关配置。使用不同的标签对源代码进行分类,以便在构建过程中对不同的源代码进行不同的处理。 | |
对象 | 可选 | Native 库(.so)相关配置。 | |
对象 | 可选 | NAPI库(.so)文件的筛选选项。标记为废弃,不建议使用,推荐使用nativeLib/filter。 | |
对象 | 可选 | ArkTS 编译配置。 | |
对象 | 可选 | 严格模式。 | |
nativeCompiler | 字符串 | 可选 | 指定Native编译时使用的编译器,包括:
说明
|
对象数组 | 可选 | 编译HAP/HSP模块时,指定需要删除的依赖包中的冗余权限,模块本身的权限不会被删除。 |
packOptions
packOptions是打包相关配置项。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
buildAppSkipSignHap | 布尔值 | 可选 | 是否跳过生成签名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文件:
|
arkOptions
arkOptions是ArkTS编译配置。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象 | 可选 | 用于ArkTS的构建配置。自定义类型,key可由数字、英文、下划线、中划线组成,value类型仅支持string、number、boolean。 | |
字符串数组 | 可选 | 自定义类型,可配置包名或d.ts/d.ets文件路径。 | |
对象 | 可选 | 与编译TS语法相关的配置选项。 | |
autoLazyImport | 布尔值 | 可选 | 编译时是否自动将符合lazy-import语法规范的import语句添加"lazy"关键字。仅支持在源码中添加"lazy"关键字,不包含依赖的字节码HAR包或HSP。
|
branchElimination | 布尔值 | 可选 | 是否启用代码分支裁剪,减少编译产物大小,开启后,在release编译模式下,不会被执行到的代码分支会被裁剪掉,示例如下:
|
apPath | 字符串 | 可选 | 说明 API 11及以上版本不再支持,即该字段配置后不再生效。 应用热点信息文件路径。 |
hostPGO | 布尔值 | 可选 | 是否启用配置文件引导优化功能:
从API 10开始废弃,由于partial模式可能存在兼容性问题,请使用Target AOT能力,不建议使用Host AOT。 |
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
targetESVersion | 字符串 | 可选 | 指定TS语法编译产物的目标运行时EcmaScript版本,包括:
|
arkOptions字段示例:
"buildOption": {
"arkOptions": {
"buildProfileFields": {
"targetData": "TargetData",
"data": "DataTargetDefault"
},
"tscConfig": {
"targetESVersion": "ES2021",
},
"autoLazyImport": true,
"branchElimination": true
}
}
strictMode
strictMode用于定义严格模式。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
noExternalImportByPath | 布尔值 | 可选 | 是否严格检查绝对路径导入方式和相对路径跨模块导入方式。
|
useNormalizedOHMUrl | 布尔值 | 可选 | 是否使用标准化的OHMUrl(OHMUrl的定义参考以下说明)格式,标准化的OHMUrl统一了原有OHMUrl的格式。使用集成态HSP和字节码HAR需使用标准化的OHMUrl格式。
|
caseSensitiveCheck | 布尔值 | 可选 | 导入文件是否严格校验大小写,支持相对路径和软链接。
|
duplicateDependencyCheck | 布尔值 | 可选 | 是否校验本地HSP模块有无依赖相同的HAR。仅在Build App(s)起效。
|
harLocalDependencyCheck | 布尔值 | 可选 | 是否对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是资源编译配置项。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象 | 可选 | 对工程预置图片资源进行纹理压缩的编译配置参数。 | |
对象 | 可选 | 对模块的src/main/ets目录下的资源文件(非源码文件)拷贝的编译配置参数。 说明 该字段对不开启混淆的源码HAR不生效。 |
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
enable | 布尔值 | 可选 | 是否将ets目录下的资源文件打包到产物中。
|
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目录的图片进行纹理压缩的配置参数。 | |
对象数组 | 可选 | 文件过滤配置参数。 说明 编译过程中会依次遍历图片文件,并与filters条件进行匹配,一旦匹配成功,则完成该图片的处理。当工程级和模块级同时配置时,先按照模块级的过滤条件匹配,一旦匹配成功,则忽略工程级的过滤条件;如果模块级的没有匹配成功,继续按工程级的条件进行匹配。 |
media
media是对资源目录下media目录的图片进行纹理压缩的配置参数。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
enable | 布尔值 | 可选 | 是否对media图片启用纹理压缩。
|
filters
filters是文件过滤配置参数。
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
对象 | 必选 | 纹理压缩的方式。 | |
对象 | 可选 | 指定用来参与压缩的文件,与exclude字段配合使用。 | |
对象 | 可选 | 从files中剔除掉不需要压缩的文件。 |
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
type | 字符串 | 必选 | 转换类型。
|
blocks | 字符串 | 必选 | astc/sut转换类型的扩展参数,决定画质和压缩率,当前仅支持"4x4"。 |
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
path | 字符串数组 | 可选 | 指定“按路径匹配”的过滤条件,符合glob规范,格式为相对路径,配置示例: |
size | 二维数组 | 可选 | 指定“按大小匹配”的过滤条件,格式为[min,max],闭区间,表示大小从min到max之间的文件,配置示例:
|
resolution | 二维数组 | 可选 | 指定“按分辨率匹配”的过滤条件,配置示例:
|
字段名称 | 类型 | 是否必选 | 含义 |
---|---|---|---|
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 } // 最大宽高
]
]
}
}
]
}
}
}