摘要

本文围绕 HarmonyOS 应用开发中三方库接入后的包体积膨胀与依赖冲突问题，给出一套可落地的治理方案：从选库规范、HAR/HSP 形态选择，到 build-profile.json5 的架构过滤（abiFilters）、strip 去符号、混淆压缩，再到按需 import、overrides 统一依赖版本与 ohpm ls 依赖体检。全文配有完整配置代码与流程图，帮助你把「随手 install」带来的 8MB → 30MB 膨胀重新压回去。

关键词：HarmonyOS、ohpm、包体积优化、HSP、依赖治理

目录

• 一、背景与痛点
• 二、接入规范与规格
• 三、整体流程图
• 四、核心代码（build-profile 体积配置）
  • 4.1 模块级 build-profile.json5：架构过滤 + strip + 混淆
  • 4.2 工程级 build-profile.json5：统一签名与构建模式
  • 4.3 按需引入：只 import 用到的子模块
  • 4.4 依赖版本统一：overrides 解决重复打包
  • 4.5 依赖体检脚本：一键找出冗余依赖
• 五、实战要点
• 六、小结与边界
• 七、总结

一、背景与痛点

鸿蒙生态里 ohpm 上的三方库越来越丰富，但"随手 ohpm install"的后果是：包体从 8MB 飙到 30MB、启动变慢、还偶尔依赖冲突。我第一个版本就因为无脑引入一个"全家桶"网络库，把用不到的 DNS 解析、WebSocket、长连接全打进了包里。

三方库接入本身简单，难的是接入后的体积与依赖治理。本文讲清接入规范 + 包体积优化的几条硬招，都是实测得来的。

二、接入规范与规格

环节	要点
安装	ohpm install <pkg>，优先官方/高 star 库，看最后更新时间
形态	HAR（静态共享包）/ HSP（动态共享包），多模块复用选 HSP
架构	真机只留 arm64-v8a，模拟器才需要 x86_64
体积	开启 strip 去掉调试符号，资源走压缩
冲突	同一库多版本会打包冲突，用 ohpm 依赖提升统一版本

三、整体流程图

下面这张图把「选库 → 接入 → 构建瘦身 → 依赖体检 → 上线」的完整链路串起来，方便对照后文的代码逐项落地。

图中三个关键回路值得注意：

• 选库回路：依赖树过重 → 换库/只引子模块，这是体积问题的源头，越早拦截成本越低。
• 体检回路：包体积不达标 → 回到依赖树复查，每次发版前跑一遍 ohpm ls，能持续压住体积增长。
• 构建瘦身链：abiFilters → strip → 混淆 → HSP → overrides 五步是叠加生效的，缺一步就少省一截。

四、核心代码（build-profile 体积配置）

4.1 模块级 build-profile.json5：架构过滤 + strip + 混淆

// entry/build-profile.json5
{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      // 只保留 64 位真机架构，砍掉 armeabi-v7a / x86_64 的多套 .so
      "abiFilters": ["arm64-v8a"],
      // 去掉 native 调试符号，Release 包体积可降 30%~50%
      "strip": true
    },
    // 开启混淆 + 压缩，减小 ArkTS 产物
    "arkOptions": {
      "obfuscation": {
        "ruleOptions": {
          "enable": true,
          "files": ["./obfuscation-rules.txt"]
        }
      }
    }
  },
  "targets": [
    {
      "name": "default",
      // 仅 release 构建开启体积优化，debug 保留符号便于排查
      "runtimeOS": "HarmonyOS"
    }
  ]
}

说明：abiFilters 决定打进包里的 native 架构，真机几乎全是 arm64-v8a，多留一套就多一份 .so；strip 去掉符号表，不影响运行但能显著瘦身；obfuscation 负责 ArkTS 代码的混淆压缩，注意把反射/序列化用到的类写进白名单。

4.2 工程级 build-profile.json5：统一签名与构建模式

// build-profile.json5（工程根目录）
{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
        // 资源压缩：去掉未引用的图片/字符串
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    { "name": "entry", "srcPath": "./entry", "targets": [{ "name": "default", "applyToProducts": ["default"] }] },
    { "name": "share", "srcPath": "./share", "targets": [{ "name": "default", "applyToProducts": ["default"] }] }
  ]
}

说明：工程级配置负责产品维度（SDK 版本、签名、构建模式），模块级配置负责产物维度（架构、混淆）。useNormalizedOHMUrl 让依赖路径规范化，避免同一库被重复打包。

