把一个大功能拆成 Feature HAP 或 HSP,在 module.json5 里写上 deliveryWithInstall: false,很多人到这里就以为“按需加载做完了”。安装包里确实没有这个模块了,但用户第一次触发这个功能时,代码要面对的是一个运行时才到达的模块:它可能还没下载、可能下载失败、可能正在安装,而且下载完成之后调用方不能直接 import 一个不存在的静态依赖。

deliveryWithInstall: false 只解决“首次安装不下载”这一步。真正让功能跑起来,需要三步:配置按需模块、运行时检查并按需拉取、拉取成功后动态加载。

模块配置和动态依赖

json5

// 按需 HSP 的 module.json5
{
  "type": "shared",
  "deliveryWithInstall": false,
  "pages": "$media:pages"
}

entry 的 oh-package.json5 里以动态依赖方式引用,不要在入口包里静态 import 按需模块的任何符号。静态依赖会迫使模块在构建期就被链接进去,deliveryWithInstall: false 就形同虚设。

运行时拉取的正确顺序

触发按需功能时,先查状态,再决定是否下载。不要直接调 fetchModules,也不要在下载回调里假设“成功了就能立刻 import”。

typescript

import { moduleInstallManager } from '@kit.AppGalleryKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function ensureModule(moduleName: string): Promise<boolean> {
  const installed = moduleInstallManager.getInstalledModule(moduleName);
  if (installed.installStatus === moduleInstallManager.InstallStatus.INSTALLED) {
    return true;
  }

  const request = moduleInstallManager.createModuleInstallRequest([moduleName]);
  return new Promise<boolean>((resolve) => {
    moduleInstallManager.fetchModules(request, (state) => {
      if (state.taskStatus === moduleInstallManager.TaskStatus.INSTALL_SUCCESSFUL) {
        hilog.info(0, 'HSP', `${moduleName} ready`);
        resolve(true);
      } else if (state.taskStatus === moduleInstallManager.TaskStatus.INSTALL_FAILED) {
        hilog.error(0, 'HSP', 'install failed');
        resolve(false);
      }
    });
  });
}

拉取成功之后,再用动态 import() 加载:

typescript

const mod = await import(sharedlib);
mod.helloFromHsp();

常见错误是在用户点击功能按钮的同一个同步调用栈里既 fetchModules 又 import,下载还没完成,import 必然抛模块不存在。另一个错误是忽略 fetchModules 的进度回调,界面卡在“加载中”没有任何反馈,用户以为功能坏了。把下载进度暴露出来——downloadedSize / totalSize——比一个转圈图标有用得多。

还有一个容易被低估的边界:元服务场景下总包体有明确上限,HSP 的按需加载和元服务的 10MB 约束是同时生效的。拆模块之前先算清楚哪些是“免安装必须”,哪些可以等用户用到再拉,不要为了拆而拆,把首屏依赖也拆出去,启动链路反而多了一次下载等待。

包体积优化的正确顺序是先砍冗余(ABI、无用资源),再消重复(HAR 换 HSP),最后才把低频大功能挪出安装包。按需加载是这条链路的最后一步,不是第一步。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