目录

hvigor-config.json5文件

配置文件结构

hvigor-config.json5文件整体的结构如下。

modelVersion
dependencies
execution
└── analyze
└── daemon
└── incremental
└── parallel
└── typeCheck
└── optimizationStrategy
logging
└── level
debugging
└── stacktrace
nodeOptions
└── maxOldSpaceSize
└── maxSemiSpaceSize
└── exposeGC
javaOptions
└── Xmx
properties
└── hvigor.cacheDir
└── ohos.buildDir
└── enableSignTask
└── ohos.arkCompile.maxSize
└── hvigor.pool.cache.capacity
└── hvigor.pool.maxSize
└── ohos.pack.compressLevel
└── hvigor.analyzeHtml
└── hvigor.dependency.useNpm
└── ohos.compile.lib.entryfile
└── ohos.align.target
└── ohos.fallback.target
└── ohos.arkCompile.sourceMapDir
└── ohos.collect.debugSymbol
└── hvigor.enableMemoryCache
└── hvigor.memoryThreshold
└── ohos.nativeResolver
└── ohos.arkCompile.noEmitJs
└── ohos.arkCompile.singleFileEmit
└── ohos.sign.har
└── hvigor.keepDependency
└── ohos.arkCompile.emptyBundleName
└── ohos.uiTransform.Optimization
└── ohos.har.excludeHspDependencies
└── ohos.processLib.optimization
└── ohos.obfuscationRules.optimization
└── hvigor.incremental.optimization
└── hvigor.task.schedule.optimization
└── ohos.byteCodeHar.integratedOptimization
└── ohos.rollupCache.usePathPlaceholder
└── ohos.rollupCache.useSourceHash
└── ohos.arkCompile.writeRollupCache
└── ohos.align.deviceTypes
└── ohos.dependencies.types.enable
└── ohos.defaults.release.cmakebuildtype
└── ohos.defaults.autoLazyImport
└── hvigor.daemon.idleTimeout
└── ohos.rollup.transform.useUnifiedAst
parameterFile

配置文件字段说明

hvigor-config.json5配置文件包含以下字段。

表1 hvigor-config.json5文件字段说明

字段名称

可选/必选

类型

含义

modelVersion

必选

字符串

开发态版本号。

默认版本号为DevEco Studio配套的modelVersion,以DevEco Studio 6.1.1 Release为例,配套的modelVersion为"6.1.1"。如需修改modelVersion,修改后的值不能小于5.0.0,且不能大于DevEco Studio配套的modelVersion。

dependencies

必选

对象

当前工程执行构建任务时,依赖的构建插件及版本,为npm源组件。

说明:

修改dependencies后,请根据界面提示,点击编辑器右上角Sync Now安装依赖。

execution

可选

对象

执行构建的相关配置参数。

logging

可选

对象

日志相关配置参数。

debugging

可选

对象

调测相关配置参数。

nodeOptions

可选

对象

Node相关配置参数。

javaOptions

可选

对象

java相关配置参数。

properties

可选

对象

额外配置参数。

parameterFile

可选

字符串

自定义的参数化配置文件路径。

从DevEco Studio 6.0.2 Beta1版本开始支持。

execution

execution是执行构建的相关配置参数,除了optimizationStrategy字段外,其他字段仅在命令行构建场景下生效,如果通过DevEco Studio菜单栏构建,需要在File > Settings(macOS为DevEco Studio > Preferences/Settings) > Build, Execution, Deployment > Build Tools > Hvigor中设置。

表2 execution字段说明

字段名称

可选/必选

类型

含义

analyze

可选

字符串/布尔值

构建分析模式。

  • normal(默认值):普通模式,通过简单打点数据进行分析。原default模式已废弃。
  • advanced:进阶模式,通过更加详细的打点数据进行分析。如果需要更详细的任务耗时数据,请选择该模式。原verbose模式已废弃。
  • ultrafine:超精细化模式,与advanced模式相比,在ArkTS编译阶段记录更详细的打点数据,但开启后可能导致编译构建时间更长。从DevEco Studio 6.0.0 Beta1版本开始支持。
  • false:不启用构建分析。

