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
parameterFile

配置文件字段说明

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

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

字段名称	可选/必选	类型	含义
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更高。

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",
  }
}

parameterFile

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

配置说明

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

parameterFile文件配置相对路径，并以工程下hvigor-config.json5文件为起点，如："parameterFile": "./parameterFile.json5"。
parameterFile文件内容采用json5格式，支持多层json对象嵌套。
parameterFile文件中的参数化key支持自定义，参数化value类型及配置要求和对应要替换的字段保持一致，具体可查看build-profile.json5文件中对应的字段。
build-profile.json5中支持参数化的字段有：source.sourceRoots，resource.directories，buildProfileFields，其他字段均不支持。
在build-profile.json5中以“@param:key”的形式引用parameterFile文件中对应的自定义字段，示例如下。
不支持在hvigorfile.ts脚本中使用参数化配置。

示例

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"]
    }
  }
]

配置文件结构​

配置文件字段说明​

execution​

logging​

debugging​

nodeOptions​

javaOptions​

properties​

parameterFile​

配置说明​

示例​