將建構設定從 Groovy 遷移至 Kotlin

Android Gradle 外掛程式 4.0 已新增在 Gradle 建構設定中使用 Kotlin 的支援功能，以取代 Groovy (Gradle 設定檔傳統使用的程式設計語言)。

在編寫 Gradle 指令碼時，Kotlin 比 Groovy 更受歡迎，因為 Kotlin 更易解讀，並且提供更好的編譯時間檢查和 IDE 支援。

相較於 Groovy，Kotlin 目前在 Android Studio 程式碼編輯器中提供更優質的整合功能，但使用 Kotlin 的建構速度往往比使用 Groovy 慢，因此在決定是否要遷移時，請考慮建構效能。

本頁提供將 Android 應用程式 Gradle 建構檔案從 Groovy 轉換為 Kotlin 的基本資訊。如需更詳盡的遷移指南，請參閱 Gradle 的官方說明文件。

時間表

注意： 從 Android Studio Giraffe 開始，Kotlin 是建構設定的預設語言。如果您使用 AGP 8.1 和 Kotlin DSL 進行建構設定，請使用 Gradle 8.1 以獲得最佳體驗。

從 Android Studio Giraffe 開始，新專案預設會使用 Kotlin DSL (build.gradle.kts) 進行建構設定。與 Groovy DSL (build.gradle) 相比，這可提供更好的編輯體驗，其中語法會醒目顯示、完成程式碼並導覽至宣告。詳情請參閱 Gradle Kotlin DSL 入門一文。

常見詞彙

Kotlin DSL：主要參照 Android Gradle 外掛程式 Kotlin DSL，有時也被稱為潛在的 Gradle Kotlin DSL。

在本遷移指南中，「Kotlin」和「Kotlin DSL」交替使用。同樣地，「Groovy」和「Groovy DSL」是交替使用。

指令碼檔案命名

指令碼副檔名的名稱取決於建構檔案所使用的語言：

• 使用 Groovy 編寫的 Gradle 建構檔案會使用 .gradle 副檔名。
• 使用 Kotlin 編寫的 Gradle 建構檔案會使用 .gradle.kts 副檔名。

轉換語法

Groovy 和 Kotlin 的語法存在一般性差異，因此您需要在整個建構指令碼中套用這些變更。

在方法呼叫中加入括號

提示： 在變更副檔名前，請先在 Groovy 程式碼中加上括號。這樣可以更輕鬆轉換為 Kotlin。

在 Groovy 中，方法呼叫可以省略括號，在 Kotlin 中則不可省略。如要遷移設定，請在這類方法呼叫中加入括號。以下程式碼顯示如何在 Groovy 中調整設定：

compileSdkVersion 30

下方是將相同的程式碼使用 Kotlin 編寫：

compileSdkVersion(30)

在指派呼叫中加入 =

提示： 變更副檔名前，請先將 = 加入 Groovy 程式碼。 這樣可以更輕鬆轉換為 Kotlin。

Groovy DSL 可讓您在指派屬性時省略指派運算子 =，在 Kotlin 中則不可省略。以下程式碼顯示如何使用 Groovy 指派屬性：

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

以下程式碼顯示如何使用 Kotlin 指派屬性：

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

轉換字串

以下是 Groovy 和 Kotlin 之間的字串差異：

• 用於定義字串的雙引號：雖然 Groovy 允許使用單引號定義字串，但在 Kotlin 中必須使用雙引號。

• 虛線運算式上的字串內插類型：在 Groovy 中，您只能使用 $ 前置字元表示虛線運算式的字串內插類型，Kotlin 則規定必須使用大括號括住虛線運算式。例如，在 Groovy 中，您可以使用 $project.rootDir，如以下程式碼片段所示：

      myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
      

  但在 Kotlin 中，上述程式碼會呼叫 project (而非 project.rootDir) 上的 toString()。如要取得根目錄的值，請用大括號括住 ${project.rootDir} 運算式：

      myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
      

  詳情請參閱 Kotlin 說明文件中的「字串範本」一節。

重新命名副檔名

遷移建構檔案時，請將 .kts 附加至每個建構檔案。舉例來說，請選取 settings.gradle 檔案等建構檔案，將檔案重新命名為 settings.gradle.kts，並將檔案內容轉換為 Kotlin。請確保在遷移每個建構檔案後，您的專案仍可編譯。

請先遷移最小的檔案，獲得經驗後再遷移其他檔案。您可以在專案中同時使用 Kotlin 和 Groovy 建構檔案，因此可以審慎地慢慢遷移。

將 def 替換為 val 或 var

請將 def 替換為 val 或 var，這是在 Kotlin 中定義變數的方式。以下是 Groovy 中宣告變數的方式：

def building64Bit = false

下方是將相同的程式碼使用 Kotlin 編寫：

val building64Bit = false

在布林屬性前方加上 is

Groovy 會根據屬性名稱，使用屬性推算邏輯。若是布林屬性 foo，「推算方法」可以是 getFoo、setFoo 或 isFoo。因此在轉換為 Kotlin 時，您需要為 Kotlin 不支援的推算方法變更屬性名稱。舉例來說，如果是 buildTypes DSL 布林元素，就需要在元素前方加上 is。以下程式碼顯示如何在 Groovy 中設定布林屬性：

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

以下是 Kotlin 中的程式碼。請注意，屬性前方會加上 is。

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

轉換清單和對照表

Groovy 和 Kotlin 用來定義清單和對照表的語法並不相同。Groovy 使用 []，Kotlin 則明確使用 listOf 或 mapOf 呼叫集合建立方法。遷移時，請務必將 [] 替換為 listOf 或 mapOf。