daemon

可选

布尔值

是否启用守护进程编译。

  • true(缺省默认值):启用。
  • false:不启用。

incremental

可选

布尔值

是否启用增量编译。

  • true(缺省默认值):启用。
  • false:不启用。

parallel

可选

布尔值

是否启用并行编译。

  • true(缺省默认值):启用。
  • false:不启用。

typeCheck

可选

布尔值

是否启用构建脚本hvigorfile.ts文件的类型检查,启用后构建效率可能会有所降低。

  • true:启用。
  • false(缺省默认值):不启用。

optimizationStrategy

可选

字符串

指定构建模式。从DevEco Studio 5.1.1 Release版本开始支持。

  • performance:性能优先模式,可加快构建速度,但会占用更多内存。
  • memory(缺省默认值):内存优先模式,可以减少编译内存占用。
说明:

更改模式后,首次编译会执行全量编译。

execution字段示例:

{
  "execution": {
    "analyze": "normal",
    "daemon": true,
    "incremental": true,
    "parallel": true,
    "typeCheck": false,
    "optimizationStrategy": "performance",
  }
}

logging

logging是日志相关配置参数。

表3 logging字段说明

字段名称

可选/必选

类型

含义

level

可选

字符串

构建时打印日志的级别。

  • debug:调测日志。
  • info(缺省默认值):基本信息日志。
  • warn:告警日志。
  • error:错误日志。

logging字段示例:

{
  "logging": {
    "level": "debug"
  }
}

debugging

debugging是调测相关配置参数。

表4 debugging字段说明

字段名称

可选/必选

类型

含义

stacktrace

可选

布尔值

是否启用堆栈跟踪。

  • true:启用。
  • false(缺省默认值):不启用。

debugging字段示例:

{
  "debugging": {
    "stacktrace": true
  }
}

nodeOptions

nodeOptions是Node相关配置参数。

表5 nodeOptions字段说明

字段名称

可选/必选

类型

含义

maxOldSpaceSize

可选

整型数值

启用守护进程编译时,为守护进程设置最大的老生代内存大小,单位为MB,默认为8192MB。当工程代码量较大出现JS内存溢出时,可以调整该参数。

maxSemiSpaceSize

可选

整型数值

启用守护进程编译时,为守护进程设置新生代内存最大的半空间大小,单位为MB,默认为16MB。增加半空间大小可能会提高Node.js的吞吐量,但会消耗更多内存。

从DevEco Studio 5.1.0 Release版本开始支持。

exposeGC

可选

布尔值

是否启用GC(Garbage Collection,内存回收),启用后会优化编译过程的峰值内存。

  • true(缺省默认值):启用。
  • false:不启用。

nodeOptions字段示例:

{
  "nodeOptions": {
    "maxOldSpaceSize": 8192,
    "maxSemiSpaceSize": 16,
    "exposeGC": true,
  }
}

javaOptions

javaOptions是java相关配置参数。

表6 javaOptions字段说明

字段名称

可选/必选

类型

含义

Xmx

可选

整型数值

设置JVM最大堆内存,单位为MB,默认为512MB。

javaOptions字段示例:

{
  "javaOptions": {
    "Xmx": 512
  }
}

properties

properties是额外配置参数。除了在hvigor-config.json5中配置properties外,还可以通过命令行参数-c或--config指定properties,命令行优先级比hvigor-config.json5更高,命令行配置方式请参考命令行构建工具(hvigorw)。

表7 properties字段说明

字段名称

可选/必选

类型

含义

hvigor.cacheDir

可选

字符串

指定项目根目录下的.hvigor缓存文件夹的存放路径。

说明:

