Android Gradle 依赖下载失败：常见原因及解决方案

Question

Android Gradle 依赖下载失败是日常开发中高频痛点：常见表现为 `Could not resolve androidx.core:core-ktx:1.12.0` 或 `Connection timed out` 等错误。根本原因通常包括：① 国内网络无法直连 Google Maven（如 maven.google.com）或 JCenter（已关停）；② 项目配置了失效/未同步的镜像仓库（如旧版阿里云仓库地址已变更）；③ Gradle 版本与 Android Gradle Plugin（AGP）不兼容，导致依赖解析逻辑异常；④ 本地 Gradle 缓存损坏（`.gradle/caches/` 中的 module-metadata 或 artifact 文件异常）；⑤ 企业防火墙或代理设置干扰 HTTPS 连接（尤其 TLS 1.3 协商失败）。这些问题常被误判为“网络慢”，实则多源于配置失配或生态迁移（如从 JCenter 迁移至 Maven Central）未同步更新。精准定位需结合 `--info` 日志分析实际请求 URL 与响应状态，而非盲目重试或清缓存。

Answer 1

```html

一、现象层：典型错误日志与表象识别

开发者首次遭遇时，常看到如下高频报错：

• Could not resolve androidx.core:core-ktx:1.12.0
• Connection timed out while downloading https://maven.google.com/...
• Could not HEAD 'https://jcenter.bintray.com/...' - Connection refused（JCenter 已于 2021 年 2 月彻底关停）
• Failed to list versions for com.squareup.okhttp3:okhttp（元数据解析失败）

这些错误看似“网络问题”，实则90%以上源于配置链断裂，而非带宽不足。

二、配置层：仓库声明与生态迁移适配

自 AGP 7.0+ 起，build.gradle 中的仓库配置必须显式声明且符合新规范。常见失效配置示例：

旧写法（已失效）	新写法（推荐）
maven { url 'https://maven.aliyun.com/repository/google' }	maven { url 'https://maven.aliyun.com/repository/public' } + google()
jcenter()（无条件启用）	// jcenter() 已移除，不可再用

阿里云等镜像站已于2023年起统一归并至 https://maven.aliyun.com/repository/public，旧 Google 专用镜像地址返回 404。

三、兼容层：Gradle 与 AGP 版本协同矩阵

版本错配是静默失败主因。以下为 2024 年主流组合兼容性验证（依据 Android 官方兼容表）：

AGP 8.4.0 → Gradle 8.6+（强制要求 TLS 1.3，禁用 TLS 1.2 回退）
AGP 8.2.0 → Gradle 8.2–8.4（若用 Gradle 8.5+，需手动添加 systemProp.javax.net.debug=ssl:handshake）
AGP 7.4.2 → Gradle 7.5–8.0（不支持 Gradle 8.1+ 的 module metadata v2 协议）

使用 ./gradlew --version 和 gradle-wrapper.properties 双校验，缺一不可。

四、诊断层：精准定位依赖解析路径

执行以下命令获取真实请求链路：

./gradlew app:dependencies --configuration debugRuntimeClasspath --info 2>&1 | grep -E "(Resolving|Downloading|GET|HEAD|HTTP.*[45]\d\d)"

关键线索包括：

• 实际发起请求的 URL（是否仍指向 jcenter.bintray.com？）
• HTTP 状态码（HTTP/1.1 403 Forbidden 表示镜像未授权；HTTP/1.1 302 后无重定向说明 DNS 或中间件拦截）
• TLS 握手日志（含 Extension: supported_versions (len=5): [TLSv1.3] 则确认启用）

五、缓存层：选择性清理与元数据修复策略

盲目 rm -rf ~/.gradle/caches/ 效率低下且易引发二次污染。推荐分步操作：

1. 仅清除模块元数据：find ~/.gradle/caches/ -name "*.module" + rm -f
2. 重建解析索引：./gradlew --refresh-dependencies --no-daemon
3. 验证缓存完整性：ls -la ~/.gradle/caches/modules-2/metadata-*/descriptors/（应含非空 .bin 文件）

六、网络层：企业环境 TLS 与代理深度调优

在金融/政企内网中，常见 TLS 1.3 协商失败。解决方案包括：

• 强制降级（临时调试）：org.gradle.jvmargs=-Djdk.tls.client.protocols=TLSv1.2
• 代理证书信任：keytool -importcert -file corp-ca.crt -keystore $JAVA_HOME/lib/security/cacerts
• 绕过特定域名（如 maven.google.com）：systemProp.http.nonProxyHosts="*.corp.com|localhost"

七、架构层：构建可审计的依赖治理流程

面向中大型团队，建议引入自动化检查机制：

graph LR
A[CI Pipeline] --> B{Gradle Properties Check}
B -->|缺失 mavenCentral\|google| C[Fail Build]
B -->|含 jcenter\|mavenCentralLegacy| D[Warn & Auto-Replace]
D --> E[生成 migration-report.md]
E --> F[推送至 GitLab MR 插件]

结合 gradle-versions-plugin 与自定义 RepositoryEnforcer Task，实现仓库策略代码化。

八、演进层：面向 Maven Central 统一生态的长期实践

JCenter 关停后，Maven Central 成为事实标准。但需注意：

• Google 已将 androidx.* 全量同步至 Maven Central（2023 Q3 起），google() 仓库非必需
• 第三方库若未发布至 Central，需联系作者或使用 jitpack.io（需验证 PGP 签名）
• 推荐最小化仓库集：mavenCentral() + google()（仅用于尚未同步的极少数组件）

所有新项目应默认禁用 jcenter() 并移除相关历史残留。

```