📚 课程目录第2章开发环境配置

2. 开发环境配置：Android Studio 版本要求、Gradle 插件、SDK Manager 配置动态交付支持

动态交付（Split Install）依赖构建工具链和运行时库的完整配合。任何一层组件的版本缺失或错配都会导致构建失败、运行时崩溃或功能静默失效。本章从 IDE、构建系统、依赖库、清单声明到 Gradle 配置，逐层拆解环境要求与配置步骤，确保后续所有动态功能模块的开发和调试有一个可复现的基线环境。

2.1 Android Studio 版本要求

Android Studio 4.0（API 30）是支持动态交付特性的最低 IDE 版本。从 4.0 起，IDE 内置了动态功能模块的项目模板和构建检查。低于此版本的 Studio 无法识别 com.android.dynamic-feature 插件，也不会在模块创建向导中提供动态功能模块选项。

2.2 组件版本最低要求

下表列出动态交付各依赖组件的最低版本与推荐版本。生产项目应优先使用推荐版本以获得最新的 bug 修复和 API 改进。

配置组件	最低版本	推荐版本	说明
Android Studio	4.0 (API 30)	Hedgehog (2023.1.1)	IDE 基础支持与模块模板
Gradle	6.5	7.4	构建系统版本
Android Gradle Plugin	4.1.0	7.4.0	提供 dynamic-feature 插件
Play Core Library	1.8.0	2.0.0+	SplitInstall API 运行时
compileSdkVersion	29	33+	编译 SDK 版本

版本匹配提示：AGP 与 Gradle 存在严格的版本对应关系。例如 AGP 7.4.0 要求 Gradle ≥ 7.4；AGP 8.0+ 要求 Gradle ≥ 8.0。升级任一组件时需同步检查另一组件的兼容性，否则构建会直接报错。

2.3 Gradle 插件与构建配置

在项目级 build.gradle 中声明 AGP 插件版本，并在每个动态功能模块中使用 com.android.dynamic-feature 插件。

2.3.1 项目级 build.gradle

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.0'
    }
}

2.3.2 模块级 build.gradle（app 主模块）

android {
    compileSdk 33
    dynamicFeatures = [':feature_a', ':feature_b']
}

2.3.3 动态功能模块 build.gradle

plugins {
    id 'com.android.dynamic-feature'
}
android {
    compileSdk 33
}

插件名称硬规则：动态功能模块必须使用 com.android.dynamic-feature 插件，不能使用 com.android.application 或 com.android.library。使用错误的插件会导致 Missing dynamic feature 构建错误。

2.4 SDK Manager 配置 Play Core 依赖

通过 SDK Manager 或直接在模块的 build.gradle 中添加 Play Core 依赖。推荐使用 Gradle 依赖声明方式，避免手动下载 SDK。

2.4.1 在 app 主模块中添加依赖

dependencies {
    implementation 'com.google.android.play:core:2.0.0'
    implementation 'com.google.android.play:core-ktx:2.0.0'  // Kotlin 扩展
}

2.4.2 在动态功能模块中添加依赖

dependencies {
    implementation project(':app')
}

动态功能模块自动继承 :app 模块的依赖，因此 Play Core 只需在主模块声明一次。如果功能模块有独立的第三方依赖，需在此单独声明。

2.5 AndroidManifest 清单声明

在主模块的 AndroidManifest.xml 中必须添加以下 <meta-data>，用于通知 Play Core 运行时该应用支持 Split Install。

<application>
    <meta-data
        android:name="com.google.android.play.core.splitinstall.support"
        android:value="true" />
</application>

清单配置注意：该 meta-data 必须放置在 <application> 元素内部，且 android:name 不能拼写错误。缺少此声明时，SplitInstallManager 的 startInstall() 会静默失败，不抛异常也不触发任何回调。

2.6 settings.gradle 注册动态功能模块

在项目根 settings.gradle 中需包含所有动态功能模块的路径，否则 Gradle 无法识别模块。

include ':app'
include ':feature_a'
include ':feature_b'

2.7 环境配置验证清单

完成上述配置后，按以下步骤验证环境是否正确。

Sync 项目：Gradle Sync 无报错，IDE 不提示“Plugin not found”或“Module not registered”。
检查模块图标：动态功能模块在 Android Studio 的 Project 面板中显示为 📦 (dynamic-feature) 图标。
构建 APK：执行 ./gradlew :app:assembleRelease，观察控制台输出 BUILD SUCCESSFUL。
检查输出产物：在 build/outputs/apk/release/ 中查看是否生成了 .apks 或 .apk 文件，且 --dynamic-feature 列表中包含已声明的功能模块。
运行时验证：安装 APK 后调用 SplitInstallManager.getInstalledModules()，确认默认只返回主模块名称。

配置要点总结：
Android Studio ≥ 4.0 + AGP 7.4.0 + Gradle 7.4 是经过广泛验证的稳定组合。
Play Core 2.0.0 及以上版本提供了 Kotlin 协程扩展，推荐升级。
dynamicFeatures 数组、dynamic-feature 插件、清单 meta-data 三者缺一不可。
每次修改配置后执行 File > Sync Project with Gradle Files，避免缓存导致的问题。

2.8 常见环境问题与快速定位

错误现象	根因	解决方案
Gradle Sync 报 “Plugin with id 'com.android.dynamic-feature' not found”	AGP 版本低于 4.1.0 或 Gradle 版本低于 6.5	升级 AGP 和 Gradle 至最低要求版本
构建成功但运行时 SplitInstallManager 返回空列表	AndroidManifest 未声明 `splitinstall.support`	添加 meta-data 并重新安装应用
模块构建报 “Cannot configure the 'dynamicFeatures' property”	app 模块的 build.gradle 中未声明 `dynamicFeatures`	在 app 模块的 android 闭包中添加 `dynamicFeatures = [...]`
Play Core API 调用时 ClassNotFoundException	Play Core 依赖未添加或版本过低	在主模块 dependencies 中添加 `implementation 'com.google.android.play:core:2.0.0'`

环境配置完成后，即可进入第 3 章正式创建动态功能模块并编写 Split Install 集成代码。所有配置示例均可在课程配套的 sample 仓库 split-install-starter 中找到完整副本。