同名的不同工程不可指定相同的存放位置。

ohos.buildDir

可选

字符串

指定项目的构建产物目录(build目录)存放位置。

说明:

同名的不同工程不可指定相同的存放位置。

enableSignTask

可选

布尔值

是否启用HAP或HSP签名任务。

  • true(缺省默认值):启用。
  • false:不启用。

ohos.arkCompile.maxSize

可选

整型数值

指定编译ArkTS线程的数量,默认为5。

hvigor.pool.cache.capacity

可选

整型数值

定义内存中缓存数据的容量,默认为4,数值越小,内存中缓存数据越少。配置为0,表示不启用内存缓存配置。

hvigor.pool.maxSize

可选

整型数值

指定编译过程中的线程数量,相比ohos.arkCompile.maxSize增加签名、打包等任务的线程。默认值为“工程的模块数”和“电脑虚拟核数-1”两者的较小值。

ohos.pack.compressLevel

可选

字符串

设置打包hap(压缩so)或app(压缩hap)时的压缩率等级。压缩率越高,压缩速度越慢。

  • fast(缺省默认值):最低等级的压缩率,压缩速度最快。
  • standard:适中等级的压缩率,压缩速度适中。
  • ultimate:最高等级的压缩率,压缩速度最慢。

hvigor.analyzeHtml

可选

布尔值

是否生成构建可视化html文件。

  • true:生成构建可视化html文件。生成的html文件存放在工程的.hvigor/report目录下,该文件可直接在浏览器中打开。
  • false(缺省默认值):不生成构建可视化html文件。

hvigor.dependency.useNpm

可选

布尔值

指定是否使用npm下载hvigor依赖。

若未配置该字段,当Node.js版本 ≥ 16时,默认使用pnpm下载依赖。在某些特定场景,可以通过配置该字段指定使用npm下载依赖。

  • true:对于任意Node版本,都使用npm下载依赖。
  • false(缺省默认值):Node.js版本 ≥ 16时,使用pnpm下载依赖;Node.js版本 < 16时,使用npm下载依赖。

ohos.compile.lib.entryfile

可选

布尔值

指定是否从入口文件开始编译:

  • true:表示从模块的入口文件开始编译,将编译入口文件及被引用的文件,没被引用的文件不会参与编译流程。
  • false(缺省默认值):表示将src/main/ets下的ets和ts文件进行全量编译,涉及到以下场景:
    1. 构建HSP时,存在于src/main/ets下的ets和ts文件都会被编译到产物中。
    2. release模式对HAR混淆或构建字节码HAR时,存在于src/main/ets下的ets和ts文件都会被编译到产物中。
    3. 构建HAP/HSP时,存在于动态依赖的HAR模块src/main/ets下的ets和ts文件都会被编译到产物中。

ohos.align.target

可选

字符串

指定本次构建任务所有涉及到的模块及其依赖的模块的target。详情请参考多产物构建target。

ohos.fallback.target

可选

字符串数组

指定本次构建任务所有涉及到的模块及其依赖模块的fallback target,fallback target是一个特定优先级的target,各target的优先级顺序:align target > 命令行指定target > 被依赖的父模块target > fallback target > default target。详情请参考多产物构建target。

ohos.arkCompile.sourceMapDir

可选

字符串

指定sourceMap文件的生成路径,方便开发者进行堆栈的回栈与错误信息的定位,当前仅支持Stage模型。若没有指定路径,默认生成在build/{productName}/outputs/{targetName}/mapping下。

说明:

从API 12开始支持。

ohos.collect.debugSymbol

可选

布尔值

是否将sourceMap、nameCache和带调试信息的so文件归档到产物路径下,根据选择的构建模式,如果是构建HAP/HSP/HAR,会归档到模块的build/{productName}/outputs/{targetName}/symbol的release或debug目录下;如果是构建APP,会将HAP/HSP模块的文件归档到工程的build/outputs/{productName}/symbol的release或debug目录下。

  • true:归档。
  • false:不归档。
