鸿蒙5.0开发进阶：配置文件（hvigor-config.json5文件）

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

hvigor-config.json5文件

配置文件结构

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

modelVersion
dependencies
execution
└── analyze
└── daemon
└── incremental
└── parallel
└── typeCheck
logging
└── level
debugging
└── stacktrace
nodeOptions
└── maxOldSpaceSize
└── exposeGC
javaOptions
└── Xmx
properties
└── hvigor.cacheDir
└── ohos.buildDir
└── enableSignTask
└── ohos.arkCompile.maxSize
└── 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.processLib.optimization

配置文件字段说明

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

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

字段名称	是否必选	类型	含义
modelVersion	必选	字符串	开发态版本号。
dependencies	必选	对象	当前工程执行构建任务时，依赖的构建插件及版本，为npm源组件。
execution	可选	对象	执行构建的相关配置参数，仅在命令行场景下生效。
logging	可选	对象	日志相关配置参数。
debugging	可选	对象	调测相关配置参数。
nodeOptions	可选	对象	Node相关配置参数。
javaOptions	可选	对象	java相关配置参数。
properties	可选	对象	额外配置参数。

execution

execution是执行构建的相关配置参数，仅在命令行构建场景下生效。如果通过DevEco Studio菜单栏构建，需要在File > Settings > Build, Execution, Deployment > Build Tools > Hvigor中设置。

表2 execution字段说明

字段名称	是否必选	类型	含义
analyze	可选	字符串/布尔值	构建分析模式。 normal（默认值）：普通模式，通过简单打点数据进行分析。原default模式已废弃。 advanced：进阶模式，通过更加详细的打点数据进行分析。如果需要更详细的任务耗时数据，请选择该模式。原verbose模式已废弃。 false：不启用构建分析。
daemon	可选	布尔值	是否启用守护进程编译。 true（缺省默认值）：启用。 false：不启用。
incremental	可选	布尔值	是否启用增量编译。 true（缺省默认值）：启用。 false：不启用。
parallel	可选	布尔值	是否启用并行编译。 true（缺省默认值）：启用。 false：不启用。
typeCheck	可选	布尔值	是否启用构建脚本hvigorfile.ts文件的类型检查，启用后构建效率可能会有所降低。 true：启用。 false（缺省默认值）：不启用。

execution字段示例：

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

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内存溢出时，可以调整该参数。
exposeGC	可选	布尔值	是否启用GC（Garbage Collection，内存回收），启用后会优化编译过程的峰值内存。 true（缺省默认值）：启用。 false：不启用。

nodeOptions字段示例：

{
  "nodeOptions": {
    "maxOldSpaceSize": 8192
    "exposeGC": true
  }
}

javaOptions

javaOptions是java相关配置参数。

表6 javaOptions字段说明

字段名称	是否必选	类型	含义
Xmx	可选	整型数值	设置JVM最大堆内存，单位为MB，默认为512MB。

javaOptions字段示例：

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

properties

properties是额外配置参数。

表7 properties字段说明

字段名称	是否必选	类型	含义
hvigor.cacheDir	可选	字符串	指定项目根目录下的.hvigor缓存文件夹的存放路径。 说明 同名的不同工程不可指定相同的存放位置。
ohos.buildDir	可选	字符串	指定项目的构建产物目录（build目录）存放位置。 说明 同名的不同工程不可指定相同的存放位置。
enableSignTask	可选	布尔值	是否启用HAP或HSP签名任务。 true（缺省默认值）：启用。 false：不启用。
ohos.arkCompile.maxSize	可选	整型数值	指定编译ArkTS线程的数量，默认为5。
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文件进行全量编译，涉及到以下场景： 构建HSP时，存在于src/main/ets下的ets和ts文件都会被编译到产物中。 release模式对HAR混淆或构建字节码HAR时，存在于src/main/ets下的ets和ts文件都会被编译到产物中。 构建HAP/HSP时，存在于动态依赖的HAR模块src/main/ets下的ets和ts文件都会被编译到产物中。
ohos.align.target	可选	字符串	指定本次构建任务所有涉及到的模块及其依赖的模块的target。
ohos.fallback.target	可选	字符串数组	指定本次构建任务所有涉及到的模块及其依赖模块的fallback target，fallback target是一个特定优先级的target，各target的优先级顺序：align target > 命令行指定target > 被依赖的父模块target > fallback target > default 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中间产物，不生成js中间产物可以降低编译过程的峰值内存，加快编译速度。 true：不生成。 false（缺省默认值）：生成。 说明 以下场景均不支持该字段，配置后也会生成js中间产物： FA模型。 覆盖率测试。 在release模式下，开启混淆构建包含js中间码的HAR。 LiteWearable设备对应的工程。
ohos.arkCompile.singleFileEmit	可选	布尔值	开启此能力后，ArkTS代码编译时将会在单文件解析完成后写入磁盘，可以降低编译过程的峰值内存。 true：开启。 false（缺省默认值）：不开启。 说明 仅在debug模式下生效。 当进行代码覆盖率编译时，此能力不使能。
ohos.sign.har	可选	布尔值	是否启用HAR签名任务。 true：启用。 false（缺省默认值）：不启用。
hvigor.keepDependency	可选	布尔值	是否保持hsp中的所有依赖。如果保持则不对依赖进行处理，如果不保持，则只会保留hsp模块中的hsp相关依赖。 true（缺省默认值）：保持。 false：不保持。
ohos.arkCompile.emptyBundleName	可选	布尔值	编译后的产物，bundleName字段是否为空值""。 true：空值。 false（缺省默认值）：应用的bundleName。 说明 仅支持在EntryAbility中使用loadContentByName加载首页，同时使用Navigation导航进行页面跳转时设置为true，否则会导致应用闪退。
ohos.processLib.optimization	可选	布尔值	是否启用ProcessLibs任务性能优化，启用后可以减少ProcessLibs任务中so增量判定的耗时。 true：启用。 false（缺省默认值）：不启用。

properties字段示例：

{
  "properties": {
    "hvigor.cacheDir": "D://tmp",
    "ohos.buildDir": "D://tmp",
    "enableSignTask": true,
    "ohos.arkCompile.maxSize": 6,
    "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.sign.har": true,
    "hvigor.keepDependency": false,
    "ohos.arkCompile.emptyBundleName": true,
  }
}