為 KMP 設定 Android Gradle 程式庫外掛程式

com.android.kotlin.multiplatform.library Gradle 外掛程式是官方支援的工具，可將 Android 目標新增至 Kotlin Multiplatform (KMP) 程式庫模組。這項工具可簡化專案設定、提升建構效能，並與 Android Studio 完美整合。

使用 com.android.library 外掛程式進行 KMP 開發時，會依賴已淘汰的 Android Gradle 外掛程式 API，且在 Android Gradle 外掛程式 9.0 以上版本 (2025 年第 4 季) 中需要選擇加入。這些 API 預計將在 Android Gradle 外掛程式 10.0 (2026 年下半年) 移除。

注意： 使用 com.android.application 外掛程式設定 Kotlin Multiplatform 模組時，沒有直接替代方案。如要遷移，請將 Android 應用程式擷取至獨立的 Gradle 模組。

如要套用這個外掛程式，請參閱「套用 Android-KMP 外掛程式」一節。如需從舊版 API 遷移，請參閱遷移指南。

如需 AGP 9.0 以上版本遷移作業的協助，可以使用 JetBrains 為 KMP 應用程式建立的代理技能。如要進一步瞭解如何在 Android Studio 中使用技能，請參閱「使用技能擴充代理模式」。請注意，AI 結果並非完全可預測。

注意： 遷移至新外掛程式前，請先瞭解已知問題和不支援的功能。

主要功能和差異

Android-KMP 外掛程式專為 KMP 專案設計，與標準 com.android.library 外掛程式有幾項主要差異：

• 單一變體架構：外掛程式使用單一變體，不再支援變種版本和建構類型，可簡化設定並提升建構效能。

• 針對 KMP 最佳化：此外掛程式專為 KMP 程式庫設計，著重於共用 Kotlin 程式碼和互通性，不支援 Android 專屬的原生建構、AIDL 和 RenderScript。

• 預設停用測試：單元和裝置 (檢測設備) 測試預設為停用，以提升建構速度。您可以視需要啟用。

• 沒有頂層 Android 擴充功能：設定由 Gradle KMP DSL 中的 android 區塊處理，維持一致的 KMP 專案結構。沒有頂層 android 擴充功能區塊。

• 選擇加入 Java 編譯：Java 編譯預設為停用。如要啟用，請在 android 區塊中使用 withJava()。這樣一來，不需要編譯 Java 時，建構時間就會縮短。

Android-KMP 程式庫外掛程式的優點

Android-KMP 外掛程式可為 KMP 專案帶來下列好處：

• 提升建構效能和穩定性：這項工具經過最佳化，可提升 KMP 專案的建構速度和穩定性。這項工具著重於 KMP 工作流程，有助於提高建構程序的效率和可靠性。

• 強化 IDE 整合：使用 KMP Android 程式庫時，可提供更優質的程式碼自動完成、導覽、偵錯和整體開發人員體驗。

• 簡化專案設定：此外掛程式會移除建構變化版本等 Android 專屬複雜設定，簡化 KMP 專案設定。這可讓建構檔案更簡潔、更容易維護。先前在 KMP 專案中使用 com.android.library 外掛程式，可能會建立令人困惑的來源集名稱，例如 androidAndroidTest。對於熟悉標準 KMP 專案結構的開發人員來說，這種命名慣例較不直覺。

不支援功能的替代方案

與 KMP 整合 com.android.library 外掛程式相比，com.android.kotlin.multiplatform.library 外掛程式缺少部分功能。以下是不支援功能的解決方法：

• 建構變化版本

  不支援建構類型和變種版本。這是因為新外掛程式採用單一變數架構，可簡化設定並提升建構效能。

  如果您需要建構變化版本，建議使用 com.android.library 外掛程式建立獨立的 Android 程式庫模組，在該模組中設定建構類型和變種版本，然後從 Kotlin Multiplatform 程式庫的 androidMain 來源集，將該模組做為標準專案依附元件使用。詳情請參閱「建立 Android 程式庫」和「設定建構變化版本」。

