Android Gradle 插件找不到的解决方案

问题描述

在使用 Android Studio 创建新项目或导入现有项目时，开发者可能会遇到以下错误提示：

Plugin [id: 'com.android.application', version: '8.0.2', apply: false] was not found in any of the following sources.

这个问题通常发生在 Gradle 无法正确下载或识别 Android Gradle 插件时，项目构建过程因此中断。错误提示中的版本号可能与实际使用的版本不同（如 8.3.1、8.2.2等），但核心问题相同。

常见原因

该问题通常由以下一种或多种原因导致：

• Gradle 插件版本与 Gradle 自身版本不兼容
• 网络问题（代理设置、DNS 解析失败或地区限制）
• 错误的项目配置
• JDK 版本不匹配
• 缓存损坏或离线模式问题
• 重复的 settings.gradle 配置文件

解决方案

1. 检查 Gradle 版本与 Android Gradle 插件 (AGP) 的兼容性

Gradle 版本必须与 Android Gradle 插件版本兼容。参考官方兼容性表检查你的配置：

1. 在项目根目录的 build.gradle 文件中检查 AGP 版本：

plugins {
    id 'com.android.application' version '8.1.1' apply false
}

2. 在 gradle-wrapper.properties 文件中检查 Gradle 版本：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip

兼容性参考表示例：

AGP 版本	所需 Gradle 版本
8.0.x	8.0
8.1.x	8.0 或 8.2
8.2.x	8.2
8.3.x	8.4

TIP

使用精确的版本号（如 8.2.0 而不是 8.2），避免因缩写导致的错误。

2. 正确配置 settings.gradle 文件

确保在 settings.gradle 或 settings.gradle.kts 文件中添加插件仓库配置：

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FALLBACK_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

3. 解决网络访问问题

移除代理配置

如果不需要代理，在 gradle.properties 文件中移除代理设置：

# 移除或注释掉以下内容
# systemProp.http.proxyHost=hostname
# systemProp.http.proxyPort=8080

处理地区限制问题

若遇地区性访问限制：

1. 尝试使用 VPN 更换区域
2. 在 gradle.properties 中添加可用的代理

systemProp.socksProxyHost=127.0.0.1
systemProp.socksProxyPort=2080

4. 检查并修复项目结构问题

合并重复的 settings 文件

若存在多个 settings.gradle 文件（如添加模块后产生的多余文件）：

1. 整合所有模块声明到主 settings.gradle.kts 文件

include(":app", ":your-module")

2. 删除多余的 settings.gradle 文件

5. 管理 Gradle 缓存和模式

禁用离线模式

在 Android Studio 中关闭离线模式：

1. File > Settings > Build, Execution, Deployment
2. 选择 Gradle > 取消勾选 "Offline work"

刷新依赖缓存

在终端执行：

./gradlew build --refresh-dependencies

WARNING

在 Android Studio Hedgehog 2023.1.1+ 中，确保 JDK 版本与 AGP 兼容（建议 JDK 17+）

6. 处理 DNS 相关问题

使用验证有效的 DNS 服务：

1. 更换本地 DNS 设置（如 Google DNS 8.8.8.8）
2. 或使用 DNS-over-HTTPS：

https://free.shecan.ir/dns-query # 仅适用于特定地区

7. 清理与重置环境

清除缓存步骤：

1. 删除项目根目录中的 .gradle 文件夹
2. 重新下载所需的 Gradle 版本
3. 在 Android Studio 选择 File > Invalidate Caches / Restart

8. 其它常见处理方案

模块化配置迁移

如果从旧版 classpath 迁移到 plugins{} 块，确保：

// 删除旧版配置
dependencies {
    // classpath 'com.android.tools.build:gradle:8.2.1'
}

// 改为
plugins {
    id 'com.android.application' version '8.2.1' apply false
}

JDK 版本修正

在 Project Structure > SDK Location 中设置兼容的 JDK 版本（推荐 JDK 17）

最佳实践总结

问题类型	解决方案优先级	验证方法
版本不兼容	★★★★★	检查兼容表
网络连接问题	★★★★☆	curl 测试资源
配置错误	★★★☆☆	检查 settings.gradle
JDK 不匹配	★★★☆☆	检查 Project Structure
离线模式启用	★★☆☆☆	检查 Gradle 设置

按照上述解决方案顺序排查问题，通常能解决大多数 Gradle 插件未找到的错误。确保所有配置一致并符合最新 Android 开发规范。

TIP

定期更新 Android Studio 和 Gradle 版本，避免使用已淘汰的配置选项。