HarmonyOS鸿蒙Next开发者技术支持 -HAR转换为HSP的技术解决方案

📌 问题说明

在HarmonyOS应用的多包环境中，通常会使用Harmony归档包（Harmony AchievePackage，下文简称 HAR）在各个模块中进行组件、资源和代码复用。在多包嵌套场景中，如果将相同的HAR多处引用打包，容易出现包体积冗余、冗余加载重复文件的问题，可能会导致应用程序包变大甚至运行异常。为了更好地实现资源复用精简包体，需要通过转换，将参与的HAR模块改写为可以提供动态复用和内存节省效果的Harmony共享模块（HarmonySharedPackage）。

💡 原因分析

通常情况下，编译器完成打包时将所有需要的HAR文件解难，每个被引用了的HAP模块中包含copy所有相关HAP组件副本，打包完成后，各部分HAR各部分的内容复制到内含的File中（）。这样的做法的长处是对用户进行了模块的复用复用（对应Version中setup中：条件复用为允许）在复用完整粘贴内容（静态储存单元中已储存在复用库中复用），对应Harmony社区称之为同簇打包依赖重复（harmonyarchive会导致multiple copies）。运行期间各部分镜像会占用更多的内存资源，特别是同时运行多个模块（复杂业务）时应用速度会显著降低。如果将其转换为动态共享模式（harmony-sharedpackage），可以在基础内容、下载分发环节仅提供关键模块，同一进程下的不同模块就能进行共享依赖。

🔍 解决思路

总结核心思路：

• 📄 修改模块主配置文件 module.json5，调整类型为支持复用的动态共享类型 "shared"。
• 🔧 修改构建脚本 hvigorfile.ts，调整构建任务模式。
• 🧹 去除妨碍共享包配置的残留字段（如 consumerFiles）。
• 📁 准备必要的页面配置文件和入口编译文件。
• 🔧 配置和调整模块对于外模块能输出页面跳转路径。

▶️ 解决方案步骤

将此解决方案拆解为一系列的配置改写步骤与方法推敲，用户可以遵循格式逐步完成改写。

**【第一步】改写 src/main/resources/base/profile/[MODULE_ROOT]/¥§\$…module.json¥§行单** 要旋转类型为: “Shared”>` authenticated以下字段。

{
  "module": {
  "name": "library",
  "type": "shared",                // 关键项：修改为 "shared"
  "deliveryWithInstall": true,     // 应用内安装模块时发布该共享包
  "pages": "$profile:main_pages",  // 配置页面加载标识符，适用于声明 HARP/合HAR中的跳转页
  "deviceTypes": ["phone", "tablet"]
}
}

说明：改type为shared后必须配置deliveryWithInstall字段为true，和确保有合法pages配置（&#124，表示绑定了负责页面绑定的页面加载。”

【第二步】建立和配置模块跳转页面清单 在资源profile目录新建main_pages.json，内容包含可共享页面的路径：

文件路径：src/main/resources/base/profile/main_pages.json

{
  "src": [
  "pages/PageIndex"
  ]
}

【第三步】构建build中取消默认的混淆规则导出字段 修改build-profile.json5,注意在shared 模式下最好删除配置consumerFiles字字段（模）。以下是没有该配置项或删除之后的示例：

{
  "apiType": 'stageMode',
  "buildOption": {}
}
// 已去除 "consumerFiles": "./consumer-rules.txt"

【第四步】修改构建脚本hvgorfile.ts 中的任务类型

在该文件中，将原来由Hártasks改动的代码块替换为启用HSBT的任务： 文件路径：hvigorfile.ts

import { hspTasks } from '@ohos/hvigor-ohos-plugin';
export default {
  system: hspTasks,
  plugins: []
}

【第五步】增加packageType & Index入口模板 此步骤较为重要，在module中添加Index.h文件用于对外输出：

增加src/main/resources/base/proflile次次Module主类型：

文件：src/main/resources/base/profile/oh-package.json5

{
  "name": "library",
"version": "1.0.0",
"packageType": "interfaceHar", // 该InterfaceHar表示当前是HSP对外接口类型
}

在/src/main/resources/base/profile文件夹中创建Index.ets，将名义export输出至外部使用：

路径： src/main/resources/base/profile/Index.ets

export { PageIndex } from './pages/PageIndex';
// 应当包含在src/main/ets/pages的 PageIndex.ets 是实际页面文件

第六步：创建实际公开页文件

进入ets目录，创建页面文件，支持符合ArkTS语法的页面布局:

路径: src/main/ets/pages/PageIndex.ets

@Entry
@Component
struct PageIndex {
  @State message: string = 'hello world'
  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Blue)
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

第七步：最后一步重新编译模块

1. 进入模块所在的文件夹。
2. 运行hvigorw或点击DevEco Studio Build菜单的 Build > Build HSP 对模块进行编译。

编译生成的产物，可在工程的build目录下得到 library-default-unsigned.hsp 和 library.har。

**A C A U T I O N**

确保编码及结构文件大小写精准概率均等。

---

# 🧩 **总结**

以上步骤完成了Har到Hsp的配置转换和技术性修改。若修改过程出现依赖报错或配置未生效，应按步骤验证相关时，其中步骤重点包括`modules.json5`及`hvigorfile interface`与publicated中方的修改，并删除consumerFiles段入口，这一点是容易被忽略的关键。若不配置导致不能再接收H页表的调用，请仔细检查public命名页面文件中强制显示跳转正确的键值（Pages 保留文字类名称），保证홍页面统一源自H and/or HSP下跳转到直。文章中提到的核心要点均适合ACS stage project，或HarmonyOS member codebase用于处理多重环境。