Gradle插件无需安装，须在build.gradle中用plugins块声明；错误做法包括命令行安装、手动放JAR包；正确方式是通过pluginManagement配置仓库，优先使用gradlePluginPortal()并设镜像回退。
Gradle插件不是“安装”的，而是声明在 build.gradle 里
很多人搜“安装Gradle插件”，其实是误解了 Gradle 的工作方式：它没有全局安装插件的概念，插件是按项目声明、按构建脚本解析加载的。所谓“添加插件”，就是在 build.gradle（或 build.gradle.kts）中用 plugins { ... } 或 apply plugin: 'xxx' 显式引入。
常见误区：
- 试图用命令行像 npm install 那样“装”一个 Gradle 插件 → 不可行
- 把插件 JAR 手动丢进
~/.gradle/caches/→ 极易导致版本冲突或类加载失败 - 在 IDE 里点“刷新 Gradle 项目”前没保存
build.gradle→ 插件不会生效
正确做法是直接编辑构建脚本。例如启用 Java 编译支持：
plugins {
id 'java'
}
这个 id 'java' 会自动从 Gradle 官方插件仓库解析并下载对应版本的插件（如 Gradle 8.5 默认用 java 插件 8.5），无需手动指定 URL 或路径。
立即学习“Java免费学习笔记（深入）”；
依赖和插件都走 repositories，但来源和用途完全不同
插件（plugins 块）默认只从 Gradle Plugin Portal 解析；而项目依赖（dependencies）默认不配置仓库时会失败。二者必须分开声明仓库，且不能混用。
典型错误写法：
// ❌ 错误：在 plugins 块里加 mavenCentral() —— plugins 块不认这个
plugins {
mavenCentral() // 语法错误，编译直接失败
id 'org.springframework.boot' version '3.2.0''
// ✅ 正确：插件仓库单独配在 settings.gradle(.kts)，依赖仓库配在 build.gradle
// settings.gradle
pluginManagement {
repositories {
gradlePluginPortal() // 必须有，插件主源
mavenCentral() // 可选，用于某些自研插件发布到私仓
}
}
// build.gradle
repositories {
mavenCentral() // 仅影响 dependencies，不影响 plugins
}
如果你用的是私有 Nexus/Artifactory，记得在 pluginManagement.repositories 里也加上对应地址，否则自研插件无法 resolve。
id 'xxx' 和 apply plugin: 'xxx' 的关键区别
两种写法都能加载插件，但行为差异很大，尤其涉及版本控制和构建缓存：
-
plugins { id 'java' }：推荐方式，支持版本声明、静态解析、构建扫描识别、IDE 更好支持 -
apply plugin: 'java'：旧式写法，动态加载，插件版本由 Gradle 自己推断（可能不一致），IDE 同步常出问题 - 混合使用风险：同一插件既用
plugins又用apply→ 构建失败或行为不可预测
特别注意：Spring Boot 插件必须用 plugins 块声明带版本号，否则 Gradle 无法确定兼容性：
plugins {
id 'org.springframework.boot' version '3.2.0' apply false // apply false 表示不立即应用，供子项目复用
id 'io.spring.dependency-management' version '1.1.4' apply false
}
这里的 apply false 是关键——避免根项目被意外注入 Spring Boot 生命周期，只留作配置模板。
本地开发调试插件时，别跳过 gradlePluginPortal() 的代理配置
如果你在企业内网或用了代理，gradlePluginPortal() 默认走 HTTPS 直连，很可能超时卡住，表现为：
- 执行
./gradlew build卡在 “Resolving plugin dependencies” - IDEA 刷新 Gradle 项目一直转圈，日志里出现
Could not resolve plugin
解决方法是在 settings.gradle 的 pluginManagement 中显式配置代理或镜像：
pluginManagement {
repositories {
maven {
url 'https://maven.aliyun.com/repository/public' // 阿里云镜像可替代 gradlePluginPortal()
}
gradlePluginPortal() // 保留，作为 fallback
}
}
或者设置系统级代理（不推荐，影响所有项目）：export GRADLE_OPTS="-Dhttps.proxyHost=xxx -Dhttps.proxyPort=xxx"。真正稳定的做法是统一用镜像源 + gradlePluginPortal() 回退组合。
插件解析失败往往不报具体错误，只显示超时或空异常，这点比普通依赖更难排查——务必先确认 pluginManagement.repositories 是否可达。
