📚 课程目录第4章主模块集成基础

主模块集成基础

主模块（Base Module）是应用发布的入口，所有功能模块必须通过主模块声明才能被 Play Core 识别。本章聚焦 app/build.gradle 的修改，覆盖 dynamicFeatures 声明、依赖管理 和 签署配置 三部分。

4.1 添加 dynamicFeatures 声明

在 android { } 块内使用 dynamicFeatures 数组列出所有功能模块的路径（与 settings.gradle 中的模块名保持一致）。

android {
    namespace "com.example.myapp"
    compileSdk 34

    // 列出所有功能模块
    dynamicFeatures = [":feature_video", ":feature_ar", ":feature_theme"]

    defaultConfig {
        applicationId "com.example.myapp"
        minSdk 21
        targetSdk 34
        versionCode 1
        versionName "1.0"
    }

    ...
}

路径格式：使用 : 前缀指向模块名，与 include ':feature_video' 一致；不要使用相对路径或路径。

所有功能模块的 namespace 建议与主模块不同，避免资源 ID 冲突。
如果功能模块不声明在 dynamicFeatures 中，SplitInstallManager 将无法找到该模块。
该数组支持空列表（dynamicFeatures = []）——适用于仅使用按需功能但不包含任何功能模块的场景。

4.2 依赖管理

主模块必须包含 Play Core（或 Feature Delivery）依赖 以及功能模块的引用。功能模块自身的依赖（如第三方库）应在各自 build.gradle 中声明，主模块无需重复。

场景	Gradle 配置	说明
基础 API	`implementation 'com.google.android.play:feature-delivery:2.1.0'`	提供 `SplitInstallManager`、`SplitInstallStateUpdatedListener` 等核心类
功能模块集成	`implementation project(':feature_video')`	必须与 `dynamicFeatures` 声明一致，确保构建时包含模块
共享代码/资源	`implementation project(':shared')`	主模块与功能模块共用的基础库，避免重复打包
注解处理（可选）	`annotationProcessor 'com.google.auto.service:auto-service:1.0-rc7'`	用于自动生成模块注册表（配合 `@AutoService` 使用）

⚠ 依赖版本对齐：所有模块使用的 feature-delivery 版本必须一致，否则 Play Core 在运行时可能抛出 SplitCompatException。

// 主模块 build.gradle
dependencies {
    // 基础 API
    implementation 'com.google.android.play:feature-delivery:2.1.0'

    // 功能模块引用
    implementation project(':feature_video')
    implementation project(':feature_ar')

    // 共享基础库
    implementation project(':shared')

    // 可选注解处理器
    annotationProcessor 'com.google.auto.service:auto-service:1.0-rc7'
}

4.3 签署配置注意事项

所有功能模块必须使用与主模块 相同的签署证书（包括 keystore、密码、别名），否则 Play Core 会拒绝安装按需模块。

android {
    signingConfigs {
        release {
            storeFile file("deploy.keystore")
            storePassword System.getenv("KEYSTORE_PASS") ?: "local_dev_pass"
            keyAlias "myalias"
            keyPassword System.getenv("KEY_ALIAS_PASS") ?: "local_dev_alias_pass"
        }
    }

    buildTypes {
        release {
            // 强制使用统一签署
            signingConfig signingConfigs.release
        }
    }
}

调试环境：默认使用 Android SDK 提供的 debug 证书，所有模块自动共享该证书，无需额外配置。
发布环境：必须在 signingConfigs 中显式配置，且每个功能模块的 build.gradle 需引用相同的 keystore。
CI/CD：将 keystore 密码放在环境变量中，避免明文提交到源码仓库。

常见错误：如果安装按需模块时出现 INSTALL_FAILED_INVALID_APK 或 SELinux denied，首先检查功能模块的签署证书是否与主模块完全一致（包括证书序列号）。

4.4 调试与验证

完成配置后，通过以下步骤验证集成是否正确：

执行 ./gradlew :app:assembleDebug 构建主模块。
检查生成的 APK 是否包含功能模块 AAB 文件（位于 build/outputs/apk/debug/ 或 build/outputs/bundle/debug/）。
使用 adb install -t 安装，并调用 SplitInstallManager.startInstall() 测试安装请求。

# 验证功能模块是否被正确打包进 App Bundle
./gradlew :app:bundleDebug
ls build/outputs/bundle/debug/app-debug.aab

# 使用 bundletool 检查模块列表
java -jar bundletool.jar dump manifest --bundle=app-debug.aab

完成以上三步配置后，主模块即可支持动态功能模块的构建与安装。下一阶段将进入功能模块自身的声明与实现。