如何构建兼容多版本Kotlin的Android AAR库？版本兼容求助

问题重现 #

使用Kotlin 1.7.10开发的Android AAR库，引入到Kotlin 1.4.32版本的项目时，构建报错：

Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 1.7.1, expected version is 1.4.2.

即使将库的Kotlin版本降至1.6.21，问题依然存在。

核心原因 #

Kotlin编译器会生成与版本绑定的元数据，高版本Kotlin编译的库元数据无法被低版本编译器解析。1.6.x版本的Kotlin元数据版本为1.6.0，仍高于1.4.2，因此报错。

解决方案 #

1. 配置库的Kotlin API兼容性 #

在库的模块级build.gradle（或build.gradle.kts）中，指定API兼容的最低Kotlin版本，让编译器生成低版本可解析的元数据：

Groovy 配置

android {
    // 保留其他Android配置
    kotlinOptions {
        // 设定API兼容到1.4版本
        apiVersion = "1.4"
        // 若需使用高版本语法但生成兼容元数据，可仅设置apiVersion
        // languageVersion = "1.7"
    }
}

Kotlin DSL 配置

android {
    // 保留其他Android配置
    kotlinOptions {
        apiVersion = "1.4"
        // languageVersion = "1.7"
    }
}

2. 启用兼容性元数据变体 #

若需适配更多Kotlin版本，启用Kotlin官方的兼容性元数据变体，让Gradle生成多版本适配的元数据：

在项目根目录的settings.gradle（或settings.gradle.kts）中添加：

Groovy 配置

enableFeaturePreview("VERSION_CATALOGS")
enableFeaturePreview("KOTLIN_MPP_COMPATIBILITY_METADATA_VARIANT")

Kotlin DSL 配置

enableFeaturePreview("VERSION_CATALOGS")
enableFeaturePreview("KOTLIN_MPP_COMPATIBILITY_METADATA_VARIANT")

同时在库的模块级配置中补充：

kotlin {
    jvmToolchain(11) // 适配Android要求的JDK版本
    sourceSets.all {
        languageSettings.apply {
            apiVersion = "1.4"
        }
    }
}

3. 强制统一项目Kotlin依赖版本 #

若项目存在多版本Kotlin依赖冲突，在根目录build.gradle中强制所有模块使用目标项目的Kotlin版本：

Groovy 配置

subprojects {
    configurations.all {
        resolutionStrategy {
            force "org.jetbrains.kotlin:kotlin-stdlib:1.4.32"
            force "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.4.32"
            force "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.4.32"
        }
    }
}

Kotlin DSL 配置

subprojects {
    configurations.all {
        resolutionStrategy {
            force("org.jetbrains.kotlin:kotlin-stdlib:1.4.32")
            force("org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.4.32")
            force("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.4.32")
        }
    }
}

4. 兼容性注意事项 #

• 若需兼容Kotlin 1.4.x，避免使用1.4以上的语法特性（如密封类扩展、inline类增强等）
• 若要使用高版本语法同时兼容低版本，仅设置apiVersion为低版本，languageVersion为高版本，编译器会自动降级语法至兼容版本

验证步骤 #

1. 重新构建库的AAR文件
2. 在目标项目中替换旧AAR为新构建版本
3. 执行./gradlew clean build验证构建是否成功

内容的提问来源于stack exchange，提问作者Ali