HarmonyOS开发：动态加载与按需加载模块

📌 核心要点：深入理解HarmonyOS动态加载机制，掌握HSP动态加载与Feature模块按需加载策略，通过路由配置与错误处理实现模块的灵活按需加载。

一、背景与动机

想象一下：你的应用有10个功能模块，但用户打开应用时通常只用到其中2-3个。如果把所有模块都打包进主HAP，用户需要下载一个臃肿的安装包，启动时还要加载一堆暂时用不到的代码和资源——这合理吗？

显然不合理。这就像搬家时把所有季节的衣服都塞进行李箱，明明只去三天却带了一个月的量。按需加载的思路很简单：用到什么加载什么，不用的时候不占空间。

HarmonyOS提供了两种主要的动态加载机制：

• HSP（HarmonyOS Shared Package）动态加载：将共享代码抽取为独立的动态库，运行时按需加载
• Feature模块按需加载：将非核心功能拆分为独立的Feature模块，安装时按需下载

这两种机制各有适用场景。HSP适合"代码共享"——多个模块引用同一套公共代码；Feature适合"功能拆分"——将独立的功能模块延迟加载。

但动态加载不是"拆了就行"的——模块边界怎么划分？路由怎么配置？加载失败怎么办？这些问题如果处理不好，动态加载反而会增加复杂度和出错概率。本文将从原理到实战，帮你系统掌握HarmonyOS的动态加载技术。

二、核心原理

2.1 动态加载的三种模式

flowchart TB
    A[HarmonyOS动态加载] --> B[HSP动态共享包]
    A --> C[Feature按需安装]
    A --> D[动态import加载]
    
    B --> B1[编译时链接<br/>运行时加载]
    B --> B2[多模块共享代码]
    B --> B3[版本统一管理]
    
    C --> C1[应用市场分发]
    C --> C2[安装时按需下载]
    C --> C3[独立更新]
    
    D --> D1[代码级按需加载]
    D --> D2[运行时决定加载]
    D --> D3[最细粒度控制]
    
    B1 --> E[✅ 适合: 公共工具库<br/>UI组件库]
    C1 --> F[✅ 适合: 独立功能模块<br/>如支付/地图/AR]
    D1 --> G[✅ 适合: 条件性功能<br/>如VIP特权/实验功能]
    
    classDef mainStyle fill:#E74C3C,stroke:#C0392B,color:#fff,font-weight:bold
    classDef hspStyle fill:#3498DB,stroke:#2980B9,color:#fff
    classDef featureStyle fill:#2ECC71,stroke:#27AE60,color:#fff
    classDef importStyle fill:#F39C12,stroke:#E67E22,color:#fff
    classDef recommendStyle fill:#9B59B6,stroke:#8E44AD,color:#fff
    
    class A mainStyle
    class B,B1,B2,B3 hspStyle
    class C,C1,C2,C3 featureStyle
    class D,D1,D2,D3 importStyle
    class E,F,G recommendStyle

2.2 HSP动态加载流程

flowchart LR
    A[主模块启动] --> B[加载HSP元数据]
    B --> C{HSP是否已安装?}
    C -->|是| D[加载HSP字节码]
    C -->|否| E[触发HSP安装]
    E --> F{安装是否成功?}
    F -->|是| D
    F -->|否| G[降级处理]
    D --> H[解析导出接口]
    H --> I[调用HSP功能]
    
    classDef startStyle fill:#E74C3C,stroke:#C0392B,color:#fff,font-weight:bold
    classDef processStyle fill:#3498DB,stroke:#2980B9,color:#fff
    classDef decisionStyle fill:#F39C12,stroke:#E67E22,color:#fff,font-weight:bold
    classDef errorStyle fill:#95A5A6,stroke:#7F8C8D,color:#fff
    classDef successStyle fill:#2ECC71,stroke:#27AE60,color:#fff
    
    class A startStyle
    class B,D,H,I processStyle
    class C,F decisionStyle
    class E processStyle
    class G errorStyle

