gradle-wrapper.properties文件必须严格位于项目根目录下的gradle/wrapper/子目录中，不可移动或改名；Android Studio、IntelliJ及gradlew脚本均硬编码查找该路径，误放至src/、app/或根目录将导致构建失败。
gradle-wrapper.properties 文件路径固定在 gradle/wrapper/
它必须放在项目根目录下的 gradle/wrapper/ 子目录中，不能随意移动或改名。
Android Studio、IntelliJ 或命令行执行 gradlew 时，都会硬编码查找这个路径。
- 如果项目里没有该文件，运行
gradle wrapper命令会自动生成整个gradle/wrapper/目录及其中的gradle-wrapper.properties和gradle-wrapper.jar - 手动创建时，路径必须严格为：
./gradle/wrapper/gradle-wrapper.properties（.表示项目根目录） - 常见误放位置：放在
src/下、app/下、或直接丢在根目录——这些都无效，gradlew会报错找不到 wrapper 配置
为什么改了 gradle-wrapper.properties 没生效
改动后不生效，大概率是以下情况之一：
-
gradlew脚本缓存了旧的distributionUrl：删掉~/.gradle/wrapper/dists/下对应版本的整个文件夹（含子目录），再重跑./gradlew --version - IDE（如 Android Studio）没触发 Sync：点击右上角 Sync Now，或手动执行
File → Sync Project with Gradle Files - 项目里存在多个
gradle-wrapper.properties（比如嵌套子项目）：确认你编辑的是最外层根项目的那个，不是某个 module 里的（module 下不该有 wrapper 目录） -
distributionUrl中的 URL 编码错误：例如https://写成https:/，或漏掉反斜杠转义（https\://中的\不可省）
distributionUrl 改本地路径时的坑
用 file:/// 指向本地 ZIP 包看似省事，但容易出问题：
- Windows 路径要三斜杠 + 反斜杠转义：
file:///D:/gradle/gradle-8.9-bin.zip（不能写file://D:\gradle...） - macOS/Linux 必须用绝对路径，且注意空格和特殊字符：建议用
file:///Users/you/Downloads/gradle-8.9-bin.zip，不要用~/ - ZIP 文件权限需可读；如果解压失败，
gradlew不会报明确错误，只会卡住或 fallback 到下载——此时检查~/.gradle/wrapper/dists/下是否生成了对应 hash 命名的空目录 - 本地 ZIP 若被杀毒软件锁定，会导致校验失败或静默跳过，建议临时关闭实时防护再试
真正稳定的做法，是把 distributionUrl 指向可信镜像（如阿里云），而不是依赖本地文件路径。路径错一个字符、少一个斜杠、多一个空格，gradlew 就不会按你想的走。
