Kotlin 版本不兼容错误解决方案

问题描述

在构建 Android 应用时，你可能会遇到以下错误信息：

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

这个错误表示项目中使用的 Kotlin 版本之间存在不兼容问题。具体来说，某个依赖库是用较新版本的 Kotlin 编译的，而你的项目配置使用的是较旧版本的 Kotlin。

根本原因

此错误通常由以下原因引起：

1. Kotlin Gradle 插件版本与 Kotlin 标准库版本不匹配
2. 项目中的多个依赖项使用了不同版本的 Kotlin
3. Gradle 缓存中存在旧的或损坏的 Kotlin 相关文件

解决方案

根据不同的项目类型和配置，以下是几种有效的解决方案：

方案一：更新 Kotlin 版本（适用于大多数项目）

在项目根目录的 build.gradle（或 build.gradle.kts）文件中更新 Kotlin 版本：

buildscript {
    ext.kotlin_version = '1.9.23' // 使用最新稳定版本
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.3.1"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

TIP

你可以从 Kotlin 官方发布页面 查看最新稳定版本。

方案二：更新 settings.gradle（适用于 Flutter 和新版 Android 项目）

对于 Flutter 项目和新版本的 Android 项目，Kotlin 版本通常在 android/settings.gradle 文件中定义：

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.3.1" apply false
    id "org.jetbrains.kotlin.android" version "1.9.23" apply false
}

确保 org.jetbrains.kotlin.android 版本与项目其他部分的 Kotlin 版本一致。

方案三：清理 Gradle 缓存

有时简单的清理缓存可以解决问题：

1. 通过 Android Studio 清理：

   • 菜单栏选择 File > Invalidate Caches / Restart
   • 选择 Invalidate and Restart

2. 手动清理：

   • 删除项目中的 build 文件夹
   • 删除 Gradle 缓存目录（通常位于 ~/.gradle/caches 或 C:\Users\用户名\.gradle\caches）

方案四：检查依赖项兼容性

如果更新 Kotlin 版本后问题仍然存在，可能是某个依赖项与当前 Kotlin 版本不兼容：

// 在 app 模块的 build.gradle 中检查依赖项
dependencies {
    implementation "androidx.core:core-ktx:1.12.0" // 确保与 Kotlin 版本兼容
    // 其他依赖项...
}

WARNING

某些库（如协程库）可能有特定的 Kotlin 版本要求。检查并确保所有依赖项的版本兼容性。

方案五：React Native 项目特殊处理

对于 React Native 项目，添加以下配置到 android/build.gradle：

allprojects {
    repositories {
        exclusiveContent {
            filter {
                includeGroup "com.facebook.react"
            }
            forRepository {
                maven {
                    url "$rootDir/../node_modules/react-native/android"
                }
            }
        }
        // 其他仓库...
    }
}

预防措施

1. 保持更新：定期更新 Kotlin 和 Android Gradle 插件到最新稳定版本
2. 统一版本：确保项目中所有模块使用相同的 Kotlin 版本
3. 检查兼容性：添加新依赖时检查其与当前 Kotlin 版本的兼容性
4. 使用版本目录：考虑使用 Gradle 版本目录统一管理所有依赖版本

总结

Kotlin 版本不兼容错误通常通过更新 Kotlin Gradle 插件和标准库版本来解决。关键在于确保项目中所有组件使用相同且兼容的 Kotlin 版本。对于不同类型的项目（纯 Android、Flutter 或 React Native），配置文件的路径和方式可能有所不同，但核心解决思路是一致的。

INFO

如果你正在开发库项目并需要向后兼容，可以考虑设置 languageVersion 和 apiVersion：

compileKotlin {
    kotlinOptions {
        languageVersion = "1.4"
        apiVersion = "1.4"
    }
}