说明:
  • 如果不配置,release模式时默认值为true,debug模式时默认值为false。
  • 仅支持Stage模型。
  • nameCache文件仅在release模式下且开启混淆后才会生成,release模式下不开启混淆以及debug模式下均不生成这个文件。

hvigor.enableMemoryCache

可选

布尔值

是否开启缓存,开启缓存会加快增量编译速度,关闭缓存能够节省内存占用,但是会增加增量编译时间。

  • true(缺省默认值):开启。
  • false:不开启。

hvigor.memoryThreshold

可选

整型数值

内存管理阈值,单位为MB,当编译构建占用内存超过此阈值时,新加入的编译任务会等待,直到正在进行的编译任务结束,新的编译任务才能开始,此配置将导致编译时间延长。

说明:
  • 配置该字段后,即使hvigor.enableMemoryCache配置为true,也不进行缓存。
  • 该字段配置为很小的值时,构建任务会串行执行,等效于配置ohos.arkCompile.maxSize:1;配置为很大的值时,与不配置没有差异。

ohos.nativeResolver

可选

布尔值

ArkTS编译过程中是否使用高性能插件进行依赖寻址,使用高性能插件可以降低编译过程的峰值内存,加快编译速度。

  • true(缺省默认值):使用。
  • false:不使用。

ohos.arkCompile.noEmitJs

可选

布尔值

ArkTS编译过程中是否生成js中间产物,具体方案及开启后的影响请参考优化编译中间产物生成。

  • true:不生成。
  • false(缺省默认值):生成。

ohos.arkCompile.singleFileEmit

可选

布尔值

是否开启单文件解析完成后写入磁盘的能力,具体方案及开启后的影响请参考文件写入磁盘。

  • true:开启。
  • false(缺省默认值):不开启。

ohos.sign.har

可选

布尔值

是否启用HAR签名任务。详情请参考构建签名HAR。

  • true:启用。
  • false(缺省默认值):不启用。

hvigor.keepDependency

可选

布尔值

是否保持hsp中的所有依赖。如果保持则不对依赖进行处理,如果不保持,则只会保留hsp模块中的hsp相关依赖。

  • true(缺省默认值):保持。
  • false:不保持。

ohos.arkCompile.emptyBundleName

可选

布尔值

ArkTS编译转换后的产物,bundleName字段是否为空值。

  • true:bundleName字段的值是空值。
  • false(缺省默认值):bundleName字段是应用实际的包名。
说明:
  • 仅支持在EntryAbility中使用loadContentByName加载首页,同时使用Navigation导航进行页面跳转时设置为true,否则会导致应用闪退。
  • 预览时暂不支持配置该字段,字段默认取值为false。

ohos.uiTransform.Optimization

可选

布尔值

是否对ArkTS编译转换后的产物中的bundleName字段开启优化。

  • true:开启,bundleName字段的值是变量。
  • false(缺省默认值):不开启,bundleName字段是应用实际的包名。

从DevEco Studio 5.0.5 Beta1版本开始支持。

说明:
  • 该字段对字节码HAR不生效,字节码HAR产物的bundleName字段的值默认是变量。
  • 预览时暂不支持配置该字段,字段默认取值为false。

ohos.har.excludeHspDependencies

可选

布尔值

构建har包时,产物module.json中是否排除依赖的hsp,排除后,module.json中不包含dependencies字段。

  • true:排除。
  • false(缺省默认值):不排除。

从DevEco Studio 5.1.0 Release版本开始支持。

ohos.processLib.optimization

可选

布尔值

是否启用ProcessLibs任务性能优化,启用后可以减少ProcessLibs任务中so增量判定的耗时。

  • true:启用。
  • false(缺省默认值):不启用。

ohos.obfuscationRules.optimization

可选

布尔值