2.3 模块加载对比

三、代码实战

3.1 基础示例：HSP动态加载模块

// HSP模块: library/src/main/ets/Index.ets
// 定义HSP对外暴露的接口

// 用户服务接口
export class UserService {
  private static instance: UserService | null = null

  static getInstance(): UserService {
    if (!UserService.instance) {
      UserService.instance = new UserService()
    }
    return UserService.instance
  }

  // 获取用户信息
  getUserInfo(userId: string): UserInfo {
    // 实际实现会从网络或本地缓存获取
    return {
      userId: userId,
      userName: '张三',
      avatar: 'https://example.com/avatar.png',
      level: 5
    }
  }

  // 更新用户昵称
  updateNickname(userId: string, nickname: string): boolean {
    console.info(`更新用户昵称: ${userId} -> ${nickname}`)
    return true
  }
}

// 用户信息数据类
export interface UserInfo {
  userId: string
  userName: string
  avatar: string
  level: number
}

// 网络请求工具
export class NetworkHelper {
  // 发送GET请求
  static async get(url: string): Promise<string> {
    const http = await import('@ohos.net.http')
    const httpRequest = http.createHttp()
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.GET
    })
    httpRequest.destroy()
    return response.result as string
  }

  // 发送POST请求
  static async post(url: string, data: Object): Promise<string> {
    const http = await import('@ohos.net.http')
    const httpRequest = http.createHttp()
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.POST,
      extraData: data
    })
    httpRequest.destroy()
    return response.result as string
  }
}

// 日期格式化工具
export function formatDate(timestamp: number, format: string = 'YYYY-MM-DD'): string {
  const date = new Date(timestamp)
  const year = date.getFullYear()
  const month = String(date.getMonth() + 1).padStart(2, '0')
  const day = String(date.getDate()).padStart(2, '0')
  const hours = String(date.getHours()).padStart(2, '0')
  const minutes = String(date.getMinutes()).padStart(2, '0')

  return format
    .replace('YYYY', String(year))
    .replace('MM', month)
    .replace('DD', day)
    .replace('HH', hours)
    .replace('mm', minutes)
}

// 主模块: entry/src/main/ets/pages/Index.ets
// 动态加载HSP模块

import { UserService, UserInfo, NetworkHelper, formatDate } from '@ohos/library'

@Entry
@Component
struct IndexPage {
  @State userInfo: UserInfo | null = null
  @State isLoading: boolean = false
  @State loadError: string = ''

