为 KMP 设置 Android Gradle 库插件

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

使用 com.android.library 插件进行 KMP 开发依赖于 Android Gradle 插件 API，这些 API 已被弃用，并且在 Android Gradle 插件 9.0 及更高版本（2025 年第 4 季度）中需要选择启用。这些 API 预计将在 Android Gradle 插件 10.0（2026 年下半年）中移除。

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

如需有关 AGP 9.0+ 迁移的帮助，您可以使用 JetBrains 为 KMP 应用创建的智能体技能。如需详细了解如何在 Android Studio 中使用技能，请参阅使用技能扩展智能体模式。请注意，AI 结果并非完全可预测。

主要功能和差异

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

• 单变体架构：该插件使用单变体，不再支持产品变种和 build 类型，从而简化了配置并提升了 build 性能。

• 针对 KMP 进行了优化：该插件专为 KMP 库设计，专注于共享 Kotlin 代码和互操作性，省略了对 Android 专用原生 build、AIDL 和 RenderScript 的支持。

• 默认停用测试：默认情况下，单元测试和设备（插桩）测试均处于停用状态，以提高构建速度。您可以根据需要启用它们。

• 无顶级 Android 扩展：配置通过 Gradle KMP DSL 中的 android 代码块进行处理，从而保持一致的 KMP 项目结构。没有顶级 android 扩展程序块。

• 选择启用 Java 编译：Java 编译默认处于停用状态。在 android 块中使用 withJava() 即可启用。这样可以缩短不需要 Java 编译时的构建时间。

Android-KMP 库插件的优势

Android-KMP 插件可为 KMP 项目提供以下优势：

• 提升了构建性能和稳定性：它经过精心设计，可优化 KMP 项目中的构建速度并增强稳定性。它专注于 KMP 工作流，有助于实现更高效、更可靠的构建流程。

• 增强的 IDE 集成：在使用 KMP Android 库时，它可提供更好的代码补全、导航、调试和整体开发者体验。

• 简化的项目配置：该插件通过移除 build 变体等 Android 特有的复杂性，简化了 KMP 项目的配置。这会使 build 文件更简洁、更易于维护。 以前，在 KMP 项目中使用 com.android.library 插件可能会创建令人困惑的源代码集名称，例如 androidAndroidTest。对于熟悉标准 KMP 项目结构的开发者来说，这种命名惯例不太直观。

针对不支持的功能的解决方法

与 KMP 与 com.android.library 插件的集成相比，com.android.kotlin.multiplatform.library 插件缺少一些功能。以下是针对不支持的功能的解决方法：

• build 变体

  不支持 build 类型和变种版本。这是因为新插件采用单变体架构，可简化配置并提升构建性能。

  如果您需要 build 变体，我们建议您使用 com.android.library 插件创建一个单独的独立 Android 库模块，在该模块中配置 build 类型和产品变种，然后将其作为标准项目依赖项从 Kotlin Multiplatform 库的 androidMain 源代码集中使用。 如需了解详情，请参阅创建 Android 库和配置 build 变体。

• 数据绑定和视图绑定

  这些是 Android 专属界面框架功能，与 Android View 系统和 XML 布局紧密耦合。借助新的 Android-KMP 库插件，我们建议您使用 Compose Multiplatform 等多平台框架来处理界面。数据绑定和视图绑定被视为最终 Android 应用（而非可共享库）的实现细节。

• 原生 build 支持

  新插件专注于为 Android 目标生成标准 AAR。 Kotlin Multiplatform 中的原生代码集成由 KMP 自己的原生目标（例如 androidNativeArm64 和 androidNativeX86）及其 C 互操作功能直接处理。如果您需要添加原生 C/C++ 代码，应将其定义为通用或原生源代码集的一部分，并在 kotlin 代码块中配置 C 互操作，而不是使用 Android 专用的 externalNativeBuild 机制。

  或者，如果您需要通过 externalNativeBuild 获得原生 build 支持，我们建议您创建一个单独的独立 com.android.library 模块，以便在其中集成原生代码，并从 Kotlin Multiplatform 库项目的 androidMain 源代码集使用该独立库。 如需了解详情，请参阅创建 Android 库和向您的项目添加 C 和 C++ 代码。

• BuildConfig 类

  BuildConfig 功能在多变体环境中最为实用。 由于新的 Kotlin Multiplatform 库插件与变体无关，并且不支持 build 类型和产品变种，因此未实现此功能。作为替代方案，我们建议使用 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 文件中应用插件声明。打开位于项目根目录中的 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 库模块 build 文件中应用该插件。打开 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 专用源代码集声明依赖项。新插件要求将这些内容明确放置在 sourceSets 代码块中，这与之前使用的常规 dependencies 代码块不同。

// 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 逻辑和源代码集。

// 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 与 build 变体互动

androidComponents 扩展程序仍可用于以编程方式与 build 工件进行交互。虽然 Variant API 的大部分内容保持不变，但新的 AndroidKotlinMultiplatformVariant 接口更受限，因为该插件仅生成一个变体。

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

// 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 类型架构。

// 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. 发布使用方 keep 规则

如果您的 KMP 库需要为其使用者提供使用者保留规则（例如 R8 的 ProGuard 规则），您需要明确启用新插件的发布功能。以前，如果指定了使用方 keep 规则，系统会默认发布这些规则。

// 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 Surface。如需详细了解新的 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 中修复