原生移动开发 / 系统课时
依赖管理与 Version Catalog
依赖管理与 Version Catalog
当依赖版本直接散落在各模块的 build.gradle.kts 中,升级很容易漏改。Version Catalog 把坐标和版本集中到 gradle/libs.versions.toml,模块只引用类型安全的别名。本课将完成一个 AndroidX 依赖的定义、引用和解析验证,并说明 Catalog 能做什么、不能做什么。
学习目标
- 在
libs.versions.toml中声明版本与 AndroidX 库别名 - 在模块
build.gradle.kts中通过libs类型安全访问器添加依赖 - 用 Gradle 依赖报告确认 Catalog 最终解析到的模块版本
从依赖坐标变成类型安全别名
传统写法会在模块中直接写 group:artifact:version。Version Catalog 把这三个信息移到 TOML 文件,再由 Gradle 生成 libs 访问器;模块仍然通过 implementation 等配置声明“我需要这个库”,Catalog 本身不会自动把任何依赖加入项目。
标准路径 gradle/libs.versions.toml 会作为默认 libs Catalog 被 Gradle 识别。别名中的短横线会形成分层访问器,例如 androidx-core 在 Kotlin DSL 中可写成 libs.androidx.core。

在 libs.versions.toml 定义 AndroidX 依赖
在项目根目录的 gradle/libs.versions.toml 中加入下面内容。示例版本用于演示 Catalog 语法,实际项目升级时应结合 compileSdk、Kotlin 和其他依赖兼容性统一验证。
[versions]
androidx-core = "1.17.0"
[libraries]
androidx-core = { module = "androidx.core:core", version.ref = "androidx-core" }[versions] 给版本字符串起名;[libraries] 给完整依赖坐标起别名,并通过 version.ref 复用版本。这样多个模块需要同一个 AndroidX Core 时,不必分别维护版本号。
这是配置文件,不会直接产生控制台输出。生效行为是 Gradle 为 androidx-core 生成可在构建脚本中访问的别名;修改 TOML 后应先让 Android Studio 重新 Sync,或直接运行一次 Gradle 命令触发模型刷新。
在模块中消费 Catalog
下面是 app/build.gradle.kts 的片段示例,前提是项目已经存在默认 libs Catalog,并且 app 是可构建的 Android 模块。
dependencies {
// 别名来自 gradle/libs.versions.toml,不再在模块里硬编码版本。
implementation(libs.androidx.core)
}这里的 libs.androidx.core 最终对应 androidx.core:core:1.17.0。如果 TOML 中使用了不同别名,Kotlin DSL 的访问器名称也会随之变化;出现 Unresolved reference: libs 或访问器不存在时,先检查文件是否位于默认路径、TOML 是否能解析,再执行 Gradle Sync,而不是手工猜测访问器名称。
验证最终解析版本
在项目根目录运行依赖报告,并只查看 app 模块的调试运行时类路径。输出通常很长,下面只关心 AndroidX Core 对应的关键行。
./gradlew :app:dependencies --configuration debugRuntimeClasspath预期输出
debugRuntimeClasspath - Runtime classpath of 'debug'.
+--- androidx.core:core:1.17.0
...
BUILD SUCCESSFUL in <TIME><TIME>、传递依赖数量以及树中的其他行会随项目变化。如果看到 androidx.core:core 后面的版本不是 1.17.0,说明依赖图中可能存在更高版本请求、约束或平台规则,需要继续用 dependencyInsight 定位是谁改变了最终选择。
Catalog 的边界要分清
Version Catalog 解决的是“集中声明坐标和请求版本”以及“生成类型安全访问器”,不是锁死依赖解析结果。Gradle 仍会根据完整依赖图做版本冲突处理,因此 Catalog 中写了某个版本,不等于最终解析一定使用它。
同样,Catalog 只负责声明候选项;只有模块真正写了 implementation(libs.androidx.core),该库才进入这个模块的依赖图。需要强制版本范围、统一平台约束或锁定解析结果时,应使用 dependency constraints、platform/BOM 或 dependency locking 等专门机制,而不是把 Version Catalog 当成版本锁。