新版 Android 项目 build.gradle.kts 升级说明

1. 新方式 vs 旧的 classpath 方式

旧方式（buildscript + classpath）

// 旧方式（build.gradle）
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.1.0"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0"
    }
}

// 然后在子模块中使用
apply plugin: 'com.android.application'
apply plugin: 'org.jetbrains.kotlin.android'

新方式（Version Catalog + alias）

// 新方式（build.gradle.kts）
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
}

主要区别

特性	旧方式 (classpath)	新方式 (alias + Version Catalog)
版本管理	硬编码在 buildscript 中	集中在 libs.versions.toml
类型安全	无	有（IDE 自动补全和检查）
可维护性	分散在各处	统一管理
代码提示	无	有（IDE 支持）
跨项目共享	困难	容易（通过 toml 文件）

2. libs.versions.toml 与 build.gradle.kts 的关系

libs.versions.toml 是 Gradle Version Catalog，用于集中管理依赖和插件版本。

工作流程

1. 在 libs.versions.toml 中定义版本和插件：

[versions]
agp = "8.13.2"
kotlin = "2.0.21"
// ... 其他版本

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

2. 在根 build.gradle.kts 中引用（apply false 表示不在根项目应用，仅声明）：

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.therouter) apply false
}

3. 在子模块（如 app/build.gradle.kts）中应用：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

优势

• 版本集中管理：所有版本在 libs.versions.toml 中，修改一处即可
• 类型安全：libs.plugins.xxx 由 Gradle 生成，IDE 提供自动补全
• 避免错误：减少拼写和版本号错误
• 易于维护：大型项目统一管理依赖更方便

映射关系

• libs.plugins.android.application → [plugins] 中的 android-application
• libs.plugins.kotlin.android → [plugins] 中的 kotlin-android
• libs.androidx.core.ktx → [libraries] 中的 androidx-core-ktx

这是 Gradle 推荐的现代依赖管理方式，比旧的 classpath 方式更清晰、更易维护。