• 資料繫結和檢視繫結

  這些是 Android 專屬的 UI 架構功能，與 Android View 系統和 XML 版面配置緊密結合。有了新的 Android-KMP 程式庫外掛程式，建議您使用 Compose Multiplatform 等多平台架構處理 UI。資料繫結和檢視繫結會視為最終 Android 應用程式的實作詳細資料，而非可共用的程式庫。

• 原生建構支援

  新外掛程式著重於為 Android 目標產生標準 AAR。Kotlin Multiplatform 的原生程式碼整合，是由 KMP 自己的原生目標 (例如 androidNativeArm64 和 androidNativeX86) 和 C 互通功能直接處理。如需加入原生 C/C++ 程式碼，請將其定義為通用或原生來源集的一部分，並在 kotlin 區塊中設定 C-interop，而非使用 Android 專屬的 externalNativeBuild 機制。

  或者，如果您需要透過 externalNativeBuild 支援原生建構，建議您建立獨立的 com.android.library 模組，以便整合原生程式碼，並從 Kotlin Multiplatform 程式庫專案的 androidMain 來源集使用該獨立程式庫。詳情請參閱「建立 Android 程式庫」和「在專案中新增 C 和 C++ 程式碼」。

• BuildConfig 類別

  BuildConfig 功能在多變體環境中最實用。由於新的 Kotlin Multiplatform 程式庫外掛程式與變數無關，且不支援建構類型和變種版本，因此未實作這項功能。建議您改用 BuildKonfig 外掛程式或類似的社群解決方案，為所有目標產生中繼資料。

必要條件

如要使用 com.android.kotlin.multiplatform.library 外掛程式，專案必須設定為下列最低版本或更高版本：

• Android Gradle 外掛程式 (AGP)：8.10.0
• Kotlin Gradle 外掛程式 (KGP)：2.0.0

將 Android-KMP 外掛程式套用至現有模組

如要將 Android-KMP 外掛程式套用至現有的 KMP 程式庫模組，請按照下列步驟操作：

1. 在版本目錄中宣告外掛程式。開啟版本目錄 TOML 檔案 (通常是 gradle/libs.versions.toml)，並新增外掛程式定義區段：

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "9.4.0"
   kotlin = "KOTLIN_VERSION"
   
   [plugins]
   kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
   android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }
   

2. 在根層級建構檔案中套用外掛程式宣告。開啟位於專案根目錄中的 build.gradle.kts 檔案。使用 apply false 將外掛程式別名新增至 plugins 區塊。這樣一來，所有子專案都能使用外掛程式別名，而不必將外掛程式邏輯套用至根專案本身。

   Kotlin

   // Root build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

   Groovy

   // Root build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

3. 在 KMP 程式庫模組建構檔案中套用外掛程式。開啟 KMP 程式庫模組中的 build.gradle.kts 檔案，並在 plugins 區塊內檔案頂端套用外掛程式：

   Kotlin

   // Module-specific build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

   Groovy

   // Module-specific build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

