Gradle版本已存在时gradlew仍下载Gradle的原因解析

核心原因 #

• Wrapper的设计初衷是构建环境一致性：Gradle Wrapper的核心目标是确保所有参与项目的环境（本地、CI、容器）使用完全一致的官方Gradle发行包，避免系统安装的Gradle可能存在的版本变种（比如包管理器精简版、自定义编译版）导致构建结果不一致。因此默认逻辑下，它不会自动复用系统已安装的Gradle。
• 系统Gradle与Wrapper的发行包结构不匹配：gradle:9.5.1-jdk25-alpine镜像中通过包管理器安装的Gradle，目录结构、附带组件可能和官方发行包有差异。Wrapper会校验发行包的完整性和结构，即使版本号相同，只要结构不符合预期，就会触发重新下载。
• 未启用系统Gradle复用配置：Wrapper默认没有开启复用系统Gradle的开关，必须显式配置才能让它优先尝试使用系统已安装的版本。

解决办法 #

• 运行时指定系统Gradle路径：执行Wrapper命令时，通过--gradle-home参数指定镜像中系统Gradle的安装路径（通常是/usr/lib/gradle）：

  ./gradlew --gradle-home /usr/lib/gradle build
  

• 修改Wrapper配置文件：在项目的gradle/wrapper/gradle-wrapper.properties中添加配置，开启系统Gradle复用：

  org.gradle.wrapper.use-system-gradle=true
  

• 直接使用系统Gradle：如果不需要Wrapper的环境一致性保障，可以跳过Wrapper，直接调用镜像中的系统Gradle命令：

  gradle build
  

内容的提问来源于stack exchange，提问作者Dragas