报错“找不到或无法加载主类 org.gradle.wrapper.GradleWrapperMain”本质是 gradle-wrapper.jar 文件缺失；该 JAR 包含启动类，被 gradlew 脚本依赖，缺失则 JVM 无法启动；常见于 Git 克隆遗漏、手动删除、CI/CD 未拷贝等场景。
直接结论：报错 找不到或无法加载主类 org.gradle.wrapper.GradleWrapperMain，基本等于告诉你——gradle-wrapper.jar 文件丢了，不是配置错、不是路径错、不是版本不兼容，就是这个 JAR 包根本不在 gradle/wrapper/ 目录下。
为什么 gradle-wrapper.jar 缺失会导致这个错误
GradleWrapperMain 是一个位于 gradle-wrapper.jar 内部的启动类，gradlew 脚本靠它来加载并运行 Gradle。没有这个 JAR，脚本连入口都找不到，JVM 自然报“找不到主类”。常见于：
• 项目从 Git 克隆后漏掉了 gradle/wrapper/ 下的二进制文件（.gitignore 误配）
• 手动删过 gradle/ 目录想“轻量化”项目
• Jenkins 或 Docker 构建时未把该 JAR 拷贝进工作目录
• Flutter/Android 项目中只复制了 android/ 子目录，但没带根目录下的 gradle/
快速补救：优先检查并补全 gradle-wrapper.jar
进入你项目的根目录，执行：
ls -l gradle/wrapper/
如果输出里没有 gradle-wrapper.jar，就确认缺失。此时最省事的做法是：
- 从另一个能正常构建的 Gradle 项目（比如 Android Studio 新建的空项目）中，复制
gradle/wrapper/gradle-wrapper.jar到当前项目的同路径下 - 确保同时存在
gradle-wrapper.properties（否则会报下载失败），内容至少包含distributionUrl配置 - Windows 下记得保留
gradlew.bat，macOS/Linux 下确保gradlew有可执行权限：chmod +x gradlew
补完后，在终端直接运行 ./gradlew --version，能打印出 Gradle 版本即表示恢复成功。
更稳妥的长期方案：用 wrapper 任务自动生成整套文件
手动拷贝容易版本错配（比如用 8.4 的 JAR 配 7.0 的 properties）。推荐用官方方式重建：
- 确保本地已安装某个版本的 Gradle（任意能跑
gradle wrapper的版本即可） - 在项目根目录运行：
gradle wrapper --gradle-version 8.5 --distribution-type bin（按需替换版本号） - 命令会自动生成完整的
gradle/目录结构，包括.jar、.properties、gradlew、gradlew.bat - 生成后务必提交全部四个文件到 Git，避免下次又丢
注意：gradle 命令必须可用；若提示 command not found，说明本地没装 Gradle，此时只能先手动拷贝再补。
IDE 同步与 CI 环境特别提醒
即使本地修复好了，IntelliJ IDEA / Android Studio 仍可能缓存旧状态：
- 点击右上角
Sync Project with Gradle Files强制刷新 - 检查
File → Settings → Build → Gradle中是否勾选Use Gradle from wrapper - Jenkins 或 GitHub Actions 中，确保
gradle/wrapper/目录被完整检出，不要用git sparse-checkout过滤掉它 - Docker 构建时，
COPY . .必须覆盖gradle/，不能只 COPYbuild.gradle等文本文件
最容易被忽略的是：很多人以为只要 gradle-wrapper.properties 存在就够了，其实 gradle-wrapper.jar 才是真正的执行载体——它小（几百 KB）、不可替代、且极难从源码编译，丢了就得补，没别的捷径。