4. 設定 Android KMP 目標。設定 Kotlin Multiplatform 區塊 (kotlin)，定義 Android 目標。在 kotlin 區塊中，使用 android 指定 Android 目標：

   Kotlin

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          compilerOptions.configure {
              jvmTarget.set(
                  org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
              )
          }
      }
   
      sourceSets {
          androidMain {
              dependencies {
                  // Add Android-specific dependencies here
              }
          }
          getByName("androidHostTest") {
              dependencies {
              }
          }
   
          getByName("androidDeviceTest") {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

   Groovy

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          compilerOptions.options.jvmTarget.set(
              org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
          )
      }
   
      sourceSets {
          androidMain {
              dependencies {
              }
          }
          androidHostTest {
              dependencies {
              }
          }
          androidDeviceTest {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

5. 套用變更。套用外掛程式並設定 kotlin 區塊後，請同步處理 Gradle 專案，套用變更。

從舊版外掛程式遷移

本指南可協助您從舊版 com.android.library 外掛程式遷移至 com.android.kotlin.multiplatform.library 外掛程式。

注意： 如果是 8.12.0 以下版本的 Android Gradle 外掛程式，Android 目標的設定區塊為 androidLibrary{}。自 AGP 8.12.0 起，我們推出了新的 android{} 區塊，取代 androidLibrary{}。androidLibrary{} 自 AGP 9.1.0-alpha09 起已淘汰，並將在日後推出的版本中移除。如果您使用的是 AGP 8.12.0 以上版本，請使用 android{}，否則請使用 androidLibrary{}。

1. 移動來源

舊版外掛程式除了 src/androidMain、src/androidHostTest 和 src/androidDeviceTest 之外，還可使用 src/main、src/test 和 src/androidTest 來源集。新外掛程式只會使用後者的來源目錄，因此您需要將來源從 src/main 移至 src/androidMain、從 src/test 移至 src/androidHostTest，以及從 src/androidTest 移至 src/androidDeviceTest。

2. 設定自訂來源和資源目錄

如果來源或資源位於非標準目錄，您先前會使用 sourceSets 區塊設定。使用新外掛程式時，請透過 androidComponents 擴充功能，將靜態來源目錄新增至變化版本。

請注意，使用新外掛程式時，addStaticSourceDirectory 方法會將目錄新增至現有的來源目錄清單。使用舊版外掛程式時，setSrcDirs 方法會「取代」清單，而 srcDir 方法則會「新增」至清單。

Android-KMP

使用新版外掛程式時，請透過 onVariants 區塊與變體的來源互動。

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

舊版外掛程式

使用 com.android.library 外掛程式時，sourceSets 區塊用於設定或新增來源目錄。

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. 宣告依附元件

常見的工作是宣告 Android 專屬來源集的依附元件。新外掛程式要求這些程式庫必須明確放置在 sourceSets 區塊中，與先前使用的一般 dependencies 區塊不同。

Android-KMP

新外掛程式會將 Android 依附元件分組到 androidMain 來源集內，讓結構更簡潔。除了主要來源集外，還有兩個測試來源集，會視需要建立：androidDeviceTest 和 androidHostTest (詳情請參閱「設定主機和裝置測試」)。

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

來源集有對應的 Kotlin 編譯，名為 main、deviceTest 和 hostTest。來源集和編譯作業可在建構指令碼中設定，如下所示：

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

舊版外掛程式

使用舊版外掛程式時，您可以在頂層依附元件區塊中宣告 Android 專屬依附元件，但這有時可能會在多平台模組中造成混淆。

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. 啟用 Android 資源

根據預設，新外掛程式不會啟用 Android 資源 (res 資料夾) 支援功能，以最佳化建構成效。您必須選擇加入，才能使用這項功能。這項異動可確保不需要 Android 專屬資源的專案，不會因相關建構作業而增加負擔。

Android-KMP

您必須明確啟用 Android 資源處理功能。資源應放在 src/androidMain/res 中。

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

舊版外掛程式

資源處理功能預設為啟用。您可以立即在 src/main 中新增 res 目錄，並開始新增 XML 可繪項目、值等。

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. 設定主機和裝置測試

根據預設，新外掛程式會停用 Android 主機端 (單元) 和裝置端 (檢測設備) 測試。您必須明確選擇加入才能建立測試來源集和設定，而舊版外掛程式會自動建立。

這種選擇加入模式有助於確保專案保持精簡，只包含您主動使用的建構邏輯和來源集。

Android-KMP

使用新外掛程式時，您可以在 kotlin.android 區塊中啟用及設定測試。這樣可以讓設定更明確，並避免建立未使用的測試元件。androidUnitTest 來源集會變成 androidHostTest (測試目錄從 src/androidUnitTest 變更為 src/androidHostTest)，而 androidInstrumentedTest 則會變成 androidDeviceTest (測試目錄從 src/androidInstrumentedTest 變更為 src/androidDeviceTest)。

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

舊版外掛程式

使用 com.android.library 外掛程式時，系統預設會建立 androidUnitTest 和 androidInstrumentedTest 來源集。您可以在 android 區塊中設定其行為，通常使用 testOptions DSL。

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. 啟用 Java 原始碼編譯

如果 KMP 程式庫需要為 Android 目標編譯 Java 來源，您必須使用新外掛程式明確啟用這項功能。請注意，這項設定會為直接位於專案中的 Java 檔案啟用編譯功能，而非其依附元件。設定 Java 和 Kotlin 編譯器的 JVM 目標版本的方法也會變更。

Android-KMP

您必須呼叫 withJava()，選擇啟用 Java 編譯功能。現在，JVM 目標會直接在 kotlin { android {} } 區塊內設定，讓設定更統一。在這裡設定 jvmTarget，會同時套用至 Android 目標的 Kotlin 和 Java 編譯。

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

舊版外掛程式

Java 編譯預設為啟用。Java 和 Kotlin 來源的 JVM 目標，都是在 android 區塊中使用 compileOptions 設定。

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. 使用 androidComponents 與建構變化版本互動

androidComponents 擴充功能仍可用於以程式輔助方式與建構構件互動。雖然 Variant API 的大部分內容保持不變，但新的 AndroidKotlinMultiplatformVariant 介面受到更多限制，因為外掛程式只會產生單一變化版本。

因此，與建構類型和變種版本相關的屬性，不再適用於變化版本物件。

Android-KMP

onVariants 區塊現在會疊代單一變化版本。您仍可存取 name 和 artifacts 等通用屬性，但無法存取特定建構類型的屬性。

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

舊版外掛程式

如果有多個變化版本，您可以存取建構類型專屬屬性來設定工作。

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. 選取 Android 程式庫依附元件的變化版本

KMP 程式庫會為 Android 產生單一變數。不過，您可能需要依附具有多個變體的標準 Android 程式庫 (com.android.library) (例如 free/paid 產品變種版本)。控管專案如何從該依附元件中選取變化版本，是常見的需求。

Android-KMP

新外掛程式會集中並釐清 kotlin.android.localDependencySelection 區塊中的邏輯。這樣一來，您就能更清楚瞭解，單一變體 KMP 程式庫會選取哪些外部依附元件變體。

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

舊版外掛程式

您在 buildTypes and productFlavors 區塊中設定了依附元件選取策略。這通常涉及使用 missingDimensionStrategy 為程式庫沒有的維度提供預設變種版本，或在特定變種版本中使用 matchingFallbacks 定義搜尋順序。

如要進一步瞭解 API 用法，請參閱「解決比對錯誤」。

9. 新增 Compose 預覽依附元件

通常，我們會希望將特定程式庫限定在本機開發環境中，以免內部工具洩漏到最終發布的構件中。新的 KMP Android 外掛程式會移除用於區分開發依附元件和發布程式碼的建構類型架構，因此會造成問題。

Android-KMP

如要僅為本機開發和測試新增依附元件，請直接將依附元件新增至主要 Android 編譯的執行階段類別路徑設定 (位於頂層 dependencies 區塊)。這可確保依附元件在執行階段可用 (例如 Compose 預覽等工具)，但不會成為編譯類別路徑或程式庫已發布 API 的一部分。

預先發布版： 這項解決方法僅適用於 Android Gradle 外掛程式 9.0.0-beta01 以上版本。

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

舊版外掛程式

如果 Kotlin Multiplatform 專案使用 com.android.library 外掛程式指定 Android 目標，則應使用 debugImplementation 設定，將依附元件範圍限定為偵錯版本建構類型，並防止依附元件包含在消費者使用的程式庫發布變數中。

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. 設定 KMP Android 目標的 JVM 目標

KMP Android 外掛程式會使用 android.compilerOptions.jvmTarget 設定 JVM 目標，這適用於 Java 和 Kotlin，與純 Android 專案中獨立的 compileOptions 和 kotlinOptions 區塊相比，設定更為簡單。

Android-KMP

使用包含 Android 目標的 Kotlin Multiplatform (KMP) 專案時，您可以透過多種方式，為 Kotlin 和 Java 編譯器設定 JVM 目標版本。瞭解這些設定的範圍和階層，是管理專案位元碼相容性的關鍵。

以下是設定 JVM 目標的三種主要方式，依優先順序由低到高排列。優先順序較高的 JVM 目標值會套用至符合設定的目標中較小的子集，並覆寫優先順序較低的值，也就是說，您可以為專案中不同目標和目標內的編譯設定不同的 JVM 版本。

使用 Kotlin 工具鍊 (優先順序最低)

設定 JVM 目標最常見的方法，是在 build.gradle.kts 檔案的 kotlin 區塊中指定工具鍊。這個方法會為專案中所有以 JVM 為基礎的目標 (包括 Android)，設定 Kotlin 和 Java 編譯工作的目標。

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

這項設定會讓 kotlinc 和 javac 都指定 JVM 21。這是為整個專案建立一致基準的好方法。

使用 Android 目標層級編譯器選項 (優先順序中等)

您可以在 android 區塊中，特別為 Android KMP 目標指定 JVM 目標。這項設定會覆寫專案層級的 jvmToolchain 設定，並套用至所有 Android 編譯。

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

在這種情況下，即使 jvmToolchain 設為其他版本，Android 目標的 Kotlin 和 Java 程式碼也會編譯為指定 JVM 11。

使用編譯層級編譯器選項 (優先順序最高)

如要進行最精細的控管，您可以依據編譯作業設定編譯器選項 (例如僅限 androidMain 或 androidHostTest)。如果特定編譯需要指定不同的 JVM 版本，這項功能就非常實用。這項設定會覆寫 Kotlin 工具鍊和 Android 目標層級選項。

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

這項設定可確保 Android 目標中的所有編譯作業都使用 JVM 11，提供精細的控制。

舊版外掛程式

在 KMP 專案中，如果使用標準 Android 程式庫外掛程式 (com.android.library)，設定會與使用 KMP Android 外掛程式時略有不同 (但概念相似)。

使用 Kotlin 工具鍊

kotlin.jvmToolchain() 方法的運作方式相同，會為 Java 設定 sourceCompatibility 和 targetCompatibility，並為 Kotlin 設定 jvmTarget。建議您採用這個方法。

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

compileOptions 和 kotlinOptions

如果不使用 Kotlin 工具鍊，則必須使用 Java 和 Kotlin 的個別區塊設定 JVM 目標。

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. 發布消費者保留規則

如果 KMP 程式庫需要為消費者提供消費者保留規則 (例如 R8 的 ProGuard 規則)，您必須明確啟用新外掛程式的發布功能。先前，如果指定了消費者保留規則，系統預設會發布這些規則。

Android-KMP

使用新外掛程式時，您必須設定 optimization.consumerKeepRules.publish = true，並在 consumerKeepRules 區塊中指定規則檔案，才能發布消費者保留規則。

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

舊版外掛程式

使用 com.android.library 時，根據預設，在 android.defaultConfig 中以 consumerProguardFiles 指定的任何規則檔案都會發布在程式庫的構件中。

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. 將程式庫發布至 Maven

如果您打算將 KMP 程式庫發布至 Maven，供其他專案使用，則程序會因您使用的是新的 Android-KMP 外掛程式，還是舊版外掛程式而有所不同。

Android-KMP

com.android.kotlin.multiplatform.library 外掛程式與標準 Kotlin Multiplatform 發布機制整合。除了標準 KMP 程式庫發布程序外，不需要執行任何 Android 專屬步驟。

如要發布程式庫，請按照 JetBrains 的官方說明文件操作：設定多平台程式庫的發布作業。

舊版外掛程式

在 KMP 專案中，使用 com.android.library 做為 Android 目標時，您必須按照標準 Android 程式庫發布指南，準備及發布 Android 專屬構件 (.aar)。

如需詳細操作說明，請參閱「準備要發布的程式庫」。

外掛程式 API 參考資料

新外掛程式的 API 介面與 com.android.library 不同。如要進一步瞭解新的 DSL 和介面，請參閱 API 參考資料：

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Android-KMP 程式庫外掛程式的已知問題

套用新的 com.android.kotlin.multiplatform.library 外掛程式時，可能會發生下列已知問題：

• 使用新的 android-KMP 外掛程式時，Compose 預覽功能無法運作

  • 已在 Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 和 Android Gradle Plugin 9.0.0-alpha13 中修正

• 使用 com.android.kotlin.multiplatform.library 外掛程式預覽 Compose Multiplatform 時發生 NullPointerException

  • 已在 Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 和 Android Gradle Plugin 9.0.0-alpha13 中修正

• KMP 將常見的編譯依附元件解析儲存在設定快取中，導致反序列化時發生錯誤 (僅限 Android)

  • 已在 Kotlin Gradle Plugin 2.3.0-Beta2 修正

• 支援 androidLibrary 目標的檢測 sourceSetTree

  • 已在 Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 和 Android Gradle Plugin 9.0.0-alpha13 中修正