必须提交gradlew、gradlew.bat和gradle-wrapper.properties这三个文件,因为它们构成Gradle Wrapper运行的最小依赖:前两者是跨平台启动脚本,负责调用Java执行构建;后者通过distributionUrl声明所需Gradle版本,确保环境一致;缺一不可。

必须提交 gradlew、gradlew.bat 和 gradle/wrapper/gradle-wrapper.properties 这三个文件,其余 gradle/wrapper/ 下的文件(如 gradle-wrapper.jar)可不提交,但实际中绝大多数团队都一并提交以避免权限或下载失败问题。
为什么只提这三个是底线
Gradle Wrapper 的运行依赖三要素:启动脚本(gradlew / gradlew.bat)和版本声明(gradle-wrapper.properties)。前者负责解析参数、检查缓存、调用 Java 启动 Gradle;后者里的 distributionUrl 决定了该拉哪个版本的二进制包。只要这三者存在且内容正确,任何没装 Gradle 的机器执行 ./gradlew build 就能自动下载并构建。
至于 gradle-wrapper.jar,它理论上可由 Wrapper 脚本在首次运行时从 distributionUrl 下载生成,但实践中常因网络策略、代理限制或 CI 环境无外网而失败——所以几乎所有规范项目(包括 Android Studio 默认模板、Google 官方示例、Gradle 官网指南)都把它一并纳入 Git。
gradle/wrapper/ 目录下哪些文件可以不提交
以下文件属于本地运行时生成或缓存产物,**绝对不能提交**:
使用 GitHub Next 的 CI Doctor 工作流来监视 GitHub Actions 运行、拉取失败日志、追踪重复模式,并打开带有具体下一步操作的调查问题。这是供代理作为 CI 失败调查员使用的,而不是用于将 GitHub Agentic Workflows 列为产品。
-
gradle/wrapper/gradle-wrapper.jar.lock(Gradle 8.4+ 引入的锁文件,纯临时) - 任何以
.tmp、.lock或~结尾的隐藏文件 -
gradle/wrapper/dists/子目录(这是下载解压后的 Gradle 安装包,体积大且平台相关)
注意:gradle/wrapper/ 本身是空目录,Git 不会跟踪空目录;只要里面放了 gradle-wrapper.jar 和 gradle-wrapper.properties,目录就会被纳入版本控制。
常见错误:误提交 .gradle/ 或 build/
这两个目录完全无关 Wrapper,却常被新手一起拖进 Git:
-
.gradle/是本地构建缓存(含 Daemon 状态、依赖 jar、插件元数据),含绝对路径和机器信息,跨机器不可复用 -
build/是每次执行./gradlew生成的输出(APK、R.java、class 文件等),属于纯产物 - 它们都在标准
.gitignore里被明确忽略,若已误提交,需用git rm -r --cached .gradle清除追踪
Android Studio 新建项目默认是否合规
是的,AS 2023.2+ 创建的新项目默认已正确配置:
-
gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.properties、gradle/wrapper/gradle-wrapper.jar全部在 Git 待提交列表中 -
.gitignore已包含.gradle/、local.properties、build/、captures/等关键条目 - 唯一需人工确认的是
gradle-wrapper.properties中的distributionUrl是否指向组织内允许的镜像(如内网 Nexus),而非默认的services.gradle.org
真正容易被忽略的点是:团队共用 Wrapper 但未同步 gradle-wrapper.jar —— 某人本地更新了 Wrapper 版本(比如执行了 ./gradlew wrapper --gradle-version 8.10),却只提交了 .properties,忘了 .jar,结果其他人拉代码后首次运行卡在下载失败。这个细节比语法或路径更影响日常协作节奏。

