  build() {
    Column() {
      // 标题栏
      Text('动态加载示例')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      // 加载状态
      if (this.isLoading) {
        LoadingProgress()
          .width(40)
          .height(40)
          .color(Color.Blue)
        Text('加载中...')
          .fontSize(14)
          .fontColor('#999999')
          .margin({ top: 10 })
      }

      // 错误提示
      if (this.loadError) {
        Text(`加载失败: ${this.loadError}`)
          .fontSize(14)
          .fontColor(Color.Red)
          .margin({ top: 10 })
      }

      // 用户信息展示
      if (this.userInfo) {
        this.UserInfoCard()
      }

      // 操作按钮
      Button('加载用户信息')
        .width('80%')
        .height(44)
        .backgroundColor('#007DFF')
        .borderRadius(22)
        .onClick(() => this.loadUserInfo())
        .margin({ top: 20 })

      Button('发送网络请求')
        .width('80%')
        .height(44)
        .backgroundColor('#4CAF50')
        .borderRadius(22)
        .onClick(() => this.sendNetworkRequest())
        .margin({ top: 10 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .padding(20)
  }

  // 用户信息卡片
  @Builder
  UserInfoCard() {
    Column() {
      Row() {
        Text('用户名: ')
          .fontSize(16)
          .fontColor('#666666')
        Text(this.userInfo!.userName)
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
      .margin({ bottom: 8 })

      Row() {
        Text('等级: ')
          .fontSize(16)
          .fontColor('#666666')
        Text(`Lv.${this.userInfo!.level}`)
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
          .fontColor('#FF9800')
      }
      .width('100%')
      .margin({ bottom: 8 })

      Row() {
        Text('更新时间: ')
          .fontSize(14)
          .fontColor('#999999')
        Text(formatDate(Date.now(), 'YYYY-MM-DD HH:mm'))
          .fontSize(14)
          .fontColor('#999999')
      }
      .width('100%')
    }
    .width('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
    .borderRadius(12)
  }

  // 加载用户信息（使用HSP模块）
  private async loadUserInfo(): Promise<void> {
    this.isLoading = true
    this.loadError = ''

    try {
      // 直接使用HSP模块导出的UserService
      const userService = UserService.getInstance()
      this.userInfo = userService.getUserInfo('user_001')
    } catch (error) {
      this.loadError = `HSP加载失败: ${error}`
    } finally {
      this.isLoading = false
    }
  }

  // 发送网络请求（使用HSP模块的NetworkHelper）
  private async sendNetworkRequest(): Promise<void> {
    try {
      const result = await NetworkHelper.get('https://api.example.com/data')
      console.info('网络请求结果:', result)
    } catch (error) {
      console.error('网络请求失败:', error)
    }
  }
}

3.2 进阶示例：Feature模块按需加载与路由配置

// route_manager.ets - 动态路由与Feature模块管理
import { router } from '@kit.ArkUI'
import { abilityAccessCtrl, bundleManager } from '@kit.AbilityKit'

// 路由配置项
interface RouteConfig {
  path: string                // 路由路径
  module: string              // 所属模块
  pageSrc: string             // 页面源码路径
  needAuth: boolean           // 是否需要登录
  preload: boolean            // 是否预加载
  fallbackPath: string        // 加载失败时的回退页面
}

// 模块加载状态
type ModuleLoadStatus = 'not_loaded' | 'loading' | 'loaded' | 'error'

// 模块信息
interface ModuleInfo {
  name: string                // 模块名称
  status: ModuleLoadStatus    // 加载状态
  loadTime: number            // 加载耗时（毫秒）
  error?: string              // 错误信息
}

// 动态路由管理器
class DynamicRouteManager {
  private routeMap: Map<string, RouteConfig> = new Map()
  private moduleStatusMap: Map<string, ModuleInfo> = new Map()
  private preloadedModules: Set<string> = new Set()

  // 注册路由
  registerRoute(config: RouteConfig): void {
    this.routeMap.set(config.path, config)
    this.moduleStatusMap.set(config.module, {
      name: config.module,
      status: 'not_loaded',
      loadTime: 0
    })
  }

  // 批量注册路由
  registerRoutes(configs: RouteConfig[]): void {
    for (const config of configs) {
      this.registerRoute(config)
    }
  }

  // 导航到指定路由
  async navigateTo(path: string, params?: Record<string, Object>): Promise<void> {
    const config = this.routeMap.get(path)
    if (!config) {
      console.error(`路由不存在: ${path}`)
      return
    }

    // 检查登录状态
    if (config.needAuth && !this.isUserLoggedIn()) {
      // 跳转到登录页
      router.pushUrl({ url: '/pages/LoginPage' })
      return
    }

    // 更新模块状态
    const moduleInfo = this.moduleStatusMap.get(config.module)!
    moduleInfo.status = 'loading'
    const startTime = Date.now()

    try {
      // 尝试导航到目标页面
      await router.pushUrl({
        url: config.pageSrc,
        params: params || {}
      })

      // 更新状态
      moduleInfo.status = 'loaded'
      moduleInfo.loadTime = Date.now() - startTime
    } catch (error) {
      // 加载失败，尝试回退页面
      moduleInfo.status = 'error'
      moduleInfo.error = String(error)
      console.error(`模块加载失败: ${config.module}`, error)

      // 导航到回退页面
      if (config.fallbackPath) {
        try {
          await router.pushUrl({ url: config.fallbackPath })
        } catch (fallbackError) {
          console.error('回退页面也加载失败:', fallbackError)
        }
      }
    }
  }

  // 预加载模块
  async preloadModule(moduleName: string): Promise<void> {
    if (this.preloadedModules.has(moduleName)) {
      return  // 已经预加载过
    }

    const moduleInfo = this.moduleStatusMap.get(moduleName)
    if (!moduleInfo || moduleInfo.status === 'loaded') {
      return
    }

    try {
      // 使用动态import预加载模块
      await import(`../${moduleName}/Index`)
      moduleInfo.status = 'loaded'
      this.preloadedModules.add(moduleName)
      console.info(`模块预加载成功: ${moduleName}`)
    } catch (error) {
      console.warn(`模块预加载失败: ${moduleName}`, error)
    }
  }

  // 批量预加载
  async preloadModules(moduleNames: string[]): Promise<void> {
    const promises = moduleNames.map(name => this.preloadModule(name))
    await Promise.allSettled(promises)
  }

  // 预加载标记了preload的路由
  async preloadMarkedRoutes(): Promise<void> {
    const preloadModules: string[] = []
    this.routeMap.forEach((config) => {
      if (config.preload) {
        preloadModules.push(config.module)
      }
    })
    await this.preloadModules(preloadModules)
  }

  // 检查Feature模块是否已安装
  async isFeatureInstalled(moduleName: string): Promise<boolean> {
    try {
      const bundleInfo = await bundleManager.getBundleInfoForSelf(
        bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_HAP_MODULE
      )
      return bundleInfo.hapModuleInfos.some(
        module => module.name === moduleName
      )
    } catch (error) {
      return false
    }
  }

  // 获取模块加载状态
  getModuleStatus(moduleName: string): ModuleInfo | undefined {
    return this.moduleStatusMap.get(moduleName)
  }

  // 获取所有模块状态
  getAllModuleStatus(): ModuleInfo[] {
    return Array.from(this.moduleStatusMap.values())
  }

  // 检查用户登录状态（简化实现）
  private isUserLoggedIn(): boolean {
    // 实际应从全局状态或本地存储获取
    return AppStorage.get<boolean>('isLoggedIn') || false
  }
}

// 全局路由管理器实例
const routeManager = new DynamicRouteManager()

// 初始化路由配置
function initRoutes(): void {
  routeManager.registerRoutes([
    {
      path: '/home',
      module: 'entry',
      pageSrc: 'pages/HomePage',
      needAuth: false,
      preload: true,
      fallbackPath: 'pages/ErrorPage'
    },
    {
      path: '/profile',
      module: 'entry',
      pageSrc: 'pages/ProfilePage',
      needAuth: true,
      preload: false,
      fallbackPath: 'pages/LoginPage'
    },
    {
      path: '/payment',
      module: 'feature_payment',
      pageSrc: 'pages/PaymentPage',
      needAuth: true,
      preload: false,
      fallbackPath: 'pages/PaymentUnavailablePage'
    },
    {
      path: '/map',
      module: 'feature_map',
      pageSrc: 'pages/MapPage',
      needAuth: false,
      preload: false,
      fallbackPath: 'pages/MapUnavailablePage'
    },
    {
      path: '/ar',
      module: 'feature_ar',
      pageSrc: 'pages/ArPage',
      needAuth: false,
      preload: false,
      fallbackPath: 'pages/ArUnavailablePage'
    }
  ])
}

3.3 完整示例：动态加载错误处理与降级方案

// dynamic_loader.ets - 动态加载错误处理与降级方案
import { router } from '@kit.ArkUI'

// 加载结果
interface LoadResult<T> {
  success: boolean
  data?: T
  error?: DynamicLoadError
  fallbackUsed: boolean
}

// 动态加载错误类型
enum DynamicLoadErrorType {
  MODULE_NOT_FOUND = 'MODULE_NOT_FOUND',       // 模块不存在
  MODULE_LOAD_FAILED = 'MODULE_LOAD_FAILED',   // 模块加载失败
  MODULE_TIMEOUT = 'MODULE_TIMEOUT',           // 加载超时
  MODULE_VERSION_MISMATCH = 'MODULE_VERSION_MISMATCH', // 版本不匹配
  NETWORK_ERROR = 'NETWORK_ERROR'              // 网络错误
}

// 动态加载错误
interface DynamicLoadError {
  type: DynamicLoadErrorType
  message: string
  moduleName: string
  timestamp: number
  retryable: boolean
}

// 降级策略
interface FallbackStrategy {
  showPlaceholder: boolean      // 显示占位界面
  showOfflineTip: boolean       // 显示离线提示
  retryCount: number            // 重试次数
  retryDelay: number            // 重试间隔（毫秒）
  fallbackComponent?: string    // 降级组件名称
}

// 动态加载器
class DynamicModuleLoader {
  private loadCache: Map<string, Object> = new Map()
  private loadingPromises: Map<string, Promise<Object>> = new Map()
  private errorLog: DynamicLoadError[] = []
  private defaultTimeout: number = 10000  // 默认超时10秒

  // 加载模块
  async loadModule<T>(moduleName: string, strategy?: FallbackStrategy): Promise<LoadResult<T>> {
    const fallbackStrategy = strategy || this.getDefaultStrategy()

    // 检查缓存
    if (this.loadCache.has(moduleName)) {
      return {
        success: true,
        data: this.loadCache.get(moduleName) as T,
        fallbackUsed: false
      }
    }

    // 检查是否正在加载
    if (this.loadingPromises.has(moduleName)) {
      try {
        const data = await this.loadingPromises.get(moduleName) as T
        return { success: true, data, fallbackUsed: false }
      } catch (error) {
        return this.handleLoadError(moduleName, error, fallbackStrategy)
      }
    }

    // 开始加载
    const loadPromise = this.executeLoad(moduleName)
    this.loadingPromises.set(moduleName, loadPromise)

    try {
      const data = await this.withTimeout(loadPromise, this.defaultTimeout) as T
      this.loadCache.set(moduleName, data)
      this.loadingPromises.delete(moduleName)
      return { success: true, data, fallbackUsed: false }
    } catch (error) {
      this.loadingPromises.delete(moduleName)
      return this.handleLoadError(moduleName, error, fallbackStrategy)
    }
  }

  // 执行模块加载
  private async executeLoad(moduleName: string): Promise<Object> {
    try {
      // 使用动态import加载模块
      const module = await import(`../${moduleName}/Index`)
      console.info(`模块加载成功: ${moduleName}`)
      return module
    } catch (error) {
      const loadError: DynamicLoadError = {
        type: DynamicLoadErrorType.MODULE_LOAD_FAILED,
        message: `模块加载失败: ${moduleName}`,
        moduleName: moduleName,
        timestamp: Date.now(),
        retryable: true
      }
      this.errorLog.push(loadError)
      throw loadError
    }
  }

  // 处理加载错误
  private async handleLoadError<T>(
    moduleName: string,
    error: Object,
    strategy: FallbackStrategy
  ): Promise<LoadResult<T>> {
    const loadError = error as DynamicLoadError
    console.error(`模块加载失败: ${moduleName}`, loadError)

    // 尝试重试
    if (loadError.retryable && strategy.retryCount > 0) {
      for (let i = 0; i < strategy.retryCount; i++) {
        console.info(`重试加载模块: ${moduleName} (${i + 1}/${strategy.retryCount})`)
        await this.delay(strategy.retryDelay)

        try {
          const data = await this.executeLoad(moduleName) as T
          this.loadCache.set(moduleName, data)
          return { success: true, data, fallbackUsed: false }
        } catch (retryError) {
          continue
        }
      }
    }

    // 重试失败，使用降级方案
    return {
      success: false,
      error: loadError,
      fallbackUsed: true
    }
  }

  // 带超时的Promise
  private withTimeout<T>(promise: Promise<T>, timeout: number): Promise<T> {
    return new Promise<T>((resolve, reject) => {
      const timer = setTimeout(() => {
        reject({
          type: DynamicLoadErrorType.MODULE_TIMEOUT,
          message: `模块加载超时: ${timeout}ms`,
          moduleName: '',
          timestamp: Date.now(),
          retryable: true
        } as DynamicLoadError)
      }, timeout)

      promise
        .then(data => {
          clearTimeout(timer)
          resolve(data)
        })
        .catch(error => {
          clearTimeout(timer)
          reject(error)
        })
    })
  }

  // 获取默认降级策略
  private getDefaultStrategy(): FallbackStrategy {
    return {
      showPlaceholder: true,
      showOfflineTip: true,
      retryCount: 2,
      retryDelay: 1000,
      fallbackComponent: 'FallbackPlaceholder'
    }
  }

  // 延迟
  private delay(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms))
  }

  // 获取错误日志
  getErrorLog(): DynamicLoadError[] {
    return [...this.errorLog]
  }

  // 清除缓存
  clearCache(moduleName?: string): void {
    if (moduleName) {
      this.loadCache.delete(moduleName)
    } else {
      this.loadCache.clear()
    }
  }
}

// 全局加载器实例
const dynamicLoader = new DynamicModuleLoader()

// 在页面中使用动态加载
@Entry
@Component
struct DynamicPageDemo {
  @State moduleLoaded: boolean = false
  @State loadError: string = ''
  @State showFallback: boolean = false

  // 降级占位组件
  @Builder
  FallbackPlaceholder() {
    Column() {
      Image($r('app.media.ic_module_unavailable'))
        .width(80)
        .height(80)
        .opacity(0.5)

      Text('该功能暂不可用')
        .fontSize(16)
        .fontColor('#999999')
        .margin({ top: 16 })

      Text('请检查网络连接或稍后重试')
        .fontSize(14)
        .fontColor('#CCCCCC')
        .margin({ top: 8 })

      Button('重试')
        .width(120)
        .height(36)
        .fontSize(14)
        .backgroundColor('#007DFF')
        .borderRadius(18)
        .margin({ top: 20 })
        .onClick(() => this.retryLoad())
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }

  build() {
    Column() {
      if (this.showFallback) {
        // 降级界面
        this.FallbackPlaceholder()
      } else if (this.moduleLoaded) {
        // 正常内容
        Text('模块加载成功')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
      } else {
        // 加载中
        LoadingProgress()
          .width(40)
          .height(40)
          .color(Color.Blue)
      }
    }
    .width('100%')
    .height('100%')
  }

  // 加载模块
  async loadFeatureModule(): Promise<void> {
    const result = await dynamicLoader.loadModule('feature_payment', {
      showPlaceholder: true,
      showOfflineTip: true,
      retryCount: 3,
      retryDelay: 1500,
      fallbackComponent: 'FallbackPlaceholder'
    })

    if (result.success) {
      this.moduleLoaded = true
      this.showFallback = false
    } else {
      this.showFallback = true
      this.loadError = result.error?.message || '未知错误'
    }
  }

  // 重试加载
  private async retryLoad(): Promise<void> {
    this.showFallback = false
    dynamicLoader.clearCache('feature_payment')
    await this.loadFeatureModule()
  }
}

四、踩坑与注意事项

坑点1：HSP模块的循环依赖

HSP模块之间如果存在循环依赖（A依赖B，B又依赖A），编译时不会报错，但运行时可能出现初始化顺序问题——A初始化时需要B的实例，但B还没初始化完成。HSP模块的依赖关系必须是单向的DAG（有向无环图），在设计模块架构时就要避免循环依赖。

坑点2：Feature模块的安装状态判断不准确

bundleManager.getBundleInfoForSelf()返回的模块信息可能存在缓存延迟——用户刚安装了Feature模块，但API返回的信息还是旧数据。建议在安装Feature模块后，延迟500ms再查询安装状态，或者通过应用内的状态管理来追踪安装结果。

坑点3：动态import的路径解析问题

动态import的路径是相对于当前文件的，而不是相对于项目根目录。如果你的代码文件在不同层级的目录中，同样的import('../module/Index')可能指向不同的路径。建议使用绝对路径别名（如@ohos/library）而非相对路径，确保路径解析的一致性。

坑点4：HSP模块版本不一致

主模块和HSP模块的版本必须兼容。如果主模块升级了但HSP模块没有同步升级，可能出现接口不匹配的问题。在HSP的package.json中明确声明版本范围，并在运行时检查版本兼容性。

坑点5：动态加载的模块无法使用主模块的上下文

通过动态import加载的模块无法直接访问主模块的UI上下文（Context）。如果HSP模块需要使用资源、文件路径等功能，必须通过参数显式传递Context。HSP模块的初始化方法应该接受Context参数，而不是假设Context可用。

坑点6：Feature模块的签名必须与主模块一致

Feature模块和主模块必须使用相同的签名证书，否则安装会失败。这在多团队协作开发时特别容易出问题——A团队用测试证书签名了Feature模块，但主模块用的是正式证书。确保CI/CD流水线中所有模块使用统一的签名配置。

坑点7：动态加载的超时设置不合理

如果动态加载的超时时间设置太短（如1秒），在网络较差时容易误判为加载失败；设置太长（如30秒），又会影响用户体验。建议超时时间设置为5-10秒，并配合加载进度提示和重试机制。

五、HarmonyOS 6适配说明

API差异表

行为变更

1. HSP预加载机制：HarmonyOS 6新增了HSP预加载API，可以在应用启动时预先加载即将使用的HSP模块，减少首次访问的等待时间。

2. Feature模块应用内安装：新增@ohos.bundle.installer模块，允许应用在运行时触发Feature模块的安装，无需跳转到应用市场。

3. 动态import类型安全：动态import现在支持在编译时进行类型检查，避免了运行时才发现导入模块类型不匹配的问题。

适配代码

// HarmonyOS 6 HSP预加载示例
import { hspManager } from '@ohos.ability.hspManager'

// 应用启动时预加载HSP模块
async function preloadHspModules(): Promise<void> {
  const modulesToPreload = [
    '@ohos/library_user',
    '@ohos/library_network',
    '@ohos/library_ui'
  ]

  for (const moduleName of modulesToPreload) {
    try {
      // HarmonyOS 6新增：HSP预加载
      await hspManager.preloadHsp(moduleName)
      console.info(`HSP预加载成功: ${moduleName}`)
    } catch (error) {
      console.warn(`HSP预加载失败: ${moduleName}`, error)
    }
  }
}

// HarmonyOS 6 Feature模块应用内安装
import { installer } from '@ohos.bundle.installer'

async function installFeatureModule(modulePath: string): Promise<boolean> {
  try {
    const bundleInstaller = installer.getBundleInstaller()
    
    await new Promise<void>((resolve, reject) => {
      bundleInstaller.install([modulePath], {
        userId: 100,
        installFlag: 1,
        isKeepData: false
      }, (err, data) => {
        if (err) {
          reject(err)
        } else {
          resolve()
        }
      })
    })
    
    console.info('Feature模块安装成功')
    return true
  } catch (error) {
    console.error('Feature模块安装失败:', error)
    return false
  }
}

六、总结

三维度评价表

动态加载是包体积优化的"终极武器"——它不减少代码总量，而是将代码的加载时机推迟到真正需要的时候。但动态加载也带来了额外的复杂度：模块边界划分、路由配置、错误处理、降级方案……每一个环节都需要精心设计。动态加载不是银弹，而是权衡的艺术——在包体积和复杂度之间找到最佳平衡点。