Gradle Wrapper 出现ClassNotFound异常的原因及解决办法

我之前也踩过这个一模一样的Gradle Wrapper坑——解压后的目录结构全对，gradle-wrapper.jar也在，但每次运行就是报Could not find or load main class org.gradle.wrapper.GradleWrapperMain的错。折腾了好一阵，总结出几个最可能的原因和修复方法，你可以逐个排查：

1. gradle-wrapper.jar文件损坏或不完整 #

这是最常见的原因！有时候压缩包打包时出问题，或者解压工具（比如某些批量解压脚本）跳过了二进制文件的完整提取，导致gradle-wrapper.jar看起来存在，但实际内容残缺。

• 修复步骤：
  • 对比解压后的gradle-wrapper.jar和你本地执行gradle wrapper生成的正常jar文件大小，如果差距很大，肯定是损坏了。
  • 直接用正常的jar文件替换解压目录里的对应文件；或者在你的解压脚本里添加哈希校验逻辑（比如用sha256sum），确保解压后的文件和原压缩包里的一致，不一致就重新解压。

2. 脚本执行Gradle Wrapper的路径不对 #

虽然目录结构正常，但如果你的脚本执行gradlew时，当前工作目录不是解压后的项目根目录，Gradle就找不到wrapper的相关文件，间接报主类找不到的错。

• 修复步骤：
  • 在脚本里明确切换到解压后的目录再执行命令，比如：

    cd /绝对路径/到/解压后的目录
    ./gradlew build
    

  • 或者直接用绝对路径调用wrapper脚本：

    /绝对路径/到/解压后的目录/gradlew build
    

3. gradle-wrapper.properties配置错误 #

gradle/wrapper/gradle-wrapper.properties里的distributionUrl如果配置无效，或者本地缓存的Gradle发行版损坏，也会导致wrapper无法正常初始化，表面上就表现为找不到主类。

• 修复步骤：
  • 打开gradle-wrapper.properties，检查distributionUrl是否是有效的Gradle发行版地址，比如：

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

  • 如果本地缓存有问题，删除用户目录下的.gradle/wrapper/dists文件夹，然后重新执行./gradlew，让它重新下载正确的Gradle发行版。

4. Java环境不兼容或配置错误 #

不同版本的Gradle对Java版本有要求（比如Gradle 8.x需要Java 11及以上），如果你的脚本用的Java版本不符合要求，或者JAVA_HOME指向了错误的JDK，也会出现类加载失败的问题。

• 修复步骤：
  • 用java -version检查当前Java版本，确认和你使用的Gradle版本兼容。
  • 在脚本里明确设置JAVA_HOME指向兼容的JDK，比如：

    export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
    ./gradlew build
    

5. 文件权限问题（Linux/macOS下） #

如果是在类Unix系统上，gradlew脚本可能没有执行权限，或者gradle-wrapper.jar没有读权限，导致无法正常读取和执行。

• 修复步骤：
  • 给gradlew添加执行权限：

    chmod +x /绝对路径/到/解压后的目录/gradlew
    

  • 确保gradle-wrapper.jar有读权限：

    chmod +r /绝对路径/到/解压后的目录/gradle/wrapper/gradle-wrapper.jar
    

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