11.1.9 对 Gradle 插件变体的支持

2 分钟阅读

原文链接: https://kotlinlang.org/docs/gradle-plugin-variants.html

11.1.9 对 Gradle 插件变体的支持

Gradle 7.0 为 Gradle 插件作者引入了一项新特性——带变体的插件。该特性让插件在保持与旧版 Gradle 兼容的同时，更容易支持最新的 Gradle 特性。进一步了解 Gradle 中的变体选择。

借助 Gradle 插件变体，Kotlin 团队可以为不同的 Gradle 版本发布不同的 Kotlin Gradle 插件（KGP）变体。目标是在 main 变体中支持基础的 Kotlin 编译，它对应最早受支持的 Gradle 版本。每个变体都会包含对应版本的 Gradle 特性的实现。最新的变体支持最新的 Gradle 特性集。通过这种方式，可以在功能有限的前提下延长对较早 Gradle 版本的支持。

目前，Kotlin Gradle 插件有以下变体：

| 变体名 | 对应的 Gradle 版本 |

| main | 7.6.0–7.6.3 | | gradle80 | 8.0–8.0.2 | | gradle81 | 8.1.1 | | gradle82 | 8.2.1–8.4 | | gradle85 | 8.5 | | gradle86 | 8.6-8.7 | | gradle88 | 8.8-8.10 | | gradle811 | 8.11-8.12 | | gradle813 | 8.13-8.14 | | gradle96 | 9.6-9.7 |

在未来的 Kotlin 版本中会添加更多变体。

要查看你的构建使用的是哪个变体，请启用 --info 日志级别，并在输出中查找以 Using Kotlin Gradle plugin 开头的字符串，例如 Using Kotlin Gradle plugin main variant。

故障排查

注意： 下面是一些已知的 Gradle 变体选择问题的变通办法：* pluginManagement 中的 ResolutionStrategy 对多变量插件不起作用 * 当插件被添加为 buildSrc 的公共依赖时，插件变体会被忽略

Gradle 无法在自定义配置中选择 KGP 变体

Gradle 无法在自定义配置中选择 KGP 变体，这是预期之中的情况。如果你使用自定义 Gradle 配置：

Kotlin

1
2
3
configurations.register("customConfiguration") {
    // ...
}

Groovy

1
2
3
configurations.register("customConfiguration") {
    // ...
}

并且想添加对 Kotlin Gradle 插件的依赖，例如：

Kotlin

1
2
3
dependencies {
    customConfiguration("org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.20")
}

Groovy

1
2
3
dependencies {
    customConfiguration 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.20'
}

你需要把以下属性添加到你的 customConfiguration 中：

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
configurations {
    customConfiguration {
        attributes {
            attribute(
                Usage.USAGE_ATTRIBUTE,
                project.objects.named(Usage.class, Usage.JAVA_RUNTIME)
            )
            attribute(
                Category.CATEGORY_ATTRIBUTE,
                project.objects.named(Category.class, Category.LIBRARY)
            )
            // 如果你想依赖某个特定的 KGP 变体：
            attribute(
                GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
                project.objects.named("7.0")
            )
        }
    }
}

Groovy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
configurations {
    customConfiguration {
        attributes {
            attribute(
                Usage.USAGE_ATTRIBUTE,
                project.objects.named(Usage, Usage.JAVA_RUNTIME)
            )
            attribute(
                Category.CATEGORY_ATTRIBUTE,
                project.objects.named(Category, Category.LIBRARY)
            )
            // 如果你想依赖某个特定的 KGP 变体：
            attribute(
                GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
                project.objects.named('7.0')
            )
        }
    }
}

否则，你会收到类似下面这样的错误：

 > Could not resolve all files for configuration ':customConfiguration'.
      > Could not resolve org.jetbrains.kotlin:kotlin-gradle-plugin:1.7.0.
        Required by:
            project :
         > Cannot choose between the following variants of org.jetbrains.kotlin:kotlin-gradle-plugin:1.7.0:
             - gradle70RuntimeElements
             - runtimeElements
           All of them match the consumer attributes:
             - Variant 'gradle70RuntimeElements' capability org.jetbrains.kotlin:kotlin-gradle-plugin:1.7.0:
                 - Unmatched attributes:

接下来学什么？

进一步了解 Gradle 的基础知识与细节。

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)