文章目录每日一句正能量一、前言依赖库是应用体积的沉默膨胀器二、HarmonyOS 依赖库精简技术全景图三、钻石依赖问题与 overrides 版本统一3.1 钻石依赖问题的本质3.2 overrides强制统一依赖版本3.3 本地包替换临时修复四、HAR → HSP消除重复代码拷贝4.1 HAR 与 HSP 的本质差异4.2 HAR → HSP 替换实战4.3 DevEco Studio 6.0 自动去重五、ohpm 依赖分析工具链5.1 ohpm list查看完整依赖树5.2 ohpm prune清理未使用依赖5.3 ohpm outdated检测过期依赖5.4 --analyze编译性能分析5.5 app-check-tool重复依赖扫描六、传递依赖优化与循环依赖检测6.1 传递依赖限制6.2 循环依赖检测七、Feature HAP 按需加载终极依赖优化八、实战案例中型应用依赖库精简8.1 项目概况8.2 优化步骤与效果8.3 优化配置汇总九、CI/CD 集成自动化依赖治理十、总结与最佳实践每日一句正能量求木之长者必固其根本欲流之远者必浚其泉源。无论是个人成长、事业建设还是关系经营追逐枝叶的繁茂速成、表象不如深耕根本能力、品德、健康想要源远流长就必须疏通源头初心、动机、系统。一切长久的美好都离不开扎实的基础。一、前言依赖库是应用体积的沉默膨胀器在 HarmonyOS 应用开发中依赖库的管理是一个容易被忽视但影响深远的环节。随着业务迭代项目中的依赖数量会不断增长——三方 SDK、内部工具库、UI 组件库、网络请求库、数据存储库……每一个依赖的引入都看似微不足道但累积起来却能让应用的包体积膨胀到难以控制的程度。更隐蔽的是钻石依赖问题当多个模块依赖同一个库的不同版本时包管理器OHPM默认选择最近版本这可能导致编译失败或运行时崩溃。而对于包含 Native 代码C的依赖版本不兼容会直接引发符号表错误造成应用启动即崩溃。HarmonyOS 提供了完整的依赖治理工具链从ohpm list查看依赖树、ohpm prune清理未使用依赖、overrides统一版本到deduplicateHar自动去重、HAR→HSP 动态共享替换。本文将系统讲解这些技术的原理、配置方法和实战技巧帮助开发者实现依赖体积减少45%、整体包体积减少35%的目标。二、HarmonyOS 依赖库精简技术全景图HarmonyOS 的依赖库精简可分为三大维度依赖去重、版本治理、按需加载每个维度都有对应的官方工具支持。优化维度核心技术工具支持预期效果依赖去重ohpm 依赖去重、HAR→HSP 替换、deduplicateHarapp-check-tool、Build Analyzer减少 30-50% 重复依赖体积版本治理overrides 统一版本、resolutionStrictness、钻石依赖消除ohpm list、ohpm outdated消除版本冲突提升编译稳定性按需加载Feature HAP 拆分、动态 import、延迟初始化hvigor、app-check-tool减少 60-70% 初始包体积三、钻石依赖问题与 overrides 版本统一3.1 钻石依赖问题的本质钻石依赖Diamond Dependency是多模块工程中最常见的问题之一。当两个不同的模块分别依赖同一个库的不同版本时包管理器需要决定使用哪个版本——这个决定可能引发连锁反应。典型场景MyApp ├── Entry HAP → ohos/aki1.0.0 ├── Feature Pay HAP → ohos/aki1.1.0 └── Feature Chat HAP → ohos/aki1.0.0在这个场景中Entry 和 Feature Chat 依赖aki1.0.0Feature Pay 依赖aki1.1.0OHPM 默认选择最近版本1.1.0但aki1.1.0的 Native 符号表与aki1.0.0不兼容结果Entry 和 Feature Chat 在调用aki的 Native 方法时发生符号解析失败应用崩溃3.2 overrides强制统一依赖版本overrides是 OHPM 提供的版本覆盖机制可以在工程级oh-package.json5中强制指定所有模块包括传递依赖使用的版本。// 工程级 oh-package.json5项目根目录 { name: MyHarmonyApp, version: 1.0.0, description: 示例 HarmonyOS 应用, // overrides: 强制所有模块使用指定版本 overrides: { ohos/aki: 1.1.0, // 统一使用 1.1.0 ohos/net: 1.2.0, // 统一使用 1.2.0 ohos/crypto: 2.0.1, // 统一使用 2.0.1 ohos/file.picker: 1.0.5 // 统一使用 1.0.5 }, // strict 模式强制严格匹配版本不一致时直接报错 resolutionStrictness: strict }overrides 的优先级规则最高优先级overrides中的声明次优先级模块级dependencies中的声明最低优先级传递依赖的默认版本strict 模式的作用# 若某个模块的 dependencies 中声明了与 overrides 不一致的版本# strict 模式下 OHPM 会直接报错而不是静默覆盖# 示例报错信息# ERROR: Module feature_pay depends on ohos/aki1.0.0,# but overrides requires ohos/aki1.1.0.# Please update the dependency version.3.3 本地包替换临时修复当某个三方库存在 bug 但官方尚未修复时可以通过overrides指定本地修改后的版本{ overrides: { ohos/file.photoPicker: file:./local_patches/photoPicker_fixed } }local_patches/ └── photoPicker_fixed/ ├── oh-package.json5 ├── index.ets └── ...注意事项overrides仅在工程级oh-package.json5中生效修改overrides后需要重新执行ohpm install本地包替换仅适用于临时修复长期应推动官方修复四、HAR → HSP消除重复代码拷贝4.1 HAR 与 HSP 的本质差异特性HAR静态共享包HSP动态共享包复用时机编译时代码复制到每个模块运行时动态加载进程中仅一份包体积影响增加重复代码减少共享代码编译产物每个模块独立包含 HAR 代码HSP 独立打包模块仅保留引用适用场景三方库分发、独立工具类应用内多模块共享代码以一个包含 Entry HAP 3 个 Feature HAP 的工程为例若utils.har100KB、network.har200KB和chart.har300KB被多个模块引用使用 HAR总包体积 各模块自身代码 utils×3 network×3 chart×3 3000KB使用 HSP总包体积 各模块自身代码 utils×1 network×1 chart×1 1800KB体积减少1200KB40%4.2 HAR → HSP 替换实战步骤一创建 HSP 模块// shared_utils/module.json5 { module: { name: shared_utils, type: shared, description: 公共工具类动态共享包, mainElement: SharedUtilsAbility, abilities: [ { name: SharedUtilsAbility, srcEntry: ./ets/utilsability/UtilsAbility.ets } ] } }步骤二修改各模块的依赖引用// entry/oh-package.json5 { dependencies: { // 原 HAR 依赖编译时拷贝 // myapp/utils: file:./utils.har // 改为 HSP 依赖运行时共享 myapp/utils: file:./shared_utils } }步骤三HSP 混淆白名单配置由于 HAP 和 HSP 是独立编译的混淆后导出名称可能不一致需要配置白名单// shared_utils/consumer-rules.txt-keep-global-name formatDate parseUrl deepClone NetworkManager StorageManager// shared_utils/obfuscation-rules.txt-keep-global-name formatDate parseUrl deepClone NetworkManager StorageManager4.3 DevEco Studio 6.0 自动去重从 DevEco Studio 6.0.1 Beta1 开始支持在构建 APP/HAP/HSP 时自动去除 HSP 中重复的 HAR// 工程级 build-profile.json5 { apiType: stageMode, buildOption: { packOptions: { deduplicateHar: true // 去除 HSP 中重复的 HAR } }, useNormalizedOHMUrl: true }效果当多个 HSP 引用了同一个 HAR 时构建工具会自动去重确保最终包中该 HAR 仅存在一份。五、ohpm 依赖分析工具链HarmonyOS 提供了完整的依赖分析工具链帮助开发者全面了解项目的依赖状况。5.1 ohpm list查看完整依赖树# 查看当前模块的依赖树包含传递依赖ohpm list--depth3# 输出示例# MyHarmonyApp# ├── ohos/aki1.1.0# │ └── ohos/crypto2.0.1# ├── ohos/net1.2.0# │ ├── ohos/aki1.1.0 (dedup)# │ └── ohos/utils1.0.0# ├── ohos/chart3.0.0# │ └── ohos/aki1.1.0 (dedup)# └── ohos/file.picker1.0.5# 查找特定依赖的所有版本ohpm list--depth3|grepohos/aki# 查看依赖树并标记重复项ohpm list--depth3--duplicates5.2 ohpm prune清理未使用依赖# 清理当前模块中未使用的依赖ohpm prune# 清理所有模块的未使用依赖ohpm prune--all# 清理并更新 oh-package-lock.json5ohpm prune--update# 清理并显示详细信息ohpm prune--verbose注意事项ohpm prune基于oh-package-lock.json5分析依赖使用关系清理前建议备份oh-package-lock.json5清理后需要重新构建验证功能完整性5.3 ohpm outdated检测过期依赖# 检测所有过期依赖ohpm outdated# 输出示例# Package Current Wanted Latest# ohos/net 1.1.0 1.2.0 1.2.0# ohos/crypto 1.5.0 2.0.1 2.0.1# ohos/chart 2.5.0 3.0.0 3.0.0# 导出 JSON 格式报告ohpm outdated--jsonoutdated-report.json# 仅检测安全更新ohpm outdated--security5.4 --analyze编译性能分析# 生成编译性能依赖图hvigorw assembleRelease--analyze# 分析结果保存在 build/reports/analyze/# 包含# - 各模块编译耗时# - 依赖解析耗时# - 循环依赖检测# - 冗余依赖警告5.5 app-check-tool重复依赖扫描# 扫描 HAP/HSP 包中的重复 HARjava-jar$OHOS_SDK/toolchains/lib/app-check-tool.jar\--modehap\--inputbuild/outputs/default/packaging/entry-default-signed.hap\--output./scan-report/# 扫描结果中的重复依赖示例# {# duplicateAnalysis: [# {# fileName: libnetwork.so,# occurrences: 4,# wastedSize: 25794972,# suggestion: 建议将包含 libnetwork.so 的 HAR 包改为 HSP 动态共享包# }# ]# }六、传递依赖优化与循环依赖检测6.1 传递依赖限制默认情况下OHPM 会安装所有传递依赖即依赖的依赖。对于大型项目这可能导致依赖树深度膨胀。// oh-package.json5 - 限制传递依赖 { dependencies: { ohos/net: { version: 1.2.0, transitive: false // 不安装 net 的传递依赖 } } }使用场景当某个依赖的传递依赖与项目已有依赖冲突时当只需要依赖的核心功能不需要其附属库时当传递依赖体积过大且功能非必需时6.2 循环依赖检测循环依赖A → B → C → A会导致编译时依赖解析死循环或运行时初始化异常。# 使用 hvigor 的 --analyze 选项检测循环依赖hvigorw assembleRelease--analyze# 循环依赖报错示例# ERROR: Circular dependency detected:# module_a - module_b - module_c - module_a## Solution: Extract common code into a new HSP module.循环依赖的解决方案提取公共代码将循环依赖中的公共部分提取为独立的 HSP 模块接口隔离使用接口Interface解耦模块间的直接依赖事件总线使用事件机制替代直接的模块调用// 解耦前循环依赖// module_a/ets/A.etsimport{B}frommyapp/module_b;// A → B// module_b/ets/B.etsimport{C}frommyapp/module_c;// B → C// module_c/ets/C.etsimport{A}frommyapp/module_a;// C → A (循环)// 解耦后事件总线// shared_events/ets/EventBus.etsexportclassEventBus{privatestaticlisteners:Mapstring,Array(data:any)voidnewMap();staticon(event:string,callback:(data:any)void):void{if(!this.listeners.has(event)){this.listeners.set(event,[]);}this.listeners.get(event)!.push(callback);}staticemit(event:string,data:any):void{this.listeners.get(event)?.forEach(cbcb(data));}}// module_a/ets/A.etsimport{EventBus}frommyapp/shared_events;EventBus.emit(module_a_ready,{status:ok});// module_c/ets/C.etsimport{EventBus}frommyapp/shared_events;EventBus.on(module_a_ready,(data){console.log(Module A is ready:,data);});七、Feature HAP 按需加载终极依赖优化对于非核心功能模块如客服聊天、地图导航、支付功能可以拆分为独立的 Feature HAP通过动态导入按需加载。// 动态导入 Feature 模块asyncfunctionopenCustomerService(){try{// 首次调用时下载并加载 Feature HAPconstmoduleawaitimport(myapp/feature_customer_service);module.launchCustomerService();}catch(err){console.error(模块加载失败:,err);promptAction.showToast({message:功能加载失败请检查网络});}}// 工程级 build-profile.json5 配置{modules:[{name:entry,srcPath:./entry},{name:feature_customer_service,srcPath:./feature_customer_service,targets:[{name:default,applyToProducts:[default]}]},{name:feature_map,srcPath:./feature_map,targets:[{name:default,applyToProducts:[default]}]}]}效果初始安装包仅包含 Entry HAP 和必要的 HSPFeature HAP 在用户首次触发功能时下载典型场景下初始包体积减少60-70%八、实战案例中型应用依赖库精简8.1 项目概况模块数量Entry HAP ×1 Feature HAP ×3 HAR ×8三方依赖15 个初始依赖体积28.5 MB初始总包体积156.3 MB8.2 优化步骤与效果优化项优化前优化后减少比例具体措施overrides 版本统一依赖 28.5MB依赖 20.0MB30%统一 5 个冲突库版本HAR→HSP 替换重复 12MB重复 0MB100%3 个 HAR 改为 HSPohpm prune未使用 8MB未使用 0MB100%清理 4 个未使用依赖deduplicateHar重复 HAR 6MB重复 HAR 3MB50%DevEco 6.0 自动去重传递依赖限制传递依赖 15MB传递依赖 9MB40%限制 3 个库的传递依赖过期依赖升级旧版本 5MB新版本 4MB20%升级 2 个过期库Feature HAP 拆分初始包 156MB初始包 48MB70%2 个功能模块按需加载循环依赖修复编译不稳定编译稳定—提取公共 HSP 解耦合计156.3MB48.0MB69%—8.3 优化配置汇总// 工程级 oh-package.json5 { name: MyHarmonyApp, version: 2.0.0, overrides: { ohos/aki: 1.1.0, ohos/net: 1.2.0, ohos/crypto: 2.0.1, ohos/file.picker: 1.0.5, ohos/chart: 3.0.0 }, resolutionStrictness: strict }// 工程级 build-profile.json5 { apiType: stageMode, buildOption: { packOptions: { deduplicateHar: true } }, useNormalizedOHMUrl: true, modules: [ { name: entry, srcPath: ./entry }, { name: shared_utils, srcPath: ./shared_utils }, { name: shared_network, srcPath: ./shared_network }, { name: feature_pay, srcPath: ./feature_pay }, { name: feature_chat, srcPath: ./feature_chat } ] }九、CI/CD 集成自动化依赖治理# .github/workflows/dependency-check.ymlname:Dependency Governanceon:[push,pull_request]jobs:check:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Check dependency conflictsrun:|ohpm list --depth3 --json dependency-tree.json conflicts$(cat dependency-tree.json | jq [.. | objects | select(has(version)) | {name: keys[0], version: .version}] | group_by(.name) | map(select(length 1))) if [ $conflicts ! [] ]; then echo ❌ 发现依赖版本冲突: echo $conflicts | jq . exit 1 fi echo ✅ 依赖冲突检查通过-name:Check outdated dependenciesrun:|ohpm outdated --json outdated.json outdated_count$(cat outdated.json | jq length) if [ $outdated_count -gt 5 ]; then echo ⚠️ 发现 $outdated_count 个过期依赖建议升级 cat outdated.json | jq .[] | {name, current, latest} fi-name:Check for unused dependenciesrun:|ohpm prune --all --dry-run-name:Build with analyzerun:|hvigorw assembleRelease --analyze-name:Check bundle sizerun:|size$(stat -c%s build/outputs/default/packaging/app-signed.app) limit$((50 * 1024 * 1024)) # 50MB if [ $size -gt $limit ]; then echo ❌ 包体积超标: $size bytes $limit bytes exit 1 fi echo ✅ 包体积检查通过-name:Generate dependency reportrun:|echo ## 依赖治理报告 dependency-report.md echo dependency-report.md echo ### 依赖树概览 dependency-report.md ohpm list --depth2 dependency-report.md echo dependency-report.md echo ### 过期依赖 dependency-report.md ohpm outdated dependency-report.md || true十、总结与最佳实践本文从钻石依赖治理出发系统讲解了 HarmonyOS 依赖库精简的全链路方案涵盖版本统一、重复消除、未使用清理、按需加载等核心技术。核心最佳实践清单工程级 overrides所有多模块工程必须在根目录oh-package.json5中配置overrides统一关键依赖版本HAR→HSP 优先被多模块引用的共享代码优先使用 HSP消除重复拷贝定期 prune每月执行ohpm prune --all清理未使用依赖过期检测每季度执行ohpm outdated检测并升级过期依赖传递限制对于体积大的依赖评估是否需要限制其传递依赖循环检测每次新增模块依赖时使用--analyze检测循环依赖按需加载非核心功能拆分为 Feature HAP减少初始包体积依赖库精简不是一次性的大扫除而是需要持续监控的日常工程实践。通过建立规范化的依赖治理体系和自动化的检查机制可以确保应用始终保持轻量、稳定、易维护的依赖结构。转载自https://blog.csdn.net/u014727709/article/details/164003986欢迎 点赞✍评论⭐收藏欢迎指正