gradle -v输出版本信息即表示安装和环境变量配置成功；若报“command not found”说明PATH未配对，报“Unsupported class file major version”则需JDK 17+，IDEA中还需启用Gradle插件并用Import Project方式导入。

直接运行 gradle -v 看输出，有版本号就代表可用

这是最快速、最可靠的验证方式。只要终端能识别 gradle 命令，并打印出 Gradle 版本、Groovy、Ant、JVM 和 OS 信息，说明安装和环境变量配置都已生效。

• 如果提示 command not found（Linux/macOS）或 'gradle' 不是内部或外部命令（Windows），说明 PATH 没配对，或者没重启终端/命令行窗口
• 如果报错 Unsupported class file major version，大概率是 JDK 版本太低——Gradle 8.5+ 要求 JDK 17+，得去 gradle/wrapper/gradle-wrapper.properties 查 distributionUrl，再核对本地 JAVA_HOME 或 IDEA 中的 Gradle JVM 设置
• 别只测命令行，还要进 IDEA 看是否真能用：打开 build.gradle 文件，语法高亮、代码补全、右键有 Reload project，才是完整可用

检查 GRADLE_USER_HOME 是否生效，避免 C 盘爆满

Gradle 默认把依赖包、插件缓存全扔在 C:\Users\{user}\.gradle（Windows）或 ~/.gradle（macOS/Linux），长期不用清理会悄悄吃掉几十 GB。

• 设置系统级环境变量 GRADLE_USER_HOME 指向其他盘路径，比如 D:\gradle\.gradle，比每次加 -g 参数更可靠
• 改完后重新开终端再跑 gradle -v，看输出里 Gradle User Home 行是否已更新——没变就是变量没生效，常见原因是没重启终端，或 Windows 下设成了用户变量却忘了勾选“应用于所有用户”
• 不建议用 gradle -g 临时指定，因为 IDEA、CI 脚本等场景不会自动继承该参数，容易漏配

IDEA 里 Gradle 工具窗口空白？不是 Gradle 问题，是插件或项目导入方式错了

很多人在 IDEA 里点开 Gradle 面板看到一片灰、Refresh 按钮不可点，第一反应是 Gradle 没装好，其实几乎全是 IDE 配置问题。

Gradle 9.8.0

下载

• 必须手动启用 Gradle 插件：Settings → Plugins → 搜索 Gradle → 确保状态是 Enabled → 重启 IDEA（仅刷新不生效）
• 不能用 Open 打开项目，必须用 Import Project，并在弹窗中**明确选择 Gradle** 作为构建工具——Auto-detect 经常失效，尤其多模块项目
• 删掉项目根目录下的整个 .idea 文件夹再重导，比调各种设置更省时间。旧缓存里可能还记着“这是 Maven 项目”，导致后续所有操作都被忽略

Gradle wrapper 是什么？为什么推荐用 ./gradlew 而不是全局 gradle

gradle 命令走的是你本地装的 Gradle，而 ./gradlew（Linux/macOS）或 gradlew.bat（Windows）是项目自带的启动脚本，它会自动下载并使用 gradle/wrapper/gradle-wrapper.properties 里声明的版本。

• 团队协作时，./gradlew build 能保证所有人用同一版 Gradle，避免“在我机器上是好的”类问题
• wrapper 脚本本身不依赖全局 Gradle 安装，哪怕你根本没配 PATH，只要 JDK 可用就能跑
• 首次运行 ./gradlew 会自动下载对应 zip 包到 GRADLE_USER_HOME/wrapper/dists/，后续复用，所以第一次略慢是正常的

关键点就两个：命令行 gradle -v 走通只是起点，IDEA 里能真正识别 build.gradle 并执行任务才算落地；wrapper 不是可选项，是工程化底线。