应填-all，因其包含源码和文档，支持IDE跳转、离线查文档及调试；-bin虽体积小、下载快，但缺失src/和docs/，导致跳转显示“decompiled”、无法查API实现、离线无文档等问题。
gradle-wrapper.properties 里 distributionUrl 应该填 -bin 还是 -all
填 -all 是更稳妥的选择，除非你明确知道自己不需要源码和文档。Gradle Wrapper 本身不关心你用的是 bin 还是 all，它只负责下载、校验、解压并执行；真正影响体验的是解压后目录里有没有 src/ 和 docs/。
常见错误现象包括：IDE（如 Android Studio）里 Ctrl+Click 跳转 Gradle DSL 方法时显示“decompiled”、构建失败时无法快速查某 Task 的源码实现、离线环境下找不到 User Guide 链接里的 API 说明——这些基本都源于用了 -bin 包。
-
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip→ 解压后只有bin/、lib/，无src/或docs/ -
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-all.zip→ 解压后含完整src/、docs/、samples/，体积约大 2–3 倍，但 IDE 支持、离线排障能力直接拉满 - AGP（Android Gradle Plugin）版本与 Gradle 版本有硬性对应关系，切勿只改 bin/all 后缀而忽略版本号匹配，例如 AGP 8.4 要求 Gradle 8.6，不能因为换成了
-bin就改成 8.5
CI 环境下用 -bin 更合适？
不一定。CI 构建机通常不依赖 IDE 跳转或本地文档，-bin 确实能节省下载带宽和磁盘空间，但代价是丧失调试能力——比如某次构建在 CI 上失败，而本地复现不了，这时如果 CI 用的是 -bin，你就没法直接登录机器进 GRADLE_USER_HOME/wrapper/dists/ 查源码或文档定位问题。
实际建议按角色区分：
- 开发机、构建基线机、插件开发者机器 → 固定用
-all，哪怕多占 100MB - 资源受限的 CI 节点（如临时云实例、内存 ≤2GB）→ 可用
-bin，但需确保构建日志足够详细，且团队有统一的本地-all环境用于交叉验证 - 镜像源同步脚本中应同时缓存
-bin和-all，避免因某类包缺失导致不同环境行为不一致
手动替换 wrapper 下载包后 gradlew 不生效？
Wrapper 不会自动识别你手动放进 GRADLE_USER_HOME/wrapper/dists/ 的 zip 文件，它只认自己下载并解压后的目录结构。如果你提前下载了 gradle-8.6-all.zip 并想跳过网络下载，正确做法是：
- 把 zip 文件放到
~/.gradle/wrapper/dists/gradle-8.6-all/xxxxx/（其中xxxxx是 distributionUrl 校验用的哈希值，可在gradle-wrapper.properties对应的distributionUrl后加?checksum=xxx查到，或运行一次./gradlew --version让它报错并打印路径） - 确保文件名严格为
gradle-8.6-all.zip，不能是gradle-8.6-all.zip.part或重命名过 - 解压后目录名必须是
gradle-8.6，不能是gradle-8.6-all或其他；Wrapper 启动时会检查该目录下是否存在bin/gradle - 删掉
~/.gradle/wrapper/dists/gradle-8.6-all/xxxxx/gradle-8.6-all.zip以外的同名残留文件，否则可能触发重复校验失败
为什么官方默认推荐 -all，但很多模板却悄悄换成 -bin
因为下载速度和稳定性。国内访问 services.gradle.org 时，-all 包（130MB+）经常卡在 99% 或校验失败，而 -bin（30MB 左右）成功率高得多。这不是设计缺陷，而是权衡结果：官方优先保障功能完整性，社区模板优先保障首次构建成功率。
但要注意，这种“降级”是有代价的：
- Android Studio 中对
build.gradle里android { }块内 DSL 的语义提示会变弱 - Gradle 自身任务（如
dependencies、help）输出的帮助文本里链接的文档地址会 404 - 使用
--debug时部分堆栈里类名无法映射到源码行号 - 某些旧版 IDE（如 IntelliJ 2022.3 之前）在加载
-bin后会静默禁用 Gradle DSL 源码跳转，不报错也不提示
真正容易被忽略的是：一旦项目长期用 -bin，团队成员会逐渐失去阅读 Gradle 源码的习惯和能力，遇到非标准插件或自定义 Task 行为异常时，第一反应是“网上搜”，而不是打开 src/core/src/main/java/org/gradle/... 看实现——这其实放大了问题排查成本。
