Android Studio Groovy迁移至Kotlin DSL完整指南（Gradle 8.6+Android St

Android Studio Groovy迁移至Kotlin DSL完整指南（Gradle 8.6+）

一、迁移全景路线图

1. 环境准备
   - JDK 17+
   - Android Studio Flamingo 2023.2.1+
   - 网络代理工具（Clash/Charles）

2. 文件转换顺序
   settings.gradle → settings.gradle.kts  
   gradle.properties → 保持原样（需Kotlin兼容处理）  
   build.gradle → build.gradle.kts  
   libs.versions.toml → 新建版本目录  
   gradle-wrapper.properties → 升级至8.6+

3. 验证流程
   阶段验证 → 全量验证 → 性能对比

二、版本目录（Version Catalogs）深度实践

1. 目录结构规范

# gradle/libs.versions.toml
[versions]
agp = "8.3.0"         # Android Gradle Plugin
kotlin = "1.9.20"     # Kotlin版本
coreKtx = "1.12.0"    # AndroidX Core

[libraries]
# 标准格式
androidx-core = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }

# 简写格式
material3 = "androidx.compose.material3:material3:1.1.2"

# 包含分类器
firebase-analytics = { 
  group = "com.google.firebase", 
  name = "firebase-analytics", 
  version = "21.5.0", 
  classifier = "play-services" 
}

[bundles]
compose = [
  "androidx.compose.foundation:foundation",
  "androidx.compose.material3:material3",
  "androidx.compose.ui:ui-tooling-preview"
]

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

2. 多环境版本控制

# 通过环境变量切换版本
[versions]
retrofit = { strictly = "[2.9.0, 3.0.0[", prefer = "2.9.0" }

3. 动态版本解析

// build.gradle.kts
dependencies {
    val retrofitVersion = libs.versions.retrofit.get()
    implementation("com.squareup.retrofit2:retrofit:$retrofitVersion")
}

三、仓库配置全维度解析

1. 企业级仓库配置

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        // 私有Maven仓库
        maven {
            url = uri("https://nexus.example.com/repository/maven-public/")
            credentials {
                username = providers.gradleProperty("nexusUser").get()
                password = providers.gradleProperty("nexusPassword").get()
            }
            content {
                includeGroup("com.company")
            }
        }

        // 阿里云镜像
        maven { 
            url = uri("https://maven.aliyun.com/repository/public") 
            metadataSources {
                mavenPom()
                artifact()
                ignoreGradleMetadataRedirection()
            }
        }
    }
}

2. 仓库过滤策略

repositories {
    mavenCentral {
        content {
            excludeModule("com.google.guava", "guava")
        }
    }
    google {
        content {
            includeGroupByRegex("androidx\\..*")
        }
    }
}

四、构建脚本迁移详解

1. Android配置完全转换

android {
    namespace = "com.example.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.app"
        minSdk = 24
        targetSdk = 34
        versionCode = libs.versions.appVersionCode.get().toInt()
        versionName = libs.versions.appVersionName.get()

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
        vectorDrawables.useSupportLibrary = true
    }

    signingConfigs {
        create("release") {
            storeFile = file("keys/release.jks")
            storePassword = System.getenv("STORE_PASSWORD")
            keyAlias = "releaseKey"
            keyPassword = System.getenv("KEY_PASSWORD")
        }
    }

    buildTypes {
        getByName("debug") {
            applicationIdSuffix = ".debug"
            isDebuggable = true
        }
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
        isCoreLibraryDesugaringEnabled = true
    }

    kotlinOptions {
        jvmTarget = "17"
        freeCompilerArgs = freeCompilerArgs + listOf(
            "-opt-in=kotlin.ExperimentalStdlibApi",
            "-Xcontext-receivers"
        )
    }

    buildFeatures {
        compose = true
        buildConfig = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = libs.versions.composeCompiler.get()
    }

    packaging {
        resources {
            excludes += "/META-INF/{AL2.0,LGPL2.1}"
        }
    }
}

2. 依赖管理的20个关键场景

dependencies {
    // 基础依赖
    implementation(libs.androidx.core.ktx)
    
    // Compose全家桶
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.bundles.compose)
    debugImplementation(libs.androidx.compose.ui.tooling)
    
    // 动态功能模块
    implementation(libs.play.core.ktx)
    
    // 测试依赖
    testImplementation(libs.junit.jupiter.api) {
        exclude(group = "org.hamcrest", module = "hamcrest-core")
    }
    androidTestImplementation(libs.androidx.test.ext.junit)
    
    // 注解处理
    ksp(libs.room.compiler)
    
    // 条件依赖
    if (project.hasProperty("enableAnalytics")) {
        implementation(libs.firebase.analytics)
    }
    
    // 排除传递依赖
    implementation(libs.okhttp) {
        exclude(module = "kotlin-stdlib")
    }
    
    // 强制版本
    configurations.all {
        resolutionStrategy.force(libs.findLibrary("guava").get())
    }
}

五、高级构建场景

1. 自定义APK输出

androidComponents {
    onVariants { variant ->
        variant.outputs.forEach { output ->
            output.outputFileName.set(
                "app-${variant.name}-${variant.versionName}.apk"
            )
        }
    }
}

2. 动态清单修改

tasks.named("processDebugManifest").configure {
    doLast {
        val manifestFile = File(processManifest.manifestOutputDirectory.get().asFile, "AndroidManifest.xml")
        val modifiedContent = manifestFile.readText()
            .replace("android:debuggable=\"false\"", "android:debuggable=\"true\"")
        manifestFile.writeText(modifiedContent)
    }
}

3. 多渠道打包

flavorDimensions += "environment"
productFlavors {
    create("dev") {
        dimension = "environment"
        applicationIdSuffix = ".dev"
        resValue("string", "app_name", "App Dev")
    }
    create("prod") {
        dimension = "environment"
        resValue("string", "app_name", "My App")
    }
}

六、企业级优化方案

1. 构建缓存配置

// settings.gradle.kts
buildCache {
    local {
        directory = File(rootDir, "build-cache")
        removeUnusedEntriesAfterDays = 30
    }
    
    remote<HttpBuildCache> {
        url = uri("https://cache.example.com/gradle/")
        credentials {
            username = "user"
            password = "pass"
        }
    }
}

2. 构建扫描集成

plugins {
    id("com.gradle.build-scan") version "3.16"
}

buildScan {
    termsOfServiceUrl = "https://gradle.com/terms-of-service"
    termsOfServiceAgree = "yes"
    publishAlways()
}

七、迁移验证Checklist

- [ ] 编译通过：./gradlew assembleDebug  
- [ ] 单元测试通过：./gradlew test  
- [ ] 静态分析通过：./gradlew lint  
- [ ] 性能对比：对比新旧构建时间（--profile）  
- [ ] 产物验证：对比APK/Metadata  
- [ ] IDE兼容：Android Studio无红色错误  
- [ ] 增量构建：修改单个文件验证增量编译  
- [ ] 缓存测试：clean后二次构建时间正常

本教程深度整合Gradle官方文档、Android最佳实践及企业级项目经验，覆盖从基础配置到高阶优化的全场景，建议配合Gradle的--dry-run参数分阶段验证。遇到问题时，可通过./gradlew build --scan生成详细分析报告。