📚 课程目录第2章环境与工具准备

2. 环境与工具准备

动态模块按需加载（SplitInstall）要求开发环境在底层构建工具、运行时库和SDK版本上严格对齐。任何版本错位都可能导致编译失败、运行时异常或动态模块无法下载。本章围绕版本选型、插件配置、依赖引入和常见故障排除展开，帮助你在一开始就建立正确的环境基线。

2.1 版本要求总览

下表列出推荐的最低版本与已充分测试的稳定版本，后续所有章节的示例均基于此配置。

组件	要求（最低）	推荐（已验证）	备注
Android Studio	4.0	2021.3 (Arctic Fox) 以上	内置 SplitInstall 向导
Android Gradle Plugin (AGP)	4.0.0	7.2.1	必须 ≥ 4.0
Gradle	6.1.1	7.4.2	与 AGP 版本匹配
Play Core（Java）	1.10.0	1.10.3	负责下载与安装逻辑
Play Core（Kotlin）	1.10.0	1.10.3	KTX 扩展包
Android SDK Platform	API 21	API 31	支持动态特性
Build Tools	30.0.2	33.0.0	用于 OBB 打包

版本陷阱：Play Core 1.11.0 以上版本移除了 SplitInstallManager 的部分同步 API，必须使用异步回调。本课程统一使用 1.10.3 以保证示例兼容。

2.2 Gradle 插件配置

在项目级 build.gradle 中声明 AGP 版本和 Google 服务插件（非必需，但建议用于 Play Integrity 校验）。

// 项目根目录 build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.2.1"
        // 可选：用于 Play Integrity 验证
        classpath "com.google.gms:google-services:4.3.13"
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

在模块级 build.gradle 中启用动态功能模块支持，并配置 assetPacks（如果使用）。

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'  // 可选
}

android {
    compileSdk 31
    defaultConfig {
        minSdk 21
        targetSdk 31
    }
    dynamicFeatures = [':feature_camera', ':feature_ar']
}

dependencies {
    implementation 'com.google.android.play:core:1.10.3'
    // 每个动态模块的 base 依赖
    implementation project(':base')
}

  关键配置：dynamicFeatures 列表中的每一项都对应一个独立的功能模块（feature module），这些模块在构建时会被打包为单独的 Split APK/App Bundle。如果不声明，SplitInstall 将找不到目标模块。

2.3 SDK 管理器下载与 Play Core 库依赖

通过 Android Studio → SDK Manager 安装以下平台和工具：

Android SDK Platform 31（目标 API）
Android SDK Build-Tools 33.0.0
NDK（仅当功能模块包含原生代码时）

Play Core 库通过 Gradle 依赖引入，无需手动下载。在 app/build.gradle 的 dependencies 块中添加：

dependencies {
    implementation "com.google.android.play:core:1.10.3"
    implementation "com.google.android.play:core-ktx:1.8.1"   // Kotlin 扩展（可选）
    // 如果需要使用 Deferred 下载，可额外引入
    implementation "com.google.android.play:core-common:2.0.2"
}

2.4 调试方法与验证

在开发阶段，SplitInstall 功能无法通过本地 APK 安装测试，必须借助以下两种方式验证：

内测分发：将 App Bundle 上传到 Google Play 控制台的内部测试轨道，通过测试链接安装。
本地模拟（推荐）：使用 bundletool 生成本地安装包并安装全部 Split APK。命令如下：

# 1. 从 App Bundle 提取所有 APK
bundletool build-apks --bundle=app-release.aab --output=app.apks --ks=keystore.jks --ks-key-alias=alias

# 2. 安装到设备（安装所有 split）
bundletool install-apks --apks=app.apks

安装后，在设备上运行以下 ADB 命令确认动态模块是否已就位：

adb shell pm list packages --show-split | grep com.example.app
# 输出示例：
# package:com.example.app
#   split:config.armeabi_v7a
#   split:feature_camera
#   split:feature_ar

如果 feature_camera 和 feature_ar 出现在列表中，说明环境配置正确，动态模块已随基础包一并安装。

2.5 常见错误处理

错误提示	原因	解决方案
`Dynamic feature module requires at least minSdk 21`	功能模块的 `minSdk` 高于 base	将所有 feature 模块 `minSdk` 设为 21
`Cannot find symbol class SplitInstallManager`	Play Core 依赖缺失或版本 < 1.10	检查 `build.gradle` 中 implementation 声明
`InstallException: -2 (ERROR_ACCESS_DENIED)`	运行时权限不足或 Play 商店版本太低	确保设备已登录 Google 账号且 Play 商店 ≥ 18.0
`Gradle sync failed: Could not find com.android.tools.build:gradle:7.2.1`	未添加 google() 仓库或网络限制	在 `settings.gradle` 中显式添加 `google()` 仓库

调试捷径：在 Android Studio 的 Logcat 中过滤 SplitInstall 或 PlayCore，可以实时看到下载、安装的状态日志，快速定位网络或存储问题。

2.6 性能与稳定性优化建议

统一 Play Core 版本：base 模块与所有 feature 模块中的 implementation 版本必须一致，否则类冲突会导致 ClassNotFoundException。
减少 feature 模块的体积：尽量使用 assetPacks 存放大型资源，避免在动态模块中嵌入过多 native so 库。
预加载缓存模式：在 Application.onCreate() 中提前初始化 SplitInstallManager 单例，避免首次调用时触发类加载延迟。
Gradle 构建缓存：开启 org.gradle.caching=true，多次构建 feature 模块时可节省 50% 以上的编译时间。