4.3 按需引入：只 import 用到的子模块

// ✅ 推荐：按需引入子模块，只打进用到的代码
import { request } from '@ohos/net.http';
import { promptAction } from '@ohos.promptAction';

// ❌ 不推荐：整包引入，未使用的模块也会被打进产物
// import * as bigLib from 'big-lib';

async function fetchUserInfo(userId: string): Promise<UserInfo> {
  const httpRequest = request.createHttp();
  try {
    const resp = await httpRequest.request(`https://api.example.com/user/${userId}`, {
      method: request.RequestMethod.GET,
      connectTimeout: 5000,
      readTimeout: 5000
    });
    return JSON.parse(resp.result as string) as UserInfo;
  } finally {
    httpRequest.destroy(); // 及时释放，避免连接泄漏
  }
}

说明：import { request } 只引入子模块，打包器可做 tree-shaking；import * as bigLib 会把整包拉进来。系统已提供的能力（HTTP、弹窗、存储）优先用 @ohos.*，能省掉一个三方依赖。

4.4 依赖版本统一：overrides 解决重复打包

// oh-package.json5
{
  "name": "my_app",
  "version": "1.0.0",
  "dependencies": {
    "big-lib": "^2.1.0"
  },
  "overrides": {
    // 强制所有传递依赖统一到同一版本，避免多版本共存重复打包
    "lodash": "4.17.21",
    "big-lib": "2.1.3"
  }
}

说明：当 A 库依赖 lodash@4.17.0、B 库依赖 lodash@4.17.21 时，ohpm 可能同时打进两份。用 overrides 强制提升到统一版本，既消除冲突也减小体积。

4.5 依赖体检脚本：一键找出冗余依赖

# 查看完整依赖树，定位重复与无人引用的传递依赖
ohpm ls

# 查看某个包的依赖来源，判断能否移除
ohpm ls big-lib

# 清理未在 oh-package.json5 中声明的缓存依赖
ohpm clean

说明：ohpm ls 输出依赖树，重点看同一包出现多个版本的分支；确认无人引用后从 dependencies 删除并重新 ohpm install，包体往往能再降一截。

五、实战要点

要点 1：abiFilters 只留 arm64-v8a。
绝大多数真机是 64 位，保留 armeabi-v7a/x86_64 只会让包里多塞几套 .so。上线构建把 abiFilters 设为 ["arm64-v8a"]，体积和安装时间都降。

要点 2：strip 一定要开。
native 库默认带调试符号，.so 能大 2~3 倍。strip: true 一行，Release 包直接瘦身，且不影响运行。

要点 3：警惕"全家桶"库。
引一个网络库前先看它依赖树。能用 @ohos.net.http 这种系统能力解决的，就别引三方。引用时只 import 子模块，避免整包打进。

要点 4：HSP 复用，别每个模块都打一份。
多模块都用同一库时，用 HSP 动态共享包，运行时加载一份；用 HAR 则每个模块各打一份，包体翻倍。

要点 5：定期跑依赖体检。
用 ohpm ls 看依赖树，删掉无人引用的传递依赖；版本冲突用 overrides 提升到统一版本，避免重复打包。

六、小结与边界

包体积优化不是"上线前突击"，而是接入即治理：选库看依赖、架构只留 64 位、strip 常开、按需引入、HSP 复用。落地五句话：abi 只留 arm64、strip 必开、别引全家桶、HSP 复用、定期体检。

六、总结

把全文压缩成一张「治理清单」，方便直接对照落地：

治理维度	关键动作	预期收益
选库	优先系统能力 @ohos.*，其次官方/高 star 库，先看依赖树	从源头避免引入"全家桶"
形态	多模块复用同一库时选 HSP 动态共享包	运行时只加载一份，避免重复打包
架构	abiFilters: ["arm64-v8a"]	砍掉多余 .so，体积与安装时间双降
符号	strip: true	Release 包体积可降 30%~50%
代码	按需 import 子模块，避免 import * as	打包器可 tree-shaking
依赖	overrides 统一版本 + ohpm ls 定期体检	消除多版本共存与冗余传递依赖

一句话概括：包体积不是上线前才想起的事，而是从选库那一刻就开始的持续治理。把上面六条固化成团队接入规范与发版检查项，包体增长就能被长期压住。

---

本文为原创首发实战笔记，基于 HarmonyOS 应用工程与 ohpm 依赖治理，代码示例为调用范式示意，实际接口以华为官方文档为准。