Roxi适用条件：从项目自带的 Wrapper 开始
适用于 Windows、macOS、Linux 上已有 Gradle Wrapper 的可信项目。资料按 2026-10-25 取得的官方文档核对，页面标识为 Gradle 9.8.2；项目实际版本以 gradle/wrapper/gradle-wrapper.properties 为准，不要求升级到文档所示版本。旧版参数先查对应版本手册。本文没有执行真实构建或设备网络测试。
使用普通用户终端，先保存本地改动并记录 JDK、项目目录、失败命令和报错中的主机名。Wrapper 脚本和项目构建逻辑会在本机执行，只在自己信任的项目中操作。下载会写入 Gradle 用户目录，后续构建还会产生项目缓存与输出。
第一步：分清是哪一次下载失败
| 观察位置 | 说明 | 下一步 |
|---|---|---|
| Downloading…gradle-…zip | Wrapper 尚在取得 Gradle 发行包 | 检查 distributionUrl 对应地址和下载路径 |
| Gradle 已启动，随后依赖解析失败 | 到了插件或项目依赖获取阶段 | 记录失败仓库与坐标，核对 JVM 代理 |
| 离线模式提示缺少依赖 | 本地缓存不够 | 恢复网络后取消该次 --offline 再试 |
| 401 / 403 或证书校验失败 | 可能是认证、权限或信任链问题 | 保留原文，交由仓库或网络管理员核对 |
./gradlew --version如果发行包未缓存，这一步也可能联网下载。若能显示 Gradle 与 JVM 版本，只能说明 Wrapper 能启动；若发行包早已缓存，不能据此宣布下载链路正常。保持 distributionUrl 和 distributionSha256Sum 原样，不用更换不明镜像或删除校验值来消除错误。
第二步：找到真正生效的 gradle.properties
- 查看是否设置了 GRADLE_USER_HOME；没有定制时查看个人用户目录下的 .gradle。只检查代理相关键，避免复制整个含凭据的文件。
- 对照用户目录、项目根目录中的 gradle.properties。官方说明用户级属性优先于项目级；项目文件写对了，也可能被用户级旧值覆盖。
- 多项目构建的 systemProp 应放在根项目配置中；子项目中的同类项会被忽略。先备份实际要改的文件，并记下每个原值。
第三步：按代理协议填写，主机字段不带 URL 前缀
下面适用于本机已有 HTTP 或 mixed 代理入口，且该入口支持 HTTP CONNECT。把 PORT 换成客户端显示的实际十进制端口；它不是固定默认值。127.0.0.1 指运行 Gradle 的这台机器，远程开发和容器不能直接套用宿主机地址。
systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=PORT
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=PORTHTTP 与 HTTPS 目标各有一组 JVM 属性；proxyHost 只填主机，不能填 http://127.0.0.1。若要让确认可直连的内部仓库绕过代理，按已有策略维护 http.nonProxyHosts，多个模式用竖线分隔；HTTPS 也使用这个 http.nonProxyHosts 键。SOCKS 使用另一组配置，不能把 SOCKS 专用端口当 HTTP 端口。
第四步：复测原任务，区分缓存成功和网络成功
- 先重复 --version，再用原来失败的构建命令复测，检查失败是否从 Wrapper 转移到了具体仓库。不要替换为与原问题无关的空项目。
- 确认原命令没有 --offline。离线成功只能证明缓存够用，不能证明仓库能访问；离线失败也不必然表示代理坏了。
- 只在网络已恢复、仍怀疑缓存元数据过旧时，为原命令追加 --refresh-dependencies。它会重新核对依赖，但可能复用校验一致的文件，并不保证重新下载所有包。
预期结果是原构建越过同一失败步骤，完成原任务；同时记录实际仓库与是否发生请求。仅显示版本或命中缓存不算网络验收。若仍失败，按发行包、插件、项目依赖三个阶段整理失败主机、HTTP 状态或证书错误。
回退与求助信息
恢复刚才备份的配置，或者仅撤销本次新增的键，再重复同一任务。不要删除整个 .gradle 缓存，否则会扩大后续下载量。提交求助时给出 Wrapper 版本、JDK、配置文件位置和脱敏错误；保留证书校验，把证书链问题交给对应网络或仓库管理员处理。