release模式开启混淆时,是否优化三方依赖中混淆配置文件的收集方式,优化后可以减少收集耗时,加快编译速度。

  • true:优化。
  • false(缺省默认值):不优化。

从DevEco Studio 5.1.0 Release版本开始支持。

hvigor.incremental.optimization

可选

布尔值

是否开启任务增量判断优化,优化方案及开启后的影响请参考任务增量判断优化。

  • true:开启。
  • false(缺省默认值):不开启。

hvigor.task.schedule.optimization

可选

布尔值

是否开启任务调度优化,优化方案及开启后的影响请参考任务调度优化。

  • true:开启。
  • false(缺省默认值):不开启。

ohos.byteCodeHar.integratedOptimization

可选

布尔值

是否开启字节码HAR集成行为优化,开启后,字节码HAR使用的依赖支持配置在工程级oh-package.json5的dependencies或dynamicDependencies中,同时会优化部分依赖收集行为,具体请参考编译行为差异说明。

  • true:开启。
  • false(缺省默认值):不开启。

从DevEco Studio 5.1.1 Beta1版本开始支持。

ohos.rollupCache.usePathPlaceholder

可选

布尔值

是否将build目录下rollup缓存中的绝对路径替换为占位符。该功能是实验特性,开启后会造成读写缓存性能降低。

  • true:是,即缓存中是占位符。
  • false(缺省默认值):否,即缓存中是绝对路径。

从DevEco Studio 6.0.0 Beta1版本开始支持。

ohos.rollupCache.useSourceHash

可选

布尔值

是否将build目录下rollup缓存中的源码替换为对应的hash内容,减少缓存大小。该功能是实验特性,可以提升缓存对比和读写性能。

  • true:是,即缓存源码hash。
  • false(缺省默认值):否,即缓存源码内容。

从DevEco Studio 6.0.0 Beta1版本开始支持。

ohos.arkCompile.writeRollupCache

可选

布尔值

build目录下是否写入rollup缓存。

  • true(缺省默认值):写缓存。
  • false:不写缓存。

从DevEco Studio 6.0.0 Beta2版本开始支持。

ohos.align.deviceTypes

可选

字符串数组

指定归一的设备类型,构建APP时,当HAP/HSP的module.json5中的设备类型是ohos.align.deviceTypes的超集时,模块才会被打包到APP中,同时打包后产物中的设备类型会被设置为ohos.align.deviceTypes的值。

从DevEco Studio 6.0.0 Beta2版本开始支持。

说明:

仅支持Stage模型。

ohos.dependencies.types.enable

可选

布尔值

编译时是否收集依赖的HAR模块/源码HAR包的类型声明文件参与语法校验。如果HAR中配置了类型声明文件,建议开启。

  • true:收集。
  • false(缺省默认值):不收集。

从DevEco Studio 6.0.0 Beta3版本开始支持。

ohos.defaults.release.cmakebuildtype

可选

字符串

在release模式下构建时,指定cmake构建类型,对所有模块生效。

  • Debug:不优化代码,附加调试信息。
  • Release(缺省默认值):最大化优化代码,但不包含调试信息。
  • RelWithDebInfo:近似于Release模式,既进行了代码优化,同时保留部分调试信息。

从DevEco Studio 6.0.1 Beta1版本开始支持。

说明:
  • 模块级build-profile.json5文件中也可以通过arguments字段指定cmake构建类型,例如"arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo"。arguments字段的优先级比ohos.defaults.release.cmakebuildtype更高。
  • 在debug模式下构建时,该字段配置无效,默认使用Debug构建类型。

ohos.defaults.autoLazyImport

可选

布尔值

编译时是否自动将符合lazy-import语法规范的import语句添加"lazy"关键字。仅支持在源码中添加"lazy"关键字,不包含依赖的字节码HAR包或HSP。关于lazy-import的介绍及相关影响请参考延迟加载(lazy import)。

  • true:添加。
  • false(缺省默认值):不添加。

