Java配置Gradle Wrapper及依赖管理指南

gradlew 命令不识别需先生成 Wrapper；依赖不生效常因插件未启用或仓库配置缺失；Spring Boot 应优先用 spring-boot-gradle-plugin 而非手动 dependencyManagement；构建慢与 wrapper 无关，应优化 Gradle 缓存和并行配置。

gradlew 命令不识别？先确认 wrapper 是否已生成

很多开发者执行 ./gradlew build 时提示 Command not found，根本原因往往是项目根目录下压根没有 gradlew（Linux/macOS）或 gradlew.bat（Windows）文件。Gradle Wrapper 不是自动存在的，必须显式生成。

• 在已有 Gradle 项目的根目录下，运行 gradle wrapper（需本地已安装 Gradle）
• 若未安装 Gradle，可直接下载二进制包解压后将 bin 目录加入 PATH，或使用 SDKMAN!： sdk install gradle
• 生成后会新增四个文件：gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar、gradle/wrapper/gradle-wrapper.properties
• gradle-wrapper.properties 中的 distributionUrl 决定了项目使用的 Gradle 版本，例如：https\://services.gradle.org/distributions/gradle-8.5-bin.zip

build.gradle 中声明依赖为何不生效？检查插件与仓库配置

依赖写对了，但编译报 Cannot resolve symbol 或 Could not find artifact，大概率是 build.gradle 缺少关键配置项，尤其在较新版本 Gradle（8.0+）中变化明显。

• 必须启用 Java 插件：plugins { id 'java' }（Kotlin DSL 是 plugins { java }）
• 仓库不能只写 mavenCentral() —— Gradle 8.4+ 默认禁用 jcenter()，且部分国内镜像需显式配置 URL，例如阿里云：maven { url 'https://maven.aliyun.com/repository/public' }
• 依赖必须放在 dependencies 块中，且注意作用域：implementation（编译+运行时）、testImplementation（仅测试）、runtimeOnly（仅运行时）
• 如果用了 Kotlin，还需加 id 'org.jetbrains.kotlin.jvm' version '1.9.20' 并确保 kotlin("jvm") 插件和 Kotlin 标准库依赖匹配

dependencyManagement 和 spring-boot-dependencies 冲突？别混用两种机制

Spring Boot 项目常误以为 dependencyManagement 块能替代 spring-boot-starter-parent 的 BOM 管理能力，结果导致版本错乱、重复引入、甚至启动失败。

• Spring Boot 官方推荐方式是继承 spring-boot-starter-parent（Maven）或使用 org.springframework.boot:spring-boot-gradle-plugin（Gradle），它会自动导入 spring-boot-dependencies BOM
• 手动写 dependencyManagement 块（Gradle 中为 dependencyManagement { imports { mavenBom(...) } }）仅适用于非 Spring Boot 项目，或需要覆盖特定 BOM 的场景
• 若同时用了 spring-boot-gradle-plugin 和自定义 dependencyManagement，后者可能覆盖前者管理的版本，引发 NoClassDefFoundError 或 MethodNotFound
• 验证是否生效：运行 ./gradlew dependencies --configuration runtimeClasspath，查看实际解析出的版本是否符合预期

./gradlew build 太慢？wrapper 和依赖缓存其实各自独立

很多人以为删掉 gradle/wrapper 能提速，其实完全无关——wrapper 只负责下载和启动对应 Gradle 实例；真正影响构建速度的是 Gradle 自身的缓存（~/.gradle/caches/）和项目级构建缓存（.gradle/）。

• 首次运行 ./gradlew build 会下载 Gradle 发行版（由 gradle-wrapper.properties 指定），之后复用本地 ~/.gradle/wrapper/dists/ 下的 zip 解压内容
• 依赖 jar 包缓存在 ~/.gradle/caches/modules-2/files-2.1/，不会因 wrapper 变化而失效
• 加速建议：在 gradle.properties 中启用构建缓存（org.gradle.caching=true）和并行构建（org.gradle.parallel=true）
• CI 场景下务必保留 ~/.gradle/caches/ 目录，否则每次都是冷启动，耗时翻倍

Wrapper 的核心价值不是“自动管理依赖”，而是锁定 Gradle 版本——哪怕团队成员本地装的是 Gradle 7.x 或 9.x，只要运行 ./gradlew，就一定用项目指定的 8.5。依赖管理的逻辑全在 build.gradle 和插件行为里，wrapper 本身不参与解析、下载或冲突解决。