设置用于 KMP 的 Android Gradle 库插件

com.android.kotlin.multiplatform.library Gradle 插件是官方支持的工具，用于向 Kotlin Multiplatform (KMP) 库模块添加 Android 目标。它简化了项目配置，提高了构建性能，并提供了与 Android Studio 更好的集成。

在 KMP 开发中使用 com.android.library 插件依赖于已弃用的 Android Gradle 插件 API，这些 API 在 Android Gradle 插件 9.0 及更高版本（2025 年第四季度）中需要手动选择启用 (opt-in)。这些 API 预计将在 Android Gradle 插件 10.0（2026 年下半年）中移除。

要应用此插件，请参阅应用 Android-KMP 插件部分。如果您需要从旧版 API 迁移，请查看迁移指南。

如需关于 AGP 9.0+ 迁移的帮助，您可以使用 JetBrains 为 KMP 应用创建的 agent skill。有关在 Android Studio 中使用技能的更多信息，请参阅通过技能扩展代理模式。请记住，AI 生成的结果不完全可预测。

主要功能与区别

Android-KMP 插件专为 KMP 项目量身定制，与标准的 com.android.library 插件在几个关键方面有所不同

• 单一变体架构：该插件使用单一变体，不再支持产品风味 (product flavors) 和构建类型 (build types)，这简化了配置并提高了构建性能。

• 针对 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 项目结构的开发者来说，这种命名约定不够直观。

不支持功能的变通方法

与使用 com.android.library 插件的 KMP 集成相比，com.android.kotlin.multiplatform.library 插件缺失了一些功能。以下是针对不支持功能的变通方法

• 构建变体

  不支持构建类型和产品风味。这是因为新插件采用了单一变体架构，旨在简化配置并提高构建性能。

  如果您需要构建变体，建议使用 com.android.library 插件创建一个单独的独立 Android 库模块，在该模块中配置构建类型和产品风味，然后将其作为标准项目依赖项供您的 Kotlin Multiplatform 库的 androidMain 源集使用。有关更多详细信息，请参阅创建 Android 库和配置构建变体。

• 数据绑定 (Data binding) 和视图绑定 (View binding)

  这些是与 Android 视图系统和 XML 布局紧密耦合的 Android 特定 UI 框架功能。对于新的 Android-KMP 库插件，我们建议您使用像 Compose Multiplatform 这样的多平台框架来处理 UI。数据绑定和视图绑定被视为最终 Android 应用的实现细节，而不是可共享的库。

• 原生构建支持

  新插件专注于为 Android 目标生成标准的 AAR。Kotlin Multiplatform 中的原生代码集成直接由 KMP 自身的原生目标（如 androidNativeArm64 和 androidNativeX86）及其 C 互操作能力处理。如果您需要包含原生 C/C++ 代码，应将其定义为通用或原生源集的一部分，并在 kotlin 代码块内配置 C 互操作，而不是使用 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.2.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 插件。

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 方法会添加到列表中。

// 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")
    }
}

// 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 特有的源集声明依赖项。与以前使用的常规 dependencies 代码块不同，新插件要求将它们明确放置在 sourceSets 代码块内。

// 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")
        }
    }
}

// build.gradle.kts

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

// 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 特有资源的项目不会受到相关构建开销的负担。

// build.gradle.kts

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

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.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 主机端（单元）测试和设备端（插桩）测试。您必须显式选择启用以创建测试源集和配置，而旧版插件会自动创建它们。

这种“选择启用”模型有助于确保您的项目保持精简，并且仅包含您实际使用的构建逻辑和源集。

// 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

// 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 目标版本的方法也有所变化。

// 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

// 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 接口受到了更多限制，因为插件仅产生一个单一变体。

因此，与构建类型和产品风味相关的属性在变体对象上不再可用。

// build.gradle.kts

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

// build.gradle.kts

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

8. 选择 Android 库依赖项的变体

您的 KMP 库为 Android 产生单一变体。但是，您可能依赖于一个具有多个变体（例如 free/paid 产品风味）的标准 Android 库（com.android.library）。控制您的项目如何从该依赖项中选择变体是一个常见需求。

// 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"))
      }
    }
  }
}

9. 添加 Compose 预览依赖项

通常，我们希望将特定库限定在本地开发环境中，以防止内部工具泄露到最终发布的产物中。使用新的 KMP Android 插件时，这是一个挑战，因为它删除了用于将开发依赖项与发布代码分离的构建类型架构。

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

// 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 代码块，简化了配置。

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

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

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

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

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. 发布使用者保留规则 (consumer keep rules)

如果您的 KMP 库需要为其使用者发布使用者保留规则（例如 R8 的 ProGuard 规则），则需要使用新插件显式启用发布功能。以前，如果指定了使用者保留规则，则默认会发布它们。

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

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

12. 将您的库发布到 Maven

如果您计划将 KMP 库发布到 Maven 以供其他项目使用，流程取决于您使用的是新的 Android-KMP 插件还是旧版插件。

插件 API 参考

新插件具有与 com.android.library 不同的 API 表面。有关新 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 中修复