前言HarmonyOS 的应用包结构采用了分层模块化设计将代码和资源组织为 HAPHarmonyOS Ability Package、HSPHarmonyOS Shared Package和 HARHarmonyOS Archive三种包格式。这种设计使得应用可以按需交付、动态加载从而显著减小安装包体积并提升启动速度。本文以 小事记xiaoshiji_ohos_app 项目的build-profile.json5和oh-package.json5为切入点深入解析 HAP/HSP/HAR 三种包格式的差异、deliveryWithInstall的交付策略以及多products的构建配置。核心特点简单易用API 设计直观上手成本低性能优异底层优化充分运行效率高扩展性强支持自定义配置和扩展本文参考 HarmonyOS 官方文档application-package-overview.md 和 application-package-structure-stage.md。一、三种包格式概述1.1 包格式对比对比维度HAPHSPHAR全称HarmonyOS Ability PackageHarmonyOS Shared PackageHarmonyOS Archive是否可独立运行✅❌❌包含代码✅✅✅包含资源✅✅✅包含配置文件✅✅❌依赖方式安装时包含运行时共享编译时静态引用多模块共享不共享运行时实例共享编译时代码复制典型用途应用主入口、功能模块公共组件库、工具库纯代码库、SDK包格式的选择决策树需要独立运行 ├── ✅ 是 → HAP (entry / feature) └── ❌ 否 → 需要被多个 HAP 共享 ├── ✅ 是 → 需要运行时实例共享 │ ├── ✅ 是 → HSP动态共享包 │ └── ❌ 否 → HAR静态共享包 └── ❌ 否 → HAR纯代码库1.2 小事记当前使用的包结构小事记是一个单模块应用当前只包含一个entry类型的 HAP 包xiaoshiji_ohos_app/ ├── AppScope/ ← 应用级配置 ├── entry/ ← 主 HAP 模块 │ ├── src/main/ │ │ ├── ets/ ← ArkTS 源代码 │ │ ├── resources/ ← 资源文件 │ │ └── module.json5 ← 模块配置 │ ├── build-profile.json5 ← 模块构建配置 │ └── oh-package.json5 ← 模块依赖声明 ├── build-profile.json5 ← 工程级构建配置 ├── oh-package.json5 ← 工程级依赖声明 └── hvigor/ ← 构建工具配置工程的build-profile.json5中modules数组定义了包含的模块{ modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [ default ] } ] } ] }二、HAPHarmonyOS Ability Package2.1 HAP 的两种类型HAP 是应用的基本交付单元分为entry和feature两种entry 类型— 应用主入口必须存在且唯一// entry/src/main/module.json5 { module: { name: entry, type: entry, // 主入口模块 mainElement: EntryAbility, // ... } }feature 类型— 按需加载的功能模块// feature_share/src/main/module.json5 { module: { name: feature_share, type: feature, // 功能模块 mainElement: ShareAbility, deliveryWithInstall: false, // 按需交付 // ... } }2.2 deliveryWithInstall 交付策略deliveryWithInstall是 HAP 模块的关键属性决定模块是否随应用安装包一起交付deliveryWithInstall安装时行为运行时行为使用场景true随主包一起安装立即可用核心功能、首页false不安装需按需下载使用时通过requestBundleInstall下载低频功能、大资源模块// 按需下载并安装 feature 模块 import { bundleManager } from kit.AbilityKit; async function downloadFeatureModule() { try { const installParam { bundleFilePath: , hapModules: [ { moduleName: feature_share, hapFilePaths: [/data/.../feature_share.hap] } ] }; await bundleManager.requestBundleInstall(installParam); console.log(feature 模块安装成功); } catch (err) { console.error(模块安装失败: ${err.message}); } }2.3 HAP 的构建产物HAP 的构建产物是.hap文件实际是一个 ZIP 压缩包包含entry.hap ├── ets/ ← 编译后的字节码 │ └── entryability/ │ └── EntryAbility.abc ├── resources/ ← 资源文件 │ ├── base/ │ │ ├── element/ │ │ ├── media/ │ │ └── profile/ │ └── en_US/ ├── module.json5 ← 模块配置 └── pack.info ← 打包信息三、HSPHarmonyOS Shared Package3.1 HSP 的共享机制HSP是运行时共享包多个 HAP 可以同时引用同一个 HSP运行时只有一份实例节省内存// hsp_common/src/main/module.json5 { module: { name: hsp_common, type: hsp, // 动态共享包 // ... } }HSP 的引用方式// entry/oh-package.json5 — 在 entry 中引用 HSP { name: entry, version: 1.0.0, dependencies: { xiaoshiji/common: file:../hsp_common // 本地路径引用 } }3.2 HSP 与 HAR 的共享区别对比维度HSPHAR编译方式单独编译为 .hsp 文件编译后拷贝到宿主 HAP运行时实例共享同一个实例各 HAP 各自持有一份拷贝代码体积总体积小不重复总体积大重复拷贝更新方式独立更新 HSP需要更新整个 HAP调试难度需要独立调试调试简单何时选择 HSP 而非 HAR多个 entry/feature 共享公共代码— 避免代码重复打包导致包体积膨胀公共组件库需要运行时单例— 如主题管理、日志模块需要独立更新组件库— HSP 可以单独发布新版本而不需要更新整个应用3.3 HSP 的升级路径如果小事记计划增加一个“分享“功能模块可以按以下路径将公共组件抽取为 HSP# 当前结构单模块 xiaoshiji_ohos_app/ ├── entry/ ← 所有代码都在 entry 中 # 重构后结构多模块 HSP xiaoshiji_ohos_app/ ├── entry/ ← 主 HAP保持不变 ├── feature_share/ ← 新增 feature HAP分享功能 └── hsp_common/ ← 新增 HSP公共组件 ├── src/main/ets/ │ ├── components/ ← 共享组件 │ ├── utils/ ← 工具函数 │ └── models/ ← 共享数据模型 └── src/main/module.json5四、HARHarmonyOS Archive4.1 HAR 的静态引用机制HAR是静态共享包编译时将其代码和资源复制到宿主 HAP 中类似 Android 的 AAR 或 iOS 的静态库// har_utils/oh-package.json5 { name: xiaoshiji/utils, version: 1.0.0, description: 公共工具函数库, dependencies: {} }在宿主模块中引用// entry/oh-package.json5 { name: entry, version: 1.0.0, dependencies: { xiaoshiji/utils: file:../har_utils // 静态引用 } }4.2 HAR 的使用限制不支持module.json5— HAR 不包含配置文件不能声明 Ability 或 ExtensionAbility不支持$profile资源引用— 配置资源必须在宿主模块中定义不支持页面路由— HAR 中不能包含Entry装饰的页面组件资源 ID 冲突— 多个 HAR 中的资源 ID 可能冲突需要通过$r(package:name/xxx)指定包名// 在 HAR 中引用自己的资源 import { BusinessError } from kit.BasicServicesKit; // 使用 $r 引用 HAR 包内的资源 // 格式$r(包名/资源类型:资源名称) let sharedString $r(xiaoshiji/utils/string:hello_world);五、oh-package.json5 依赖管理5.1 工程级与模块级依赖小事记的依赖管理分为两级工程级依赖根目录oh-package.json5// 根目录 oh-package.json5 { modelVersion: 6.0.2, description: Please describe the basic information., dependencies: { }, devDependencies: { ohos/hypium: 1.0.25, // 单元测试框架 ohos/hamock: 1.0.0 // Mock 测试框架 } }模块级依赖entry/oh-package.json5// entry/oh-package.json5 { name: entry, version: 1.0.0, description: Please describe the basic information., main: , author: , license: , dependencies: {} }5.2 依赖版本管理oh-package-lock.json5文件锁定了所有依赖的具体版本确保构建可复现// oh-package-lock.json5部分内容 { lockfileVersion: 1.0, packages: { ohos/hypium: { version: 1.0.25, resolved: https://repo.harmonyos.com/ohpm/ohos/hypium/-/1.0.25.tgz }, ohos/hamock: { version: 1.0.0, resolved: https://repo.harmonyos.com/ohpm/ohos/hamock/-/1.0.0.tgz } } }5.3 依赖类型对比依赖类型配置位置作用域示例dependencies运行依赖编译 运行时业务库、组件库devDependencies开发依赖仅编译时测试框架、构建工具peerDependencies同伴依赖运行时提供插件化框架六、products 构建配置6.1 多产品变体build-profile.json5中的products数组定义了应用的不同构建变体{ app: { products: [ { name: default, // 产品名称 signingConfig: default, // 签名配置 targetSdkVersion: 6.0.2(22), // 目标 SDK 版本 compatibleSdkVersion: 6.0.2(22), // 兼容 SDK 版本 runtimeOS: HarmonyOS, // 目标操作系统 buildOption: { strictMode: { caseSensitiveCheck: true, // 文件名大小写检查 useNormalizedOHMUrl: true // 标准化 OHM URL } } } ] } }6.2 多产品场景下的配置产品名称用途签名配置目标 SDKdefault开发调试debug 证书最新 SDKrelease应用商店发布release 证书最低兼容 SDKbeta内测分发beta 证书最新 SDK// 多产品配置示例 { app: { products: [ { name: debug, signingConfig: debug, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12) }, { name: release, signingConfig: release, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12) }, { name: beta, signingConfig: beta, targetSdkVersion: 6.0.2(22), compatibleSdkVersion: 5.0.0(12) } ] } }6.3 buildModeSet 构建模式buildModeSet定义了两种构建模式{ buildModeSet: [ { name: debug // 调试模式未混淆、可调试 }, { name: release // 发布模式已混淆、不可调试 } ] }debug 与 release 模式的区别对比维度debugrelease代码混淆❌ 不混淆✅ 已混淆可调试性✅ 可调试❌ 不可调试签名证书debug 证书release 证书性能较低较高安装方式DevEco Studio 直接安装通过应用市场分发七、包体积优化策略7.1 资源混淆与压缩优化手段节省空间配置方式说明资源混淆10%-15%arkOptions.obfuscation混淆资源名称代码混淆20%-30%obfuscation-rules.txt混淆类名、方法名图片压缩50%-80%使用 WebP 格式替代 PNG/JPG移除未用资源5%-10%Lint 检查删除未引用的资源文件7.2 按需交付策略// 低频功能模块设置为按需交付 { module: { name: feature_ai_generate, type: feature, deliveryWithInstall: false, // 不随安装包交付 installationFree: false } }7.3 公共代码抽取为 HSP// 将公共代码抽取为 HSP 避免重复打包 { module: { name: hsp_common, type: hsp } }八、版本号与构建号管理8.1 版本号的编码规范小事记的versionCode: 1000000遵循标准的编码规范// 版本号编码公式 // versionCode MAJOR * 1000000 MINOR * 10000 PATCH * 100 BUILD // 1.0.0.0 → 1000000 // 2.3.4.5 → 2030405 function encodeVersion(major: number, minor: number, patch: number, build: number): number { return major * 1000000 minor * 10000 patch * 100 build; } function decodeVersion(versionCode: number): { major: number, minor: number, patch: number, build: number } { return { major: Math.floor(versionCode / 1000000), minor: Math.floor((versionCode % 1000000) / 10000), patch: Math.floor((versionCode % 10000) / 100), build: versionCode % 100 }; }8.2 版本更新策略场景versionCode 变化versionName 变化是否强制更新修复 Bug11.0.0.x → 1.0.0.y❌新增功能1001.0.x → 1.0.y❌重大变更100001.x → 1.y✅架构重构1000000x → y✅九、Hvigor 构建工具9.1 构建配置文件小事记的hvigor/hvigor-config.json5配置了构建工具的基本参数// hvigor/hvigor-config.json5 { modelVersion: 6.0.2, dependencies: { ohos/hvigor: 5.0.0, ohos/hvigor-ohos-plugin: 5.0.0 } }9.2 构建流程hvigor clean ← 清理构建产物 hvigor assembleDebug ← 构建 debug 版本 hvigor assembleRelease ← 构建 release 版本 hvigor install ← 安装到设备 hvigor run ← 运行应用十、实际项目中的包结构选择10.1 小事记当前的包结构评估当前小事记采用单模块 HAP 架构适合以下场景应用功能相对集中没有明显的模块化边界团队规模小单模块开发效率更高不需要按需加载功能所有功能都是核心功能不需要跨模块共享运行时实例10.2 未来包结构演进路径阶段包结构触发条件阶段一当前单 entry HAP原型验证、MVP 阶段阶段二entry HAR工具库出现可复用的纯逻辑代码阶段三entry HSP共享组件需要多个模块共享组件实例阶段四entry feature按需加载 HSP功能模块体积庞大需要按需交付总结本文从xiaoshiji_ohos_app项目的构建配置文件和依赖声明出发深入解析了 HarmonyOS 的HAP/HSP/HAR 三层包结构。核心要点如下HAP 是应用的基本交付单元分为entry主入口和feature按需加载两种类型通过deliveryWithInstall控制交付策略HSP 是运行时共享包多个 HAP 可共享同一个 HSP 实例适用于公共组件库和工具库HAR 是编译时静态共享包代码复制到宿主 HAP 中适用于纯逻辑库和 SDKoh-package.json5管理工程级和模块级依赖支持dependencies、devDependencies和peerDependenciesproducts 构建配置支持多产品变体debug/release/beta通过buildModeSet控制构建模式下一篇文章将深入解析应用生命周期全景从 Ability 到 WindowStage 再到 UI 组件的完整状态流转。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源小事记项目源码xiaoshiji_ohos_app官方文档 - 包结构概览application-package-overview.md官方文档 - 包结构 Stageapplication-package-structure-stage.md官方文档 - 包基础application-package-fundamentals.md官方文档 - 包开发application-package-dev.md官方文档 - 安装卸载application-package-install-uninstall.md官方文档 - 配置文件application-configuration-file-stage.md开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net