从DevEco Studio 6.0.2 Beta1版本开始支持。

说明:
  • 如果配置为true,编译时不会做场景识别,即源码中任何符合语法规范的import语句都会被添加"lazy"。
  • 仅支持Stage模型。
  • build-profile.json5文件中也可以通过autoLazyImport字段实现该能力,autoLazyImport的优先级比ohos.defaults.autoLazyImport更高。

hvigor.daemon.idleTimeout

可选

整型数值

设置daemon进程的最大空闲时长,单位为毫秒。默认值为10800000,即3小时。

从最后一次构建任务完成时开始计算,超过最大空闲时长则daemon进程退出。

从26.0.0版本开始支持。

ohos.rollup.transform.useUnifiedAst

可选

布尔值

是否开启ArkTS编译转换过程中的AST(抽象语法树)合一优化。

  • true:开启,编译过程中将多个AST合并为统一AST,可有效降低编译峰值内存、缩短全量编译时间。
  • false(缺省默认值):不开启,编译过程中各阶段独立维护各自的AST。

从26.0.0版本开始支持。

properties字段示例:

{
  "properties": {
    "hvigor.cacheDir": "D://tmp",
    "ohos.buildDir": "D://tmp",
    "enableSignTask": true,
    "ohos.arkCompile.maxSize": 6,
    "hvigor.pool.cache.capacity": 2,
    "hvigor.pool.maxSize": 8,
    "ohos.pack.compressLevel": "standard",
    "hvigor.analyzeHtml": true,
    "hvigor.dependency.useNpm": false,
    "ohos.compile.lib.entryfile": true,
    "ohos.align.target": "target1",
    "ohos.fallback.target": ["target1", "target2"],
    "ohos.arkCompile.sourceMapDir": "D://MyProject",
    "ohos.collect.debugSymbol": false,
    "hvigor.enableMemoryCache": true,
    "hvigor.memoryThreshold": 1000,
    "ohos.nativeResolver": true,
    "ohos.arkCompile.noEmitJs": true,
    "ohos.arkCompile.singleFileEmit": true,
    "ohos.sign.har": true,
    "hvigor.keepDependency": false,
    "ohos.arkCompile.emptyBundleName": true,
    "ohos.align.deviceTypes": ["phone", "tablet"],
    "ohos.defaults.release.cmakebuildtype": "RelWithDebInfo",
    "hvigor.daemon.idleTimeout": 10800000,
  }
}

parameterFile

从DevEco Studio 6.0.2 Beta1版本开始,编译构建新增参数化配置功能。开发者可添加一个参数化文件(json5格式文件),在该文件中维护构建配置文件build-profile.json5中部分字段的值,工程级或者各模块的build-profile.json5将根据该文件中的键值对进行配置,满足不同构建场景下,开发者快速切换构建配置的需要。

[h2]配置说明

在hvigor-config.json5文件中添加parameterFile配置,并指定parameterFile文件路径。配置规则如下:

[h2]示例

hvigor-config.json5的parameterFile字段示例:

{
  "nodeOptions": {
    // ...
  },
  "parameterFile": "./parameterFile.json5"
}

parameterFile所指向文件的配置示例:

{
  "source": {
    "customizedSourceRoot1": "./src/default1",
    "customizedSourceRoot2": "./src/default2"
  }
}

模块级build-profile.json5示例,以多个har模块为例:

// har1模块build-profile.json5
"targets": [
  {
    "name": "default",
    "source": {
      "sourceRoots": ["@param:source.customizedSourceRoot1"]   // 使用时必须以'@param:'开头,构建时sourceRoots会被替换为'./src/default1'
    }
  }
]
// har2模块build-profile.json5
"targets": [
  {
    "name": "default",
    "source": {
      "sourceRoots": ["@param:source.customizedSourceRoot2"]
    }
  }
]