1. 项目概述作为一名长期从事鸿蒙应用开发的工程师我发现很多开发者在从FA模型转向Stage模型时对应用程序包结构、应用间跳转以及HSP/HAR等概念的理解存在不少困惑。今天我就结合自己实际项目中的踩坑经验给大家详细剖析这些关键知识点。Stage模型作为鸿蒙新一代应用架构其包结构与FA模型有显著差异。理解这些差异对于开发高性能、可维护的鸿蒙应用至关重要。同时应用间跳转作为鸿蒙生态的核心能力之一在Stage模型下的实现方式也有其特殊性。而HSPHarmony Shared Package和HARHarmony Ability Resources则是提升开发效率的重要工具但很多团队在实际使用中经常混淆它们的适用场景。2. Stage模型应用程序包结构解析2.1 基础目录结构Stage模型的典型项目结构如下以DevEco Studio创建的项目为例MyApplication ├── entry # 主模块 │ ├── src │ │ ├── main │ │ │ ├── ets # 代码目录 │ │ │ │ ├── Application # 应用入口 │ │ │ │ ├── MainAbility # 主Ability │ │ │ │ └── pages # 页面目录 │ │ │ ├── resources # 资源目录 │ │ │ └── config.json # 模块配置文件 │ │ └── ohosTest # 测试代码 │ └── build-profile.json5 # 模块构建配置 ├── feature # 功能模块(可选) ├── library # 库模块(可选) └── ohos.build.json5 # 工程级配置与FA模型相比Stage模型最显著的变化是采用多模块化设计entry/feature/library分工明确配置文件从config.json迁移到更灵活的JSON5格式Ability生命周期管理方式发生根本性改变2.2 config.json5配置详解Stage模型的模块级config.json5包含几个关键部分{ app: { bundleName: com.example.myapp, vendor: example, versionCode: 1, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name }, deviceConfig: {}, module: { name: entry, type: entry, abilities: [ { name: MainAbility, srcEntry: ./ets/MainAbility/MainAbility.ts, icon: $media:icon, label: $string:MainAbility_label, startWindowIcon: $media:icon, startWindowBackground: $color:white, exported: true, skills: [ { actions: [ action.system.home ], entities: [ entity.system.home ] } ] } ] } }关键提示Stage模型中每个Ability必须显式声明exported属性否则其他应用无法通过隐式调用访问它。这是与FA模型的重要区别之一。2.3 资源访问机制Stage模型的资源访问采用全新URI机制// 访问应用内资源 let context getContext(this) as common.UIAbilityContext; let resourceManager context.resourceManager; // 获取字符串资源 resourceManager.getStringValue(app_name).then(value { console.log(value); }); // 获取媒体资源URI let imageUri $r(app.media.icon).id;资源分类与访问方式对照表资源类型前缀示例访问方式应用资源app.app.string.app_name$r(app.string.app_name)系统资源system.system.color.white$r(system.color.white)公共资源common.common.media.ic_launcher$r(common.media.ic_launcher)3. Stage模型下的应用间跳转3.1 显式跳转实现显式跳转需要明确指定目标应用的bundleName和abilityNameimport featureAbility from ohos.ability.featureAbility; import wantConstant from ohos.ability.wantConstant; let wantInfo { deviceId: , // 空表示本设备 bundleName: com.example.targetapp, abilityName: MainAbility, parameters: { // 可传递参数 key1: value1, key2: 123 } }; featureAbility.startAbility(wantInfo).then(() { console.log(startAbility success); }).catch((err) { console.error(startAbility failed: JSON.stringify(err)); });3.2 隐式跳转实现隐式跳转通过actions和entities匹配let wantInfo { action: action.system.detail, entities: [entity.system.detail], parameters: { url: https://example.com } }; featureAbility.startAbility(wantInfo).then(() { console.log(startAbility success); }).catch((err) { console.error(startAbility failed: JSON.stringify(err)); });对应的目标Ability配置{ abilities: [ { name: DetailAbility, skills: [ { actions: [ action.system.detail ], entities: [ entity.system.detail ] } ] } ] }3.3 跳转参数传递最佳实践基本类型参数直接传递parameters: { id: 123, name: 张三, isVIP: true }复杂对象需要序列化let product { id: P1001, name: 华为手机, price: 3999 }; parameters: { product: JSON.stringify(product) }接收方解析示例onCreate(want, launchParam) { let productStr want.parameters.product; if (productStr) { this.product JSON.parse(productStr); } }常见问题当传递的数据量超过1MB时建议使用分布式数据管理或公共文件方式共享数据而不是直接通过want传递。4. Harmony共享包(HSP)深度应用4.1 HSP创建与使用创建HSP模块在DevEco Studio中选择File New Module选择HarmonyOS Shared Package关键配置ohos.build.json5{ subsystem: myhsp, name: mylibrary, buildOption: { hspType: shared } }导出共享内容// index.ts export { default as utils } from ./utils; export { default as network } from ./network;使用方配置依赖{ dependencies: { sharedLibrary: [ { name: mylibrary, version: 1.0.0 } ] } }4.2 HSP与HAR的区别特性对比表特性HSPHAR代码共享方式运行时共享编译时拷贝包大小影响不增加主包体积会增加主包体积更新机制可独立更新需重新发布主包适用场景基础功能库、常用工具集业务相关工具类、组件性能影响首次加载稍慢无额外加载开销版本管理需要严格版本控制随主包版本更新4.3 HSP实战技巧资源冲突解决在HSP的resources/base/element/string.json中{ string: [ { name: app_name, value: HSP模块名称 } ] }主应用使用时需要指定hsp前缀$r(hsp.string.app_name)类名冲突避免为HSP中的公共类添加特定前缀使用命名空间组织代码性能优化建议将不常变动的稳定代码放入HSP避免在HSP中保存状态数据控制HSP的依赖层级5. Harmony能力资源(HAR)开发实践5.1 HAR创建流程创建HAR模块New Module Static Library导出配置ohos.build.json5{ subsystem: mylibrary, name: mylibrary, buildOption: { artifactType: obfuscation } }使用方引用{ dependencies: { localLibrary: [ { name: mylibrary, version: 1.0.0 } ] } }5.2 HAR中的资源处理资源访问规则HAR中的资源会被编译到主包中访问时不需要特殊前缀资源冲突解决方案在HAR的oh-package.json5中配置资源前缀{ resourcePrefix: my_lib_ }最佳实践为所有资源添加前缀提供资源访问的封装方法文档中明确资源命名规范5.3 HAR与HSP的混合使用在实际项目中我们通常会这样组合使用基础工具库使用HSP如网络请求、加密工具UI组件库使用HAR如自定义按钮、对话框业务公共模块根据变更频率选择HSP或HAR示例架构App ├── entry (主模块) ├── feature_shop (功能模块) ├── feature_user (功能模块) ├── lib_network (HSP) ├── lib_ui_components (HAR) └── lib_utils (HSP)6. 常见问题与解决方案6.1 应用跳转失败排查错误现象调用startAbility返回错误码201可能原因目标Ability未导出目标应用未安装权限未配置解决方案检查目标Ability的exported属性确认目标应用已安装import bundle from ohos.bundle; bundle.getBundleInfo(com.example.targetapp, 0) .then(info { console.log(应用已安装); }) .catch(err { console.error(应用未安装); });在config.json5中添加权限{ module: { requestPermissions: [ { name: ohos.permission.START_ABILITIES_FROM_BACKGROUND } ] } }6.2 HSP加载异常处理错误现象HSP功能调用时报undefined is not a function可能原因HSP版本不匹配HSP未正确安装多版本冲突解决方案检查依赖版本一致性确认HSP安装状态import sharedLibrary from ohos.sharedLibrary; sharedLibrary.getSharedLibraryVersion(mylibrary) .then(version { console.log(当前版本 version); });清理缓存后重试# 在设备上执行 rm -rf /data/app/el2/100/base/com.example.myapp/hsp6.3 资源ID冲突解决当出现资源访问异常时可以检查资源命名是否冲突使用完整资源路径访问在build-profile.json5中开启资源混淆{ buildOption: { resourceObfuscation: true } }7. 性能优化建议7.1 包结构优化按需加载配置{ module: { abilities: [ { name: MainAbility, label: $string:MainAbility_label, launchType: standard // 或singleton、specified } ], deliveryWithInstall: false, // 是否随安装下载 installationFree: false // 是否支持免安装 } }资源分包策略基础资源放在entry功能特有资源放在各自feature模块公共资源放入HSP/HAR7.2 应用启动优化减少主包体积延迟加载非必要HSP使用Stage模型的onWindowStageCreate回调优化初始化逻辑onWindowStageCreate(windowStage: window.WindowStage) { // 重要初始化放在这里 windowStage.loadContent(pages/Index, (err, data) { // 次要初始化放在回调中 }); }7.3 内存管理技巧及时释放Ability实例onDestroy() { // 清理资源 this.releaseResources(); }使用WeakReference持有大对象监控内存使用import profiler from ohos.profiler; profiler.getMemoryUsage().then(usage { console.log(内存使用 usage.used / 1024 KB); });在实际项目开发中合理使用HSP可以显著减少包体积我们的电商应用通过将商品详情页的渲染逻辑放入HSP使主包体积减少了约35%。而HAR则非常适合封装业务通用组件比如我们开发的支付组件HAR已经被公司内5个不同应用复用极大提高了开发效率。 
长河君 · 2026/9/20 9:48:27 · 阅读 1.2k 鸿蒙Stage模型开发实战：包结构、应用跳转与HSP/HAR详解
1. 项目概述作为一名长期从事鸿蒙应用开发的工程师我发现很多开发者在从FA模型转向Stage模型时对应用程序包结构、应用间跳转以及HSP/HAR等概念的理解存在不少困惑。今天我就结合自己实际项目中的踩坑经验给大家详细剖析这些关键知识点。Stage模型作为鸿蒙新一代应用架构其包结构与FA模型有显著差异。理解这些差异对于开发高性能、可维护的鸿蒙应用至关重要。同时应用间跳转作为鸿蒙生态的核心能力之一在Stage模型下的实现方式也有其特殊性。而HSPHarmony Shared Package和HARHarmony Ability Resources则是提升开发效率的重要工具但很多团队在实际使用中经常混淆它们的适用场景。2. Stage模型应用程序包结构解析2.1 基础目录结构Stage模型的典型项目结构如下以DevEco Studio创建的项目为例MyApplication ├── entry # 主模块 │ ├── src │ │ ├── main │ │ │ ├── ets # 代码目录 │ │ │ │ ├── Application # 应用入口 │ │ │ │ ├── MainAbility # 主Ability │ │ │ │ └── pages # 页面目录 │ │ │ ├── resources # 资源目录 │ │ │ └── config.json # 模块配置文件 │ │ └── ohosTest # 测试代码 │ └── build-profile.json5 # 模块构建配置 ├── feature # 功能模块(可选) ├── library # 库模块(可选) └── ohos.build.json5 # 工程级配置与FA模型相比Stage模型最显著的变化是采用多模块化设计entry/feature/library分工明确配置文件从config.json迁移到更灵活的JSON5格式Ability生命周期管理方式发生根本性改变2.2 config.json5配置详解Stage模型的模块级config.json5包含几个关键部分{ app: { bundleName: com.example.myapp, vendor: example, versionCode: 1, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name }, deviceConfig: {}, module: { name: entry, type: entry, abilities: [ { name: MainAbility, srcEntry: ./ets/MainAbility/MainAbility.ts, icon: $media:icon, label: $string:MainAbility_label, startWindowIcon: $media:icon, startWindowBackground: $color:white, exported: true, skills: [ { actions: [ action.system.home ], entities: [ entity.system.home ] } ] } ] } }关键提示Stage模型中每个Ability必须显式声明exported属性否则其他应用无法通过隐式调用访问它。这是与FA模型的重要区别之一。2.3 资源访问机制Stage模型的资源访问采用全新URI机制// 访问应用内资源 let context getContext(this) as common.UIAbilityContext; let resourceManager context.resourceManager; // 获取字符串资源 resourceManager.getStringValue(app_name).then(value { console.log(value); }); // 获取媒体资源URI let imageUri $r(app.media.icon).id;资源分类与访问方式对照表资源类型前缀示例访问方式应用资源app.app.string.app_name$r(app.string.app_name)系统资源system.system.color.white$r(system.color.white)公共资源common.common.media.ic_launcher$r(common.media.ic_launcher)3. Stage模型下的应用间跳转3.1 显式跳转实现显式跳转需要明确指定目标应用的bundleName和abilityNameimport featureAbility from ohos.ability.featureAbility; import wantConstant from ohos.ability.wantConstant; let wantInfo { deviceId: , // 空表示本设备 bundleName: com.example.targetapp, abilityName: MainAbility, parameters: { // 可传递参数 key1: value1, key2: 123 } }; featureAbility.startAbility(wantInfo).then(() { console.log(startAbility success); }).catch((err) { console.error(startAbility failed: JSON.stringify(err)); });3.2 隐式跳转实现隐式跳转通过actions和entities匹配let wantInfo { action: action.system.detail, entities: [entity.system.detail], parameters: { url: https://example.com } }; featureAbility.startAbility(wantInfo).then(() { console.log(startAbility success); }).catch((err) { console.error(startAbility failed: JSON.stringify(err)); });对应的目标Ability配置{ abilities: [ { name: DetailAbility, skills: [ { actions: [ action.system.detail ], entities: [ entity.system.detail ] } ] } ] }3.3 跳转参数传递最佳实践基本类型参数直接传递parameters: { id: 123, name: 张三, isVIP: true }复杂对象需要序列化let product { id: P1001, name: 华为手机, price: 3999 }; parameters: { product: JSON.stringify(product) }接收方解析示例onCreate(want, launchParam) { let productStr want.parameters.product; if (productStr) { this.product JSON.parse(productStr); } }常见问题当传递的数据量超过1MB时建议使用分布式数据管理或公共文件方式共享数据而不是直接通过want传递。4. Harmony共享包(HSP)深度应用4.1 HSP创建与使用创建HSP模块在DevEco Studio中选择File New Module选择HarmonyOS Shared Package关键配置ohos.build.json5{ subsystem: myhsp, name: mylibrary, buildOption: { hspType: shared } }导出共享内容// index.ts export { default as utils } from ./utils; export { default as network } from ./network;使用方配置依赖{ dependencies: { sharedLibrary: [ { name: mylibrary, version: 1.0.0 } ] } }4.2 HSP与HAR的区别特性对比表特性HSPHAR代码共享方式运行时共享编译时拷贝包大小影响不增加主包体积会增加主包体积更新机制可独立更新需重新发布主包适用场景基础功能库、常用工具集业务相关工具类、组件性能影响首次加载稍慢无额外加载开销版本管理需要严格版本控制随主包版本更新4.3 HSP实战技巧资源冲突解决在HSP的resources/base/element/string.json中{ string: [ { name: app_name, value: HSP模块名称 } ] }主应用使用时需要指定hsp前缀$r(hsp.string.app_name)类名冲突避免为HSP中的公共类添加特定前缀使用命名空间组织代码性能优化建议将不常变动的稳定代码放入HSP避免在HSP中保存状态数据控制HSP的依赖层级5. Harmony能力资源(HAR)开发实践5.1 HAR创建流程创建HAR模块New Module Static Library导出配置ohos.build.json5{ subsystem: mylibrary, name: mylibrary, buildOption: { artifactType: obfuscation } }使用方引用{ dependencies: { localLibrary: [ { name: mylibrary, version: 1.0.0 } ] } }5.2 HAR中的资源处理资源访问规则HAR中的资源会被编译到主包中访问时不需要特殊前缀资源冲突解决方案在HAR的oh-package.json5中配置资源前缀{ resourcePrefix: my_lib_ }最佳实践为所有资源添加前缀提供资源访问的封装方法文档中明确资源命名规范5.3 HAR与HSP的混合使用在实际项目中我们通常会这样组合使用基础工具库使用HSP如网络请求、加密工具UI组件库使用HAR如自定义按钮、对话框业务公共模块根据变更频率选择HSP或HAR示例架构App ├── entry (主模块) ├── feature_shop (功能模块) ├── feature_user (功能模块) ├── lib_network (HSP) ├── lib_ui_components (HAR) └── lib_utils (HSP)6. 常见问题与解决方案6.1 应用跳转失败排查错误现象调用startAbility返回错误码201可能原因目标Ability未导出目标应用未安装权限未配置解决方案检查目标Ability的exported属性确认目标应用已安装import bundle from ohos.bundle; bundle.getBundleInfo(com.example.targetapp, 0) .then(info { console.log(应用已安装); }) .catch(err { console.error(应用未安装); });在config.json5中添加权限{ module: { requestPermissions: [ { name: ohos.permission.START_ABILITIES_FROM_BACKGROUND } ] } }6.2 HSP加载异常处理错误现象HSP功能调用时报undefined is not a function可能原因HSP版本不匹配HSP未正确安装多版本冲突解决方案检查依赖版本一致性确认HSP安装状态import sharedLibrary from ohos.sharedLibrary; sharedLibrary.getSharedLibraryVersion(mylibrary) .then(version { console.log(当前版本 version); });清理缓存后重试# 在设备上执行 rm -rf /data/app/el2/100/base/com.example.myapp/hsp6.3 资源ID冲突解决当出现资源访问异常时可以检查资源命名是否冲突使用完整资源路径访问在build-profile.json5中开启资源混淆{ buildOption: { resourceObfuscation: true } }7. 性能优化建议7.1 包结构优化按需加载配置{ module: { abilities: [ { name: MainAbility, label: $string:MainAbility_label, launchType: standard // 或singleton、specified } ], deliveryWithInstall: false, // 是否随安装下载 installationFree: false // 是否支持免安装 } }资源分包策略基础资源放在entry功能特有资源放在各自feature模块公共资源放入HSP/HAR7.2 应用启动优化减少主包体积延迟加载非必要HSP使用Stage模型的onWindowStageCreate回调优化初始化逻辑onWindowStageCreate(windowStage: window.WindowStage) { // 重要初始化放在这里 windowStage.loadContent(pages/Index, (err, data) { // 次要初始化放在回调中 }); }7.3 内存管理技巧及时释放Ability实例onDestroy() { // 清理资源 this.releaseResources(); }使用WeakReference持有大对象监控内存使用import profiler from ohos.profiler; profiler.getMemoryUsage().then(usage { console.log(内存使用 usage.used / 1024 KB); });在实际项目开发中合理使用HSP可以显著减少包体积我们的电商应用通过将商品详情页的渲染逻辑放入HSP使主包体积减少了约35%。而HAR则非常适合封装业务通用组件比如我们开发的支付组件HAR已经被公司内5个不同应用复用极大提高了开发效率。