返回

Flutter Run 报错 Unresolved reference: kotlin 解决指南

Android

Flutter Run 报错：Unresolved reference: kotlin (以及其他 Kotlin 相关错误)

刚上手 Flutter 开发就遇到了麻烦？别慌！你的flutter run命令报了一堆和 Kotlin 相关的错误，这通常是因为 Gradle 构建过程出了问题。 别着急，下面咱就一步步解决它。

一、问题现象：

项目无法正常编译运行，控制台输出类似下面的错误信息：

Launching lib\main.dart on sdk gphone64 x86 64 in debug mode...
e: file:///D:/Flutter/flutter/packages/flutter_tools/gradle/src/main/kotlin/dependency_version_checker.gradle.kts:6:22 Unresolved reference: kotlin
e: file:///D:/Flutter/flutter/packages/flutter_tools/gradle/src/main/kotlin/dependency_version_checker.gradle.kts:156:41 Unresolved reference: Version
e: file:///D:/Flutter/flutter/packages/flutter_tools/gradle/src/main/kotlin/dependency_version_checker.gradle.kts:186:33 Unresolved reference: KotlinAndroidPluginWrapper

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':gradle:compileKotlin'.
> A failure occurred while executing org.jetbrains.kotlin.compilerRunner.GradleCompilerRunnerWithWorkers$GradleKotlinCompilerWorkAction
   > Compilation error. See log for more details

...

关键错误信息是 Unresolved reference: kotlin，Unresolved reference: Version 和 Unresolved reference: KotlinAndroidPluginWrapper。 这些错误都表明 Gradle 在编译 Kotlin 代码时找不到必要的定义。

二、问题原因分析：

造成这些错误的原因可能有多种，让我们逐个排查：

  1. Kotlin 或 Gradle 插件版本不兼容： Flutter 项目依赖特定版本的 Kotlin 和 Gradle 插件。 如果版本不匹配，就会导致编译错误。

  2. Gradle 缓存问题： Gradle 会缓存依赖项和编译结果。 有时候，缓存可能会损坏或过时，导致构建失败。

  3. 网络问题（依赖项下载失败）： Gradle 需要从远程仓库下载依赖项。 如果网络连接不稳定，或者仓库地址配置错误，就可能导致下载失败。

  4. JDK 版本问题: 虽然错误信息直接指向 Kotlin, 但底层的Java Development Kit(JDK) 版本不兼容， 也会间接影响 Gradle 运行。

  5. Flutter SDK 或 项目配置问题 ：极少情况下，Flutter SDK 安装不完整或项目配置 (如 build.gradle 文件) 被错误修改，也会导致此问题。

三、解决方案：

针对以上原因，可以尝试以下几种解决办法。建议按顺序尝试，每尝试一种方法后，都重新运行 flutter run 看是否解决问题。

1. 清理 Gradle 缓存：

Gradle 缓存问题比较常见。清理缓存可以让 Gradle 重新下载依赖项， 往往能解决很多莫名其妙的错误。

  • 操作步骤：

    • 找到你项目的 android 目录。

    • 在该目录下打开命令行（或终端）。

    • 执行以下命令：

      ./gradlew clean
    然后执行:
    bash flutter clean
    • 等待命令执行完毕。
    • 重新尝试运行项目:
    flutter run

2. 更新 Gradle 和 Kotlin 插件版本：

确保项目使用兼容的 Gradle 和 Kotlin 插件版本。

  • 操作步骤：

    • 打开你项目中的 android/build.gradle 文件。
    • 找到 buildscript 块，其中包含 dependencies。 检查ext.kotlin_version = 'x.x.x' , 并确保它为合理的版本.
    • 在同一块中，检查 classpath 'com.android.tools.build:gradle:x.x.x' 确保是合理的 Gradle 版本.
    • 找到plugins块. 确认其中有id 'org.jetbrains.kotlin.android'
    • 打开你项目中的 android/gradle/wrapper/gradle-wrapper.properties 文件。
    • 找到 distributionUrl，确保其中的 Gradle 版本号是推荐的版本。

  • 修改示例 (android/build.gradle)

