Gradle同步会失败，因.gitignore忽略/gradle目录导致gradle-wrapper.jar缺失，使./gradlew无法启动；Wrapper四文件（gradlew、gradlew.bat、gradle-wrapper.jar、gradle-wrapper.properties）必须共存且版本匹配，缺一则构建中断。
gradle-wrapper.jar 被 .gitignore 忽略后会怎样
Android Studio 新建项目默认的 .gitignore 模板里常含 /gradle 这一行，它会把整个 gradle/ 目录（含 gradle/wrapper/gradle-wrapper.jar）一并排除。一旦这个 .jar 文件没进仓库，其他协作者 clone 后执行 ./gradlew build 就会直接报错：Could not load wrapper properties 或更隐蔽的 NoClassDefFoundError: org/gradle/wrapper/GradleWrapperMain —— 因为脚本根本找不到主类。
为什么 gradle-wrapper.jar 不能靠“重新生成”补救
gradle wrapper 命令确实能生成新 Wrapper，但它依赖本地已安装的 Gradle 版本，而该版本很可能和项目要求的不一致。比如项目 gradle-wrapper.properties 写着 gradle-8.0-bin.zip，但你本地装的是 gradle-8.5，运行 gradle wrapper 就会生成指向 8.5 的配置，破坏构建一致性。
- 生成命令不会读取现有
gradle-wrapper.properties，而是按当前 Gradle 版本推导 - 即使手动指定
--gradle-version 8.0，生成的gradle-wrapper.jar仍是新版打包逻辑，可能与旧版properties中的zipStorePath等字段行为不兼容 - CI 流水线通常禁用全局 Gradle，只认
gradlew，没有.jar就彻底卡死
哪些文件必须一起提交，缺一不可
Wrapper 是一个原子性单元，四个文件必须同时存在且版本匹配：
-
gradlew（Unix shell 脚本） -
gradlew.bat（Windows 批处理） -
gradle/wrapper/gradle-wrapper.jar（核心逻辑，含下载器和启动器） -
gradle/wrapper/gradle-wrapper.properties（声明 distributionUrl、路径等，必须和 jar 编译时目标一致）
单独漏掉 .jar，就等于交了一张只有说明书没有发动机的汽车图纸——脚本知道要干什么，但根本动不了。
如何快速验证 Wrapper 是否完整
在项目根目录运行以下检查，比等 AS 同步失败再排查快得多：
-
ls -l gradlew gradlew.bat—— 确认两个启动脚本存在且有可执行权限（Unix 下gradlew需x权限） -
ls -l gradle/wrapper/gradle-wrapper.jar gradle/wrapper/gradle-wrapper.properties—— 二者必须都存在 -
file gradle/wrapper/gradle-wrapper.jar—— 输出应含Java archive data，不是空文件或 HTML（常见于被重定向的错误 URL 下载）
真正容易被忽略的是：即使所有文件都在，如果 gradle-wrapper.jar 是从错误镜像或篡改源下载的，它仍会在首次运行时静默失败——此时 ./gradlew --version 会卡住或抛出 ClassNotFoundException，而不是报路径错。