以下對比 Groovy 和 Kotlin 中定義清單的方法：

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

下方是將相同的程式碼使用 Kotlin 編寫：

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

以下對比 Groovy 和 Kotlin 中定義對照表的方法：

def myMap = [key1: 'value1', key2: 'value2']

下方是將相同的程式碼使用 Kotlin 編寫：

val myMap = mapOf("key1" to "value1", "key2" to "value2")

設定建構類型

在 Kotlin DSL 中，只有偵錯和發布建構類型能以默示方式使用。所有其他自訂建構類型都必須手動建立。

在 Groovy 中，您不必預先建立，即可使用偵錯、發布和其他特定建構類型。以下程式碼片段顯示 Groovy 中具有 debug、release 和 benchmark 建構類型的設定。

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

如要在 Kotlin 中建立相對應的設定，您必須明確建立 benchmark 建構類型。

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

從 buildscript 遷移至 plugins 區塊

如果您的版本使用 buildscript {} 區塊將外掛程式新增至專案，建議您重構使用 plugins {} 區塊。plugins {} 區塊可讓您更輕鬆地套用外掛程式，且能與版本目錄搭配使用。

此外，當您在建構檔案中使用 plugins {} 區塊時，Android Studio 會知道結構定義，即使建構作業失敗也知道。這個結構定義可讓 Studio IDE 執行程式碼完成作業，並提供其他實用建議，因此有助於修正 Kotlin DSL 檔案。

尋找外掛程式 ID

雖然 buildscript {} 區塊會使用外掛程式的 Maven 座標 (例如 com.android.tools.build:gradle:7.4.0)，將外掛程式新增至建構類別路徑，但 plugins {} 區塊會改用外掛程式 ID。

對大部分的外掛程式而言，外掛程式 ID 是您使用 apply plugin 套用字串時使用的字串。舉例來說，下列外掛程式 ID 屬於 Android Gradle 外掛程式的一部分：

• com.android.application
• com.android.library
• com.android.lint
• com.android.test

您可以在 Google Maven 存放區中找到完整的外掛程式清單。

Kotlin 外掛程式可由多個外掛程式 ID 參照。建議您使用命名空間外掛程式 ID，並依照下表從簡式重構為命名空間外掛程式 ID：

簡寫外掛程式 ID	命名空間外掛程式 ID
kotlin	org.jetbrains.kotlin.jvm
kotlin-android	org.jetbrains.kotlin.android
kotlin-kapt	org.jetbrains.kotlin.kapt
kotlin-parcelize	org.jetbrains.kotlin.plugin.parcelize

您也可以在 Gradle 外掛程式入口網站、Maven Central Repository 和 Google Maven 存放區中搜尋外掛程式。如要進一步瞭解外掛程式 ID 的運作方式，請參閱「開發自訂 Gradle 外掛程式」。

執行重構

知道所用外掛程式的 ID 後，請執行下列步驟：

1. 如果 buildscript {} 區塊中已宣告外掛程式的存放區，請改為將其移至 settings.gradle 檔案。

2. 將外掛程式新增至頂層 build.gradle 檔案的 plugins {} 區塊。您需要在這裡指定外掛程式的 ID 和版本。如果外掛程式不需要套用至根專案，請使用 apply false。

3. 從頂層 build.gradle.kts 檔案移除 classpath 項目。

4. 如要套用外掛程式，請將外掛程式新增至模組層級 build.gradle 檔案的 plugins {} 區塊。您只需在這裡指定外掛程式的 ID，因為版本是沿用自根專案。

5. 從模組層級 build.gradle 檔案移除外掛程式的 apply plugin 呼叫。

舉例來說，這項設定會使用 buildscript {} 區塊：

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

以下為使用 plugins {} 區塊的設定：

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

轉換外掛程式區塊

在 Groovy 和 Kotlin 中套用 plugins {} 區塊中的外掛程式類似。以下程式碼顯示如何在使用版本目錄時，在 Groovy 中套用外掛程式：

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

以下程式碼顯示如何在 Kotlin 中執行相同操作：

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

以下程式碼顯示如何在「不」使用版本目錄時，在 Groovy 中套用外掛程式：

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

以下程式碼顯示如何在 Kotlin 中執行相同操作：

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

如要進一步瞭解 plugins {} 區塊，請參閱 Gradle 說明文件中的「套用外掛程式」一節。

其他

如要瞭解其他功能的 Kotlin 程式碼範例，請參閱下列說明文件頁面：

• 如有 ProGuard 設定，請參閱「啟用縮減、模糊處理和最佳化功能」。
• 如有 signingConfig {} 區塊，請參閱「移除建構檔案中的簽署資訊」。
• 如果使用專案層級的屬性，請參閱「設定專案層級屬性」。

注意： 雖然 Gradle 可讓您在模組層級定義專案層級的屬性，但這會導致共用這些屬性的模組發生耦合情形，因此建議您避免採用這個做法。模組耦合會導致單一模組較難匯出為獨立專案，且會阻礙 Gradle 使用平行專案執行功能加快多模組建構作業。

已知問題

目前的已知問題是使用 Kotlin 的建構速度可能比 Groovy 慢。

如何回報問題

如要瞭解如何提供問題分類所需的資訊，請參閱「建構工具和 Gradle 錯誤的詳細資料」。接著，請使用 Google 的公開 Issue Tracker 回報錯誤。

其他資源

如需使用 Kotlin 編寫的 Gradle 建構檔案實例，請參閱 GitHub 上的 Now in Android 範例應用程式。