buildscript {
    ext.kotlin_version = '1.8.20' // 更改为你需要的 Kotlin 版本
    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2' // 更改为你需要的 Gradle 版本
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

plugins {
    id "org.jetbrains.kotlin.android" version "1.8.20" apply false
}
...
  • 修改示例(android/gradle/wrapper/gradle-wrapper.properties)
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-all.zip // 更改为匹配的 Gradle 版本

安全建议 版本不要过于激进使用最新版, 使用经过充分测试的稳定版本更可靠。 可以到Flutter官方网站查看推荐的版本。

3. 检查并修复网络连接：

如果网络连接有问题，Gradle 无法下载依赖项。

  • 操作步骤：
    • 确保你的电脑可以正常访问互联网。
    • 如果你使用代理服务器，确保代理设置正确。可以在 Gradle 配置文件中配置代理（如有必要）。
      • 在项目的 android/gradle.properties 文件 (若不存在则创建)中添加:
          systemProp.http.proxyHost=your_proxy_host
    systemProp.http.proxyPort=your_proxy_port
    systemProp.https.proxyHost=your_proxy_host
    systemProp.https.proxyPort=your_proxy_port

4. 检查并更新 JDK 版本：

Flutter 需要正确安装并配置 Java Development Kit (JDK)。

  • 操作步骤:
    • 在命令行中运行 java -version，查看已安装的 JDK 版本。
    • 在命令行中运行 echo %JAVA_HOME% (Windows) 或 echo $JAVA_HOME (macOS/Linux)，查看 JAVA_HOME 环境变量是否正确设置。 如果没有, 需要手动添加环境变量。
    • Flutter 目前推荐使用 JDK 11 或 JDK 17。 如果版本过低或过高，建议安装推荐的版本。
      • 去Oracle官网或其他可靠来源, 下载并安装 JDK.
    • 修改环境变量JAVA_HOME 到正确的 JDK 路径。
    • 重启终端或命令行。
  • Windows 系统下, 新增/修改环境变量一般需要重启电脑才能完全生效.

5. 使用 Flutter Doctor 检查环境：

Flutter 提供了一个方便的命令行工具 flutter doctor，可以检查你的开发环境是否配置正确。

  • 操作步骤：

    • 打开命令行（或终端）。

    • 运行以下命令：

      flutter doctor -v

    • 仔细查看输出信息。 flutter doctor 会列出所有发现的问题，并给出相应的解决建议。如果有任何错误或警告,按提示操作。

6. 删除并重新创建 Android 项目（作为最后的手段）：

如果以上方法都无法解决问题，可以尝试删除并重新创建 Android 项目部分。

  • 操作步骤：
    • 备份 android 文件夹
    • 删除 项目中的android目录
    • 在项目根目录中, 运行如下指令: 
      flutter create .
    • 把之前备份的配置或文件手动转移到新生成的 android 文件夹 (谨慎操作).
  • 这样做有风险，因为它会重置你对 Android 项目所做的所有自定义修改。务必提前备份.

进阶使用

  • 使用国内镜像:
    由于国内网络环境的特殊性，可以配置国内镜像加速依赖项的下载。

    在 android/build.gradle 文件的 repositories 部分，添加以下内容：

        maven { url 'https://maven.aliyun.com/repository/google' }
    maven { url 'https://maven.aliyun.com/repository/jcenter' }
    maven { url 'https://maven.aliyun.com/repository/public' }

    将原有的 google() 和 mavenCentral() 替换为国内镜像.
    同样, 可以考虑在 android/gradle.properties 文件 (若不存在则创建)中添加：

    org.gradle.jvmargs=-Xmx1536M

    可以调整 Gradle 的最大堆内存, 对于大型项目有帮助.

    然后删除 android/app/build，执行 flutter clean.

通过以上方法，你应该能解决 flutter run 命令报出的 Kotlin 相关错误，顺利开始你的 Flutter 开发之旅!