# 打包工具 打包工具用于在程序编译完成后，对编译出的文件等进行打包，以供安装发布。开发者可以使用DevEco Studio进行打包，也可使用打包工具的JAR包进行打包，JAR包通常存放在SDK路径下的toolchains目录中。 打包工具支持生成：Ability类型的模块包（HAP）、动态共享包（HSP）、应用程序包（App）、快速修复模块包（HQF）、快速修复包（APPQF）。 打包指令中的文件来源于[DevEco Studio编译构建产物](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-compile-build)，文件路径查看操作如下。 1. 在DevEco Studio工程根目录下的/hvigor/hvigor-config.json5文件中，修改"logging"下的"level"字段为"debug"。 2. 在DevEco Studio菜单栏，依次选择"构建 -> 清理项目"。 3. 在DevEco Studio菜单栏，依次选择"构建 -> 构建APP(s)"。 4. 在DevEco Studio底部"构建"窗口，搜索"app_packing_tool.jar"，确认打包参数中文件的路径。 打包工具会对module.json文件属性进行合法性校验。module.json文件是编译构建产物，其属性值在编译构建时自动生成，与配置文件中配置项对应关系如下。 **表1** module.json与配置文件属性的对照表 |module.json属性|含义|[module.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file#配置文件标签)配置项|[app.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file#配置文件标签)配置项|[工程级build-profile.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-profile-app)配置项| |:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| |bundleName|应用的Bundle名称。|-|bundleName|-| |bundleType|应用的Bundle类型。|-|bundleType|-| |versionCode|应用的版本号。|-|versionCode|-| |debug|应用是否可调试。|-|debug|-| |module/name|当前Module的名称。|module/name|-|-| |minCompatibleVersionCode|应用能够兼容的最低历史版本号。|-|minCompatibleVersionCode|-| |minAPIVersion|应用运行所需的最小API版本。|-|minAPIVersion|compatibleSdkVersion| |targetAPIVersion|应用运行需要的API目标版本。|-|targetAPIVersion|targetSdkVersion/compileSdkVersion 说明：targetSdkVersion存在时，targetAPIVersion由targetSdkVersion决定； 否则，targetAPIVersion由compileSdkVersion决定。| |querySchemes|允许应用进行跳转查询的URL schemes。|querySchemes|-|-| |generateBuildHash|标识当前HAP或HSP是否由打包工具生成哈希值。|generateBuildHash|generateBuildHash|-| |buildVersion|应用的构建版本号。|-|buildVersion|-| ## 约束与限制 * 打包工具需要运行在Java8及其以上环境。 * 打包指令中参数和参数值需成对出现。例如，HAP打包指令中--resources-path ，其中--resources-path为指令参数，path为参数值，两者需要同时出现。 * 不建议使用JDK 20版本运行打包工具。JDK 20对zip64扩展数据字段的校验规则存在已知缺陷，当zip包（如HAP、HSP或任何zip64文件）的目录中zip64扩展字段长度异常时，解析会抛出Invalid CEN header (invalid zip64 extra data field size)异常。建议使用JDK 17（LTS）或JDK 21（LTS）等长期支持版本。若必须使用JDK 20，可在JVM启动参数中添加-Djdk.util.zip.disableZip64ExtraFieldValidation=true规避此问题。 ## HAP打包指令 开发者可以使用打包工具的JAR包对模块进行打包，通过传入打包选项、文件路径，生成所需的HAP包。 **HAP打包时合法性校验** * 从API version 21开始，在打包entry类型的HAP时，如果module.json文件中querySchemes配置了超过50个URL scheme，则要求minAPIVersion大于等于21。 **打包HAP时的压缩规则：** * 应用配置compressNativeLibs为true时，会按照--compress-level设置的压缩等级对--lib-path指定目录下的文件进行压缩。 * 出于运行时性能等考量，--lib-path指定目录外的文件不会进行压缩。 示例： * Stage模型示例： ```bash java -jar app_packing_tool.jar --mode hap --json-path [--resources-path ] [--ets-path ] [--index-path ] [--pack-info-path ] [--lib-path ] --out-path [--force true] [--compress-level 5] [--pkg-context-path ] [--hnp-path ] [--pkg-sdk-info-path ] [--skills-path ] ``` * FA模型示例： ```bash java -jar app_packing_tool.jar --mode hap --json-path [--maple-so-path ] [--profile-path ] [--maple-so-dir ] [--dex-path ] [--lib-path ] [--resources-path ] [--index-path ] --out-path [--force true] [--compress-level 5] ``` **表2** HAP打包指令参数说明 |指令|是否必选项|选项|描述|备注| |:------------------|:----|:------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------| |--mode|是|hap|打包类型。|NA| |--json-path|是|NA|.json文件路径。FA模型文件名必须为config.json；Stage模型文件名必须为module.json。|NA| |--profile-path|否|NA|CAPABILITY.profile文件路径。|NA| |--maple-so-path|否|NA|maple so文件输入路径，so文件路径，文件名必须以.so为后缀。如果是多个so需要用"，"分隔。|NA| |--maple-so-dir|否|NA|maple so目录输入路径。|NA| |--dex-path|否|NA|dex文件路径，文件名必须以.dex为后缀。如果是多个dex需要用"，"分隔。 dex文件路径也可以为目录。|NA| |--lib-path|否|NA|lib库文件路径。从API version 22开始，--exist-src-path配置有效且--lib-path-retain配置为true时，对libs目录做增量打包，直接拷贝--exist-src-path配置的源HAP包中的libs目录，不再打包--lib-path配置的libs目录，--lib-path参数无效。|NA| |--resources-path|否|NA|resources资源包路径。|NA| |--index-path|否|NA|.index文件路径，文件名必须为resources.index。|NA| |--pack-info-path|否|NA|pack.info文件路径，文件名必须为pack.info。|NA| |--rpcid-path|否|NA|rpcid.sc文件路径，文件名必须为rpcid.sc。|NA| |--js-path|否|NA|存放js文件目录路径。|仅Stage模型生效。| |--ets-path|否|NA|存放ets文件目录路径。|仅Stage模型生效。| |--out-path|是|NA|目标文件路径，文件名必须以.hap为后缀。|NA| |--force|否|boolean|当目标文件路径已存在时，控制是否强制执行覆盖。当--out-path目标文件打包前已存在，该参数为true时，覆盖写入；为false时，终止打包过程并报错。当--out-path目标文件打包前不存在，正常打包，该参数无效。默认值为false。|NA| |--an-path|否|NA|存放[an文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs-V5/faqs-arkts-52-V5)的路径。|仅Stage模型生效。| |--ap-path|否|NA|存放[ap文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs-V5/faqs-arkts-52-V5)的路径。|仅Stage模型生效。| |--dir-list|否|NA|可指定目标文件夹列表，将其打入HAP包内。|NA| |--compress-level|否|number|lib库下文件压缩等级，默认值1。可选等级1-9。在应用配置compressNativeLibs参数为true的情况下生效，数值越大压缩率越高、压缩速度越慢。|NA| |--pkg-context-path|否|NA|可指定语境信息表文件路径，文件名必须为pkgContextInfo.json。当app.json5配置文件中bundleType取值不是appPlugin，且module.json5配置文件中requestPermissions取值包含"ohos.permission.kernel.SUPPORT_PLUGIN"时，该参数必填。|仅Stage模型生效。| |--hnp-path|否|NA|指定native软件包文件路径，将native软件包打入HAP包内。|NA| |--exist-src-path|否|NA|指定增量打包时的源HAP包路径，该路径必须指向一个已存在的、有效的.hap文件。当--lib-path-retain配置为true时，打包工具会直接拷贝源HAP包中的libs目录，不再打包--lib-path指定的libs目录，该特性称为增量打包。当--lib-path-retain配置为false时，正常打包--lib-path指定的libs目录，该参数无效。当libs目录中so文件压缩耗时比较久时，使用增量打包可以提升打包速度。 从API version 22开始支持该参数。|仅Stage模型生效。| |--lib-path-retain|否|boolean|是否对libs目录做增量打包。为true时表示对libs目录做增量打包，直接拷贝--exist-src-path指向的源HAP中的libs目录，不再打包--lib-path指定的libs目录；为false时表示不做增量打包，打包--lib-path指向的目录。默认值为false。此参数必须与--exist-src-path配套使用，单独设置不生效。 从API version 22开始支持该参数。|仅Stage模型生效。| |--pkg-sdk-info-path|否|NA|pkgSdkInfo.json（构建产物中依赖的HAR的基本信息，包括模块名和版本）文件路径，文件名必须为pkgSdkInfo.json。 从API version 23开始支持该参数。|仅Stage模型生效。| |--skills-path|否|NA|存放skill目录的路径。打包时，根据module.json5文件中的skillProfiles配置项，将--skills-path目录下对应的skill内容打入HAP包内。 当bundleType为app或atomicService时，允许传入该参数。当bundleType为shared、appService或appPlugin时，不允许传入该参数，否则打包失败。 从API版本26.0.0开始支持该参数。|仅Stage模型生效。| ## HSP打包指令 HSP包实现了多个HAP对文件的共享，开发者可以使用打包工具的jar包对应用进行打包，通过传入打包选项、文件路径，生成所需的HSP包。 **打包HSP时的压缩规则：** * 应用配置compressNativeLibs为true时，会按照--compress-level设置的压缩等级对--lib-path指定目录下的文件进行压缩。 * 出于运行时性能等考量，--lib-path指定目录外的文件不会进行压缩。 示例： ```bash java -jar app_packing_tool.jar --mode hsp --json-path [--resources-path ] [--ets-path ] [--index-path ] [--pack-info-path ] [--lib-path ] --out-path [--force true] [--compress-level 5] [--pkg-context-path ] [--pkg-sdk-info-path ] [--skills-path ] ``` **表3** HSP打包指令参数说明 |指令|是否必选项|选项|描述| |:------------------|:----|:------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |--mode|是|hsp|打包类型。| |--json-path|是|NA|.json文件路径，文件名必须为module.json。| |--profile-path|否|NA|CAPABILITY.profile文件路径。| |--dex-path|否|NA|1. dex文件路径，文件名必须以.dex为后缀。如果是多个dex需要用"，"分隔。 2. dex文件路径也可以为目录。| |--lib-path|否|NA|lib库文件路径。从API version 22开始，--exist-src-path配置有效且--lib-path-retain配置为true时，对libs目录做增量打包，直接拷贝--exist-src-path配置的源HSP包中的libs目录，不再打包--lib-path配置的libs目录，--lib-path参数无效。| |--resources-path|否|NA|resources资源包路径。| |--index-path|否|NA|.index文件路径，文件名必须为resources.index。| |--pack-info-path|否|NA|pack.info文件路径，文件名必须为pack.info。| |--js-path|否|NA|存放js文件目录路径。| |--ets-path|否|NA|存放ets文件目录路径。| |--out-path|是|NA|目标文件路径，文件名必须以.hsp为后缀。| |--force|否|boolean|当目标文件路径已存在时，控制是否强制执行覆盖。当--out-path目标文件打包前已存在，该参数为true时，覆盖写入；为false时，终止打包过程并报错。当--out-path目标文件打包前不存在，正常打包，该参数无效。默认值为false。| |--compress-level|否|number|lib库下文件压缩等级，默认值1，可选等级1-9。在应用配置compressNativeLibs参数为true的情况下生效，数值越大压缩率越高、压缩速度越慢。| |--pkg-context-path|否|NA|可指定语境信息表文件路径，文件名必须为pkgContextInfo.json。当app.json5配置文件中bundleType取值不是appPlugin，且module.json5配置文件中requestPermissions取值包含"ohos.permission.kernel.SUPPORT_PLUGIN"时，该参数必填。| |--exist-src-path|否|NA|指定增量打包时的源HSP包路径，该路径必须指向一个已存在的、有效的.hsp文件。当--lib-path-retain配置为true时，打包工具会直接拷贝源HSP包中的libs目录，不再打包--lib-path指定的libs目录，该特性称为增量打包。当--lib-path-retain配置为false时，正常打包--lib-path指定的libs目录，该参数无效。当libs目录中so文件压缩耗时比较久时，使用增量打包可以提升打包速度。 从API version 22开始支持该参数。| |--lib-path-retain|否|boolean|是否对libs目录做增量打包。为true时表示对libs目录做增量打包，直接拷贝--exist-src-path指向的源HSP中的libs目录，不再打包--lib-path指定的libs目录；为false时表示不做增量打包，打包--lib-path指向的目录。默认值为false。此参数必须与--exist-src-path配套使用，单独设置不生效。 从API version 22开始支持该参数。| |--pkg-sdk-info-path|否|NA|pkgSdkInfo.json（构建产物中依赖的HAR的基本信息，包括模块名和版本）文件路径，文件名必须为pkgSdkInfo.json。 从API version 23开始支持该参数。| |--skills-path|否|NA|存放skill目录的路径。打包时，根据module.json5文件中的skillProfiles配置项，将--skills-path目录下对应的skill内容打入HSP包内。 当bundleType为app、atomicService或skill时，允许传入该参数。当bundleType为shared、appService或appPlugin时，不允许传入该参数，否则打包失败。 从API版本26.0.0开始支持该参数。| ## App打包指令 开发者可以使用打包工具的jar包对应用进行打包，通过传入打包选项、文件路径，生成所需的App包。App包用于上架应用市场。 **表4** App打包合法性校验规则 |HAP或HSP的module.json中的被校验字段|校验规则| |:-------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |module下的name字段|要求所有HAP或HSP的name字段值均不相同。| |bundleName|要求所有HAP或HSP的bundleName字段值均保持一致。| |bundleType|要求所有HAP或HSP的bundleType字段值均保持一致。| |versionCode|要求所有HAP或HSP的versionCode字段值均保持一致。| |debug|从API version 20开始，要求所有HAP的debug字段值均保持一致，如果HAP的debug字段值为false，HSP的debug字段值也必须为false。如果HAP的debug字段值为true，对HSP的debug字段值无要求。 对于API version 19及之前版本，要求所有HAP或HSP的debug字段值均保持一致。| |minAPIVersion|从API version 20开始，要求所有HAP的minAPIVersion字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 19及之前版本，要求所有HAP或HSP的minAPIVersion字段值均保持一致。| |minCompatibleVersionCode|从API version 16开始，要求所有HAP的minCompatibleVersionCode字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 15及之前版本，要求所有HAP或HSP的minCompatibleVersionCode字段值均保持一致。| |targetAPIVersion|从API version 16开始，要求所有HAP的targetAPIVersion字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 15及之前版本，要求所有HAP或HSP的targetAPIVersion字段值均保持一致。| |versionName|从API version 12开始，不再对versionName校验。| |buildVersion|从API version 23开始，要求所有HAP或HSP的buildVersion字段值均保持一致。| > 说明 > > * module.json文件为DevEco Studio编译构建产物，其中的字段与配置文件的对应关系，请参考[表1 module.json与配置文件属性的对照表](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/packing-tool)。 **打包APP时的压缩规则：** 打包APP时，对release模式的HAP、HSP包会进行压缩，对debug模式的HAP、HSP包不会压缩。 > 说明 > > 若HAP或HSP中已压缩的so文件，在打包APP时再次压缩，将不会有明显体积缩减。 示例： ```bash java -jar app_packing_tool.jar --mode app [--hap-path ] [--hsp-path ] --out-path [--signature-path ] [--certificate-path ] --pack-info-path [--pack-res-path ] [--force true] [--encrypt-path ] [--pac-json-path ] [--atomic-service-entry-size-limit ] [--atomic-service-non-entry-size-limit ] [--replace-pack-info false] ``` **表5** App打包指令参数说明 |指令|是否必选项|选项|描述| |:------------------------------------|:----|:------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |--mode|是|app|多个HAP需满足HAP的合法性校验。| |--hap-path|否|NA|HAP包文件路径，文件名必须以.hap为后缀。如果是多个HAP包需要用","分隔。 HAP包文件路径也可以是目录。| |--hsp-path|否|NA|HSP包文件路径，文件名必须以.hsp为后缀。如果是多个HSP包需要用","分隔。 HSP包文件路径也可以是目录。| |--pack-info-path|是|NA|文件名必须为pack.info。| |--out-path|是|NA|目标文件路径，文件名必须以.app为后缀。| |--signature-path|否|NA|签名路径。| |--certificate-path|否|NA|证书路径。| |--pack-res-path|否|NA|pack.res快照文件路径。| |--force|否|boolean|当目标文件路径已存在时，控制是否强制执行覆盖。当--out-path目标文件打包前已存在，该参数为true时，覆盖写入；为false时，终止打包过程并报错。当--out-path目标文件打包前不存在，正常打包，该参数无效。默认值为false。| |--encrypt-path|否|NA|文件名必须为encrypt.json 。| |--pac-json-path|否|NA|[pac.json](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/agc-pac)文件路径，文件名必须为pac.json。 从API version 20开始支持该参数。| |--atomic-service-entry-size-limit|否|NA|设置元服务entry包大小（包含其依赖包的大小）限制，仅Stage模型应用且bundleType为atomicService时生效。取值范围为[0,4194304]的整数，取值为0表示不限制大小，单位KB。不设置该参数时默认值为2048KB。如果entry包是release模式（module.json5文件中type字段值为entry，且app.json5中debug字段的值为false），该限制作用于打包app时压缩后的entry包大小（包含其依赖包的大小）。| |--atomic-service-non-entry-size-limit|否|NA|设置元服务非entry包大小（包含其依赖包的大小）限制，仅Stage模型应用且bundleType为atomicService时生效。取值范围为[0,4194304]的整数，取值为0表示不限制大小，单位KB。不设置该参数时默认值为2048KB。如果非entry包是release模式（module.json5文件中type字段值不是entry，且app.json5中debug字段的值为false），该限制作用于打包app时压缩后的非entry包大小（包含其依赖包的大小）。| |--replace-pack-info|否|boolean|打包APP时，是否使用由--pack-info-path参数指定的pack.info文件替换HAP、HSP包中的pack.info文件。如果为true表示替换，false表示不替换，默认值为true。 从API version 22开始支持该参数。| |--stat-duplicate|否|boolean|打包完成后，是否扫描重复so文件，该参数可用于识别重复so，以减小包大小。取值为true时，执行扫描，扫描完成会在--out-path参数指定的输出文件所在目录下生成scan_report目录，其中包含文件名为scan_result的[重复so文件扫描报告](#扫描重复so文件)，并在告警中打印scan_report目录路径。取值为false时，不执行扫描。默认值为false。 从API version 23开始支持该参数。| |--deduplicate-so|否|boolean|用于在打包时对so文件进行去重，从而有效减小App的包体积。 默认值：false 取值说明： true：执行so文件去重。去重完成后，将在--out-path指定的目录下生成去重报告[so_dedup_report.json](#so去重报告)，并在日志中打印去重结果。 false：不执行so文件去重。 去重策略： - 当App包中不同模块间存在相同的so文件，且这些so会解压到应用根目录时（即module.json5中compressNativeLibs和extractNativeLibs不同时为false，且libIsolation为false）。 - 打包工具会根据deviceTypes、deliveryWithInstall、distributionFilter、requiredDeviceFeatures等配置进行去重，确保去重后应用在各个可安装设备上的功能保持不变。 **说明**： - 若应用代码中有直接从原始安装包中读取so文件的操作，开启去重后应用行为将发生变化。此时请勿开启该功能，或修改代码逻辑改为读取解压后的so文件后再开启。 - 开发者若在打包时开启了so去重功能，建议仔细检查去重结果，并在上架前充分验证去重后App包的功能完整性。 从API版本26.0.0开始支持该参数。| ## 多工程打包指令 多工程打包适用于多个团队开发同一个应用，但不方便共享代码的情况。开发者通过传入已经打好的HAP、HSP和App包，将多个包打成一个最终的App包，并上架应用市场。 **表6** 多工程打包合法性校验规则 |HAP或HSP的module.json中的被校验字段|校验规则| |:-------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |module下的name字段|要求所有HAP或HSP的name字段值均不相同。| |bundleName|要求所有HAP或HSP的bundleName字段值均保持一致。| |bundleType|要求所有HAP或HSP的bundleType字段值均保持一致。| |versionCode|要求所有HAP或HSP的versionCode字段值均保持一致。| |debug|从API version 20开始，要求所有HAP的debug字段值均保持一致，如果HAP的debug字段值为false，HSP的debug字段值也必须为false。如果HAP的debug字段值为true，对HSP的debug字段值无要求。 对于API version 19及之前版本，要求所有HAP或HSP的debug字段值均保持一致。| |minAPIVersion|从API version 20开始，要求所有HAP的minAPIVersion字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 19及之前版本，要求所有HAP或HSP的minAPIVersion字段值均保持一致。| |minCompatibleVersionCode|从API version 16开始，要求所有HAP的minCompatibleVersionCode字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 15及之前版本，要求所有HAP或HSP的minCompatibleVersionCode字段值均保持一致。| |targetAPIVersion|从API version 16开始，要求所有HAP的targetAPIVersion字段值均保持一致，且均不低于所有HSP对应字段的最大值。 对于API version 15及之前版本，要求所有HAP或HSP的targetAPIVersion字段值均保持一致。| |versionName|从API version 12开始，不再对versionName校验。| |buildVersion|从API version 23开始，要求所有HAP或HSP的buildVersion字段值均保持一致。| > 说明 > > * module.json文件为DevEco Studio编译构建产物，其中的字段与配置文件的对应关系，请参考[表1 module.json与配置文件属性的对照表](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/packing-tool)。 示例： ```bash java -jar app_packing_tool.jar --mode multiApp [--hap-list ] [--hsp-list ] [--app-list ] --out-path