第4章 模块定义与Gradle配置：动态功能模块 & dist:install-time vs on-demand

动态交付的核心是「按需下载运行，而非安装时打包」。Android 通过 Split Install API 和 Gradle 动态功能模块 实现这一目标。本章从模块定义出发，深入 dist:install-time 与 dist:on-demand 的机制差异，并给出完整配置示例与调试方法。

4.1 动态功能模块的结构

每个动态功能模块是一个独立的 Gradle module，其 build.gradle 中仅需声明 com.android.dynamic-feature 插件，并定义模块名称与分发类型。

模块内文件结构与普通 com.android.library 一致，可包含资源、AndroidManifest.xml、res、src 等。关键区别在于 AndroidManifest.xml 中必须配置 dist:module 属性。

4.2 dist:install-time 与 dist:on-demand 深度对比

4.3 Gradle 配置完整示例

以下展示 base module 与动态功能模块的 build.gradle 协作配置（Kotlin DSL 格式）。

4.3.1 Base module (app/build.gradle.kts)

plugins {
    id("com.android.application")
}

android {
    compileSdk = 34
    defaultConfig {
        applicationId = "com.example.dynamicdemo"
        minSdk = 21
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    // 启用动态功能
    dynamicFeatures = setOf(":feature_ar", ":feature_pdf")
}

dependencies {
    implementation("androidx.appcompat:appcompat:1.6.1")
    // 不直接依赖动态模块，只依赖 play 部分
    implementation("com.google.android.play:feature-delivery:2.1.0")
}

4.3.2 On-demand 模块 (feature_ar/build.gradle.kts)

plugins {
    id("com.android.dynamic-feature")
}

android {
    compileSdk = 34
    namespace = "com.example.dynamicdemo.feature_ar"
}

dependencies {
    implementation(project(":app"))
    // 可添加该模块独有的依赖
    implementation("com.google.ar:core:1.38.0")
}

4.3.3 Install-time 模块 (feature_pdf/build.gradle.kts)

plugins {
    id("com.android.dynamic-feature")
}

android {
    compileSdk = 34
    namespace = "com.example.dynamicdemo.feature_pdf"
}

dependencies {
    implementation(project(":app"))
    implementation("com.itextpdf:itext7-core:7.2.5")
}

4.4 AndroidManifest.xml 中的分发属性

每个动态功能模块的 AndroidManifest.xml 必须包含 <dist:module> 元素，位于 <manifest> 根节点下，不嵌套在 <application> 内。

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:dist="http://schemas.android.com/apk/distribution"
    package="com.example.dynamicdemo.feature_ar">

    <dist:module
        dist:on-demand="true"
        dist:title="@string/feature_ar_title">
        <dist:delivery>
            <dist:install-time />
        </dist:delivery>
        <dist:fusing dist:include="true" />
    </dist:module>

    <application ... />
</manifest>

属性说明：

• dist:on-demand="true" 启用按需模式（与 dist:install-time="true" 互斥）
• <dist:install-time /> 内嵌在 <dist:delivery> 中，指示分发方式（可嵌套多个方式）
• dist:fusing 允许模块在旧设备（不支持 Split APK）时与 base 融合安装
• dist:title 为用户可见的模块名称（用于系统设置卸载时的标识）

4.5 构建与调试要点

1. 生成 Split APK：使用 ./gradlew bundle 或 Build > Build Bundle(s) / APK(s) > Build APK(s)，Android Studio 会自动为每个动态模块生成独立的 .apk 分片。
2. 本地测试：使用 Android Studio 的 “Run” 按钮默认仅部署 base + install-time 模块。要测试 on-demand 模块，需通过 SplitInstallManager API 或使用 bundletool 安装完整应用。
3. bundletool 命令示例：

java -jar bundletool.jar build-apks --bundle=app.aab --output=app.apks
java -jar bundletool.jar install-apks --apks=app.apks

4.6 常见配置错误与修复

4.7 性能与稳定性优化

• 按需模块大小控制：每个 on-demand 模块建议不超过 200 MB，避免下载超时。超过 512 MB 会被 Google Play 拒绝。
• 预加载策略：对高频 on-demand 模块，可在应用启动后通过 SplitInstallManager.deferredInstall() 提前下载到缓存区，提升用户体验。
• 错误处理：在 onError() 回调中捕获 SplitInstallErrorCode.ACTIVE_SESSIONS_LIMIT_EXCEEDED（同时下载会话不得超过 10 个）。
• 模块拆分粒度：避免将原子功能拆成多个模块，因为每次 on-demand 下载都有网络开销。建议按「用户场景」而非「技术组件」划分。

android {
    defaultConfig {
        resConfigs "en", "zh-rCN"
    }
    bundle {
        language {
            enableSplit = true
        }
        density {
            enableSplit = true
        }
    }
}

4.8 小结