摘要HAR 是静态打包全部代码安装时一次性装入主包APP 体积大、冷启动慢HSPHarmony Shared Package动态共享库支持运行时按需加载将非核心业务拆分独立动态包首页仅加载基础模块其他功能进入对应页面时再动态拉取 / 加载减小安装包体积、缩短启动耗时。API23 重构 HSP 动态加载上下文、页面路由跳转、资源隔离、内存释放逻辑修复低版本 HSP 页面跳转空白、动态组件渲染失败、包重复加载内存泄漏、资源跨包访问崩溃等问题。本文完整讲解 HSP 创建、依赖配置、动态加载页面 / 工具 / 组件、分包路由、资源隔离、卸载回收配套笔记业务 HSP 实战工程对比 HAR 与 HSP 适用场景给出分包优化规范适配课程设计大型多模块项目、商用轻量化 APP 开发。关键词OpenHarmonyArkTSAPI23HSP动态共享包按需加载分包动态路由包体积优化一、引言1.1 HSP 开发背景静态 HAR 全部代码编译打包进 entry 主模块存在明显短板功能越多安装包越大低端设备安装缓慢首次启动需要加载全部代码冷启动卡顿低频功能笔记、相册、设置长期占用内存后台耗电多业务耦合删除功能需要重新全量编译。HSP 动态共享库解决以上痛点代码、资源独立分包运行时按需加载不用不占用内存主包仅保留首页、登录、基础工具大幅缩减安装包体积低频业务拆分为独立 HSP进入页面时再加载包支持动态卸载退出业务页面释放整个分包内存。OpenHarmony API23 HSP 核心升级点新增 loadPackage/waitPackageLoad 统一加载 API简化异步等待逻辑隔离 HSP 与主包资源域避免图片、常量重名冲突修复动态加载页面返回栈错乱、路由丢失完善包卸载资源回收组件、数据库、定时器自动释放支持 HSP 内部再次依赖基础 HAR复用公共工具严格限制跨包直接导入统一使用动态导入接口杜绝编译爆红。1.2 HSP 与 HAR 核心区分表格类型加载时机包体积跨包导入方式适用场景HAR 静态库编译打包安装即加载合并入主包包大import 静态导入全局基础工具、高频公共组件HSP 动态库运行时按需动态加载独立分包主包极小动态 loadPackage 反射调用低频独立业务笔记、相机相册、设置二、API23 HSP 核心配置与基础 API2.1 HSP 模块 module.json5 基础配置json{ module: { name: hsp_note, type: hsp, description: 笔记动态分包, deviceTypes: [phone], deliveryWithInstall: true, installationFree: false, pages: [ src/main/ets/pages/NoteList ], dependencies: [ { name: har_base, version: 1.0.0, scope: shared } ] } }关键点type 固定为hspHSP 内部可注册 pages 页面独立路由仅能依赖静态 HARHSP 之间禁止互相依赖deliveryWithInstalltrue打包时自动拆分独立分包。2.2 entry 主模块依赖 HSP仅声明不静态合并jsondependencies: [ { name: hsp_note, version: 1.0.0, scope: shared } ]2.3 动态加载核心 APIetsimport hspManager from ohos.hspManager // 1. 异步加载HSP包 await hspManager.loadPackage(hsp_note) // 2. 等待包加载完成获取包上下文 const hspContext await hspManager.waitPackageLoad(hsp_note) // 3. 卸载分包释放全部资源 hspManager.unloadPackage(hsp_note) // 4. 跳转HSP内部页面包名://页面路径 router.pushUrl({url: hsp_note/pages/NoteList})2.4 API23 强制约束禁止直接 import 导入 HSP 内部 ets 代码必须动态加载后反射调用HSP 页面路由格式固定hsp包名/页面完整pages路径HSP 不能定义 UIAbility生命周期统一由 entry 主 Ability 管理跨 HSP 资源不能直接 $r 引用需通过全局 HAR 共享资源页面退出必须 unloadPackage 释放分包防止内存持续上涨同一分包不可重复并发 loadPackage增加加载状态锁防重复请求。三、最简基础示例动态加载并跳转 HSP 页面entry 首页跳转笔记分包etsimport hspManager from ohos.hspManager import router from ohos.router import { showToast } from ohos:har_base/utils/toast_util Entry Component struct Index { State loading: boolean false async jumpNoteHsp() { if (this.loading) return this.loading true try { // 加载笔记动态分包 await hspManager.loadPackage(hsp_note) showToast(笔记模块加载完成) // 跳转HSP内部页面 router.pushUrl({ url: hsp_note/src/main/ets/pages/NoteList }) } catch (err) { showToast(动态模块加载失败) console.error(hsp加载异常, err) } finally { this.loading false } } build() { Column() { Text(主应用首页仅基础包).fontSize(24).margin({ top: 80 }) Button(this.loading ? 加载中... : 打开笔记模块(动态HSP)) .width(300) .height(48) .margin({ top: 30 }) .onClick(() this.jumpNoteHsp()) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }HSP 笔记页面 hsp_note/src/main/ets/pages/NoteList.etsetsimport NoteDbUtil from ohos:har_base/db/note_db import { NoteItemCard } from ohos:har_base/components/NoteItemCard import { NoteItem } from ohos:har_base/model/NoteModel import router from ohos.router import hspManager from ohos.hspManager Entry Component struct NoteList { State list: NoteItem[] [] async aboutToAppear() { const ctx getContext(this) NoteDbUtil.setContext(ctx) await NoteDbUtil.init() this.list await NoteDbUtil.queryList(0, 10) } // 返回首页并卸载HSP分包释放内存 backHome() { router.back() // 卸载动态包 hspManager.unloadPackage(hsp_note) } build() { Column({ space: 12 }) { Row() { Button(返回首页并释放分包).onClick(() this.backHome()) Text(笔记动态分包页面(HSP)).layoutWeight(1).fontSize(20) } List({ space: 10 }).layoutWeight(1) { ForEach(this.list, (item: NoteItem) { ListItem() { NoteItemCard({ data: item }) } }) } } .width(100%) .height(100%) .padding(12) .backgroundColor(#f5f5f5) } async aboutToDisappear() { await NoteDbUtil.closeDB() } }四、实战封装HSP 动态加载工具类 utils/hsp_load_util.etsetsimport hspManager from ohos.hspManager import router from ohos.router import promptAction from ohos.promptAction class HspLoadUtil { private static instance: HspLoadUtil // 记录正在加载的分包防重复并发加载 private loadingMap: Mapstring, boolean new Map() static getInstance(): HspLoadUtil { if (!HspLoadUtil.instance) HspLoadUtil.instance new HspLoadUtil() return HspLoadUtil.instance } // 加载分包并跳转内部页面 async loadAndJump(hspName: string, pagePath: string): Promiseboolean { if (this.loadingMap.get(hspName)) { promptAction.showToast({ message: 模块正在加载请稍等 }) return false } this.loadingMap.set(hspName, true) try { // 加载分包 await hspManager.loadPackage(hspName) // 等待包就绪 await hspManager.waitPackageLoad(hspName) // 跳转页面 router.pushUrl({ url: ${hspName}/${pagePath} }) return true } catch (e) { promptAction.showToast({ message: 功能模块加载失败 }) console.error(HSP[${hspName}]加载失败, e) return false } finally { this.loadingMap.set(hspName, false) } } // 卸载分包释放资源 unload(hspName: string) { hspManager.unloadPackage(hspName) this.loadingMap.delete(hspName) } } export default HspLoadUtil.getInstance()工具调用示例etsimport HspLoadUtil from ../utils/hsp_load_util // 点击按钮加载笔记分包并跳转页面 Button(打开笔记模块) .onClick(async (){ await HspLoadUtil.loadAndJump(hsp_note, src/main/ets/pages/NoteList) })五、HSP 分包工程分层架构规范标准三层架构entry主包首页、登录、全局状态、EntryAbility、HSP 加载工具仅依赖基础 har_base不包含任何低频业务代码har_base静态公共库全局工具、数据模型、通用 UI 组件、常量entry 与所有 HSP 统一依赖共享无重复代码hsp_xxx各业务动态分包hsp_note 笔记模块hsp_camera 相机相册模块hsp_setting 设置模块 每个 HSP 仅依赖 har_base互相不依赖独立按需加载、卸载分包拆分标准必须放入主 entry登录、首页、全局基础工具、启动逻辑适合拆 HSP低频独立完整业务页面不与首页强耦合禁止拆 HSP全局高频组件、通用工具统一放入 HAR。六、性能与内存优化规范加载时机优化不在 aboutToAppear 自动预加载 HSP用户点击按钮再加载减少冷启动耗时内存释放强制规范退出 HSP 业务页面必须调用 unloadPackage释放数据库、定时器、组件缓存防重复加载工具类增加 loadingMap 状态锁避免快速点击重复触发 loadPackage资源复用规范图片、字体、通用组件全部放入 har_baseHSP 不重复存放资源减小分包体积避免嵌套加载禁止在一个 HSP 内部加载另一个 HSP统一由 entry 主包管理分包加载逻辑分包体积控制单个 HSP 控制在 10MB 以内超大业务继续拆分为多个小 HSP。七、API23 升级常见问题解决方案问题 1跳转 HSP 页面提示页面不存在 解决路由路径完整填写hsp包名/完整页面文件路径核对 module.json5 中 pages 注册路径。问题 2多次点击按钮重复加载应用卡顿 解决使用 Map 标记加载状态加载中拦截重复点击。问题 3退出页面不卸载 HSP内存持续上涨 解决页面返回时调用 hspManager.unloadPackage 释放分包资源。问题 4HSP 中使用 RDB/Preferences 上下文失效 解决HSP 页面通过 getContext (this) 获取上下文传入 HAR 工具类不要使用 entry 全局上下文。问题 5编译提示 HSP 之间存在依赖循环 解决HSP 仅允许依赖静态 har_base所有 HSP 互相不引用。问题 6打包后分包未拆分全部合并进 entry 解决HSP 模块 deliveryWithInstall 配置为 true重新构建 App 包。八、总结HSP 动态共享包是 OpenHarmony 官方分包体积优化方案API23 完善动态加载、等待就绪、卸载回收、路由跳转整套能力完美解决静态 HAR 打包主包体积大、冷启动慢、低频功能常驻占用内存等痛点。 工程采用「entry 主包 HAR 公共底层 多 HSP 业务分包」三层标准架构高频基础能力静态复用低频独立业务按需动态加载、用完卸载释放内存兼顾启动速度、安装包大小、内存占用三大性能指标。 代码完全兼容 API23 / HarmonyOS NEXT适合大型综合课程设计、商用轻量化鸿蒙 APP 分包改造。