📚 课程目录第3章 PlayCore依赖配置

第3章 PlayCore依赖配置：Gradle引入、版本选择、最低SDK要求

PlayCore库是Google Play动态交付功能的客户端SDK，负责与Play商店通信、管理拆分APK的下载与安装。正确配置Gradle依赖是使用SplitInstallManager的前提。本章讲解依赖声明方式、版本选择策略以及最低SDK约束，并给出可复用的配置模板。

3.1 库定位与版本演进

PlayCore库托管于Google's Maven仓库（maven.google.com），包名为com.google.android.play:core。从1.8.0版起，动态交付API趋于稳定；1.10.0版后新增SplitInstallManagerFactory等便捷入口。建议始终使用当前最新稳定版，避免使用-alpha或-beta后缀版本用于生产环境。

版本	发布日期	最低API	动态交付支持	建议
1.10.3	2023-03	API 14	✅ 完整	推荐用于新项目
1.9.1	2022-06	API 14	✅ 完整	可选，但建议升级
1.8.2	2021-11	API 14	✅ 基本	不再维护
1.7.3	2020-08	API 14	⚠️ 部分	不推荐

版本锁定策略：在build.gradle中使用implementation "com.google.android.play:core:1.10.3"固定版本，避免因自动升级引入破坏性变更。

3.2 Gradle依赖声明

需要在项目级和模块级两个层面配置。项目级build.gradle（或settings.gradle）中添加Google Maven仓库，模块级build.gradle中声明依赖。

// 项目级 build.gradle（根目录）
buildscript {
    repositories {
        google()  // 必须包含
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.4.2"
    }
}

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

// 模块级 build.gradle（app 模块）
android {
    compileSdk 34
    defaultConfig {
        minSdk 21   // 动态交付最小要求
        targetSdk 34
    }
}

dependencies {
    implementation "com.google.android.play:core:1.10.3"
    // 如需Kotlin扩展可额外添加:
    // implementation "com.google.android.play:core-ktx:1.8.1"
}

  注意：从Gradle 7.0起，推荐在settings.gradle中使用dependencyResolutionManagement声明仓库。下面给出等效写法：

// settings.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

3.3 最低SDK要求

PlayCore库本身最低支持API 14（Android 4.0），但动态交付功能要求设备运行Android 5.0（API 21）或更高版本。低于API 21的设备调用SplitInstallManager时会抛出UnsupportedOperationException，因此推荐将minSdk设置为21。

⚠️ 常见踩坑：如果minSdk < 21，必须在运行时检测API版本并优雅降级——例如显示“该功能仅支持Android 5.0+”的提示，而非直接崩溃。

// 运行时检查示例
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    // 初始化 SplitInstallManager
    val manager = SplitInstallManagerFactory.create(context)
} else {
    // 降级处理：直接加载完整APK或提示用户升级
}

3.4 配置流程可视化

下图展示了从添加仓库到API可用的完整依赖配置流程：

3.5 同步验证与常见错误

执行File → Sync Project with Gradle Files后，可在External Libraries中看到play-core-1.10.3及依赖的annotations等库。如果出现以下错误，请参考排查：

错误信息	可能原因	解决方案
`Could not find com.google.android.play:core`	未添加Google Maven仓库	在项目级`build.gradle`或`settings.gradle`中添加`google()`
`Failed to resolve: :play-core:1.10.3`	版本号错误或网络问题	确认版本号存在且镜像可达，可改用`mavenCentral()`备用
`minSdk (19) is lower than the library's minSdk (21)`	模块`minSdk`低于21	将`minSdk`提升至21

  Gradle缓存清理：若依赖无法刷新，执行./gradlew clean --refresh-dependencies，再重新Sync。

3.6 性能与稳定性建议

使用固定版本号：避免使用1.+范围匹配，防止意外升级。
开启R8/ProGuard：PlayCore已包含混淆规则，通常无需额外配置。若自定义规则需保留com.google.android.play.core包下类。
最小化依赖树：仅添加core基库，无需引入core-ktx扩展（除非使用Kotlin协程简化回调）。
测试配置：在CI流水线中增加./gradlew :app:dependencies任务，输出依赖树并确认PlayCore版本一致。

快速检查命令：

./gradlew :app:dependencies --configuration implementation
# 查找 play-core 版本行：com.google.android.play:play-core:1.10.3