1. Android Gradle 构建报错到底卡在哪：从依赖下载失败到请求链路验证
Android 项目里最让人血压升高的场景，往往不是业务代码写不出来，而是点下 Sync 或 Run 之后，Gradle 直接甩出一屏红字。你明明没改几行代码，昨天还能跑，今天换了个网络环境、换了台机器，或者同事拉了你刚推的分支，构建就挂了。这类问题在 Android 异常解决方法里占比非常高，因为它横跨了网络、缓存、依赖版本、仓库配置、JDK 版本、Gradle 插件版本好几个层面，报错信息又经常只给一个笼统的Could not resolve或者Connection timed out。
先明确这篇内容适合谁：如果你正在被Could not download xxx.jar、Could not GET 'https://xxx'、Failed to resolve: com.xxx:xxx、Read timed out、Connect to repo.maven.apache.org refused这类报错卡住，或者你团队里多个人的构建结果不一致，那这篇就是给你写的。核心检索词就是 Android Gradle 构建报错排查，我会把定位思路拆成可复制的步骤，而不是只告诉你「换个仓库就好了」。
Gradle 构建的本质，是它要按照settings.gradle和build.gradle里声明的仓库地址，去远程拉取依赖的 POM 和 AAR/JAR 文件，然后做依赖解析、版本对齐、缓存写入。只要这条链路上任何一环出问题，构建就会失败。链路大致是：Gradle Daemon 启动 → 读取仓库配置 → 发起 HTTP(S) 请求 → 下载元数据 → 解析依赖树 → 下载产物 → 写入本地缓存 → 编译。报错发生在哪一步，决定了你该往哪个方向查。
很多人一看到报错就去删.gradle缓存、重启 Android Studio，这属于「大力出奇迹」，偶尔有效但不可复现。更靠谱的做法是先看报错的第一行和Caused by，区分它到底是网络问题、缓存问题，还是依赖冲突问题。这三类的表现和解决路径完全不同：
网络类报错通常带Connection timed out、Read timed out、Could not GET、Unknown host，说明请求根本没成功到达仓库或者响应超时。缓存类报错常见Could not find xxx、Cached version not found、Metadata file not found，说明本地缓存里的元数据和远程对不上。依赖冲突类则是Duplicate class、Conflict with dependency、Program type already present，说明多个库引入了同一个类的不同版本。
我实测下来，最容易被忽略的是「请求链路本身是否通」这个问题。很多开发者默认「我浏览器能打开网页，所以网络没问题」，但 Gradle 走的是 JVM 的 HTTP 客户端，代理配置、DNS、TLS 版本、证书信任链都可能和浏览器不一样。所以排查的第一步，不是改代码，而是确认 Gradle 发出的请求到底能不能通、通到哪里、返回了什么。
这里就引出一个很实用的思路：把「依赖下载」和「模型/接口请求」分开验证。Android 项目现在越来越多会接入大模型能力，比如在构建脚本里做代码检查、在 App 里调用模型接口。如果依赖下载和接口请求同时出问题，你会很难判断是网络整体不通，还是某个服务不可达。借助一个统一的 Key/API 通道，可以先把「请求链路」这件事单独验证掉，确认网络出口和鉴权没问题，再回头专心查 Gradle 依赖。
TaoToken 在这里的角色，就是提供一个统一的 API 入口，让你用同一个 Key 去验证请求链路是否正常。它的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置的时候直接用这个就行。你可以把它理解成一个「请求链路的探针」：当 Gradle 报网络错的时候，先用它确认你的机器能不能正常发出 HTTPS 请求并拿到响应，这样就能快速排除「是不是整个网络出口都挂了」这种大范围问题。
举个实际场景：你公司内网对某些域名做了限制，Gradle 拉google()仓库超时，但你不确定是仓库被限了还是整个外网都不通。这时候用 TaoToken 的模型对话接口发一个最简单的请求，如果它能正常返回，说明你的网络出口和 TLS 握手是好的，问题就缩小到「特定仓库域名不可达」；如果它也超时，那说明是整体网络问题，改仓库地址也没用。这个区分动作能帮你省下大量瞎试的时间。
所以这一节的结论是：Android Gradle 构建报错，先别急着改配置，先做链路分层。把「网络是否通」「缓存是否脏」「依赖是否冲突」三件事分开验证，再针对性处理。下一节我会讲怎么把 TaoToken 的 Key 和请求配置准备好，作为链路验证的前置步骤。
2. TaoToken 前置准备：拿到 Key 并配好请求链路验证环境
在开始改 Gradle 配置之前，我建议先把请求链路验证的环境搭好。原因很简单：后面排查网络类报错时，你需要一个「确定能通」的参照物。如果连参照物都没有，你改完仓库地址也不知道是真的修好了，还是碰巧缓存命中了。
TaoToken 的接入准备分三步：拿 Key、确认 Base URL、选一个 Model ID。这三件套在后面的 Gradle 配置和验证请求里都会用到，所以先统一说清楚。
第一步，打开控制台创建 API Key。地址是 https://taotoken.net/console ，登录后进入 API Keys 页面，新建一个 Key 并复制保存。注意 Key 只在创建时完整显示一次，关掉页面就看不到了，所以一定要先存到安全的地方。如果你只是做链路验证，可以给这个 Key 起个容易识别的名字，比如android-gradle-debug，方便后面区分用途。
第二步，确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api ，所有请求都基于这个地址拼接。比如模型对话的完整路径是https://taotoken.net/api/v1/chat/completions，具体以接入文档为准。文档地址在 https://taotoken.net/doc ，里面会列出当前支持的模型和对应的 Model ID。配置的时候 Base URL 填https://taotoken.net/api，不要自己加/v1或者结尾斜杠，避免路径拼接出错。
第三步，选 Model ID。不同模型对应不同的 ID 字符串，比如常见的对话模型、代码模型都有各自的标识。你可以在文档里找到当前可用的列表，选一个你常用的就行。做链路验证不需要挑最强的模型，选一个响应快的即可。如果你后面要做长期编码或者 Agent 类任务，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan ，它更适合高频调用场景。
把这三件套准备好之后，先别急着写进 Gradle。先用一个最简单的命令行请求验证一下，确认 Key 和 Base URL 是对的。可以用 curl 发一个最小请求：
curl -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer 你的API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的Model_ID", "messages": [ {"role": "user", "content": "ping"} ] }'如果返回里能看到choices字段和一段回复内容，说明请求链路是通的，Key 和 Base URL 都没问题。如果返回 401，说明 Key 不对或者没带上；如果返回超时，说明网络出口有问题；如果返回 404，说明路径拼错了。这一步的返回结果，就是你后面排查 Gradle 网络问题的基准线。
这里要提醒一个容易踩的坑：不要把 Key 硬编码到会提交到 Git 的文件里。Gradle 项目里经常有local.properties或者gradle.properties，这些文件如果被提交，Key 就泄露了。正确做法是把 Key 放在环境变量或者不纳入版本控制的本地文件里，构建脚本通过读取环境变量来获取。比如在~/.gradle/gradle.properties里写，或者用 CI 的 Secret 管理。
另外，如果你用的是 Claude Code 这类工具做辅助开发，它的配置也需要 Base URL、Key、Model ID 三件套。Claude Code 的接入文档在 https://taotoken.net/doc ，里面有专门的配置说明。配置的时候同样是 Base URL 填https://taotoken.net/api，Key 用你刚创建的，Model ID 按文档选。这样你的命令行工具和 Gradle 构建脚本就能共用同一套鉴权信息，排查问题时也更容易统一。
准备好这些之后，你就有了一个「确定能通」的请求通道。接下来在 Gradle 报网络错的时候，先用这个通道发一个请求，就能快速判断是整体网络问题还是特定仓库问题。下一节我会给出可复制的 Gradle 配置片段，包括仓库镜像、超时设置、缓存策略，以及怎么把请求链路验证嵌进构建流程。
3. 可复制的 Gradle 配置片段：仓库、超时、缓存与请求链路验证
这一节是实操核心。我会给出可以直接复制到项目里的配置片段，覆盖仓库声明、超时设置、缓存策略，以及一个可选的请求链路验证任务。所有片段都基于 Gradle 7.x 及以上版本，Kotlin DSL 和 Groovy DSL 都会给，你可以按项目实际情况选。
先看仓库配置。Android 项目默认会用google()和mavenCentral()，但在网络受限的环境下，这两个仓库经常超时。解决办法是在settings.gradle里做仓库集中管理，并加上超时和重试。Gradle 7 之后推荐用dependencyResolutionManagement统一声明仓库，而不是在每个模块的build.gradle里重复写。
Groovy DSL 版本，放在settings.gradle：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url = uri("https://maven.aliyun.com/repository/public") allowInsecureProtocol = false } } }Kotlin DSL 版本，放在settings.gradle.kts：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url = uri("https://maven.aliyun.com/repository/public") isAllowInsecureProtocol = false } } }这里加了阿里云的公共镜像作为补充，它在国内访问通常更稳定。注意allowInsecureProtocol要设为 false，避免用 HTTP 明文仓库。如果你的项目有私有仓库，也在这里加，顺序上把响应快的放前面，Gradle 会按顺序尝试。
接下来是超时和重试配置。Gradle 默认的超时时间比较长，网络不好时会卡很久。可以在gradle.properties里调整：
# 网络请求超时，单位毫秒 systemProp.org.gradle.internal.http.connectionTimeout=30000 systemProp.org.gradle.internal.http.socketTimeout=30000 # 依赖下载重试次数 systemProp.org.gradle.internal.repository.max.retries=3 systemProp.org.gradle.internal.repository.initial.backoff=500 # 开启并行下载和缓存 org.gradle.parallel=true org.gradle.caching=true org.gradle.daemon=true这几个参数的作用：connectionTimeout控制建立连接的超时，socketTimeout控制读取响应的超时，max.retries控制失败重试次数，initial.backoff控制重试间隔。把超时设成 30 秒是个折中值，太短会误判，太长会卡住。重试 3 次能覆盖大部分偶发网络抖动。
然后是缓存策略。Gradle 的依赖缓存默认在~/.gradle/caches/modules-2，如果缓存损坏或者元数据过期，会出现「远程有但本地找不到」的怪现象。可以在需要时强制刷新：
# 强制刷新依赖，忽略缓存 ./gradlew --refresh-dependencies assembleDebug # 清理构建缓存 ./gradlew clean # 查看依赖树，定位冲突 ./gradlew :app:dependencies --configuration debugRuntimeClasspath--refresh-dependencies会重新检查远程元数据，适合怀疑缓存脏了的场景。dependencies任务能打印完整的依赖树，冲突和版本对齐问题一目了然。
现在说请求链路验证。你可以在app/build.gradle里加一个自定义任务，用 TaoToken 的接口做一次最小请求，确认网络出口正常。这个任务不参与正式构建，只在排查时手动触发。Groovy DSL 版本：
tasks.register("verifyApiLink") { doLast { def apiKey = System.getenv("TAOTOKEN_API_KEY") if (!apiKey) { throw new GradleException("请先设置环境变量 TAOTOKEN_API_KEY") } def url = new URL("https://taotoken.net/api/v1/chat/completions") def conn = url.openConnection() conn.setRequestMethod("POST") conn.setRequestProperty("Authorization", "Bearer " + apiKey) conn.setRequestProperty("Content-Type", "application/json") conn.setDoOutput(true) conn.setConnectTimeout(30000) conn.setReadTimeout(30000) def body = '{"model":"你的Model_ID","messages":[{"role":"user","content":"ping"}]}' conn.getOutputStream().write(body.getBytes("UTF-8")) def code = conn.getResponseCode() println("API 响应码: " + code) if (code == 200) { println("请求链路正常") } else { println("请求链路异常，请检查 Key 和网络") } } }Kotlin DSL 版本：
tasks.register("verifyApiLink") { doLast { val apiKey = System.getenv("TAOTOKEN_API_KEY") ?: throw GradleException("请先设置环境变量 TAOTOKEN_API_KEY") val url = java.net.URL("https://taotoken.net/api/v1/chat/completions") val conn = url.openConnection() as java.net.HttpURLConnection conn.requestMethod = "POST" conn.setRequestProperty("Authorization", "Bearer $apiKey") conn.setRequestProperty("Content-Type", "application/json") conn.doOutput = true conn.connectTimeout = 30000 conn.readTimeout = 30000 val body = """{"model":"你的Model_ID","messages":[{"role":"user","content":"ping"}]}""" conn.outputStream.write(body.toByteArray(Charsets.UTF_8)) val code = conn.responseCode println("API 响应码: $code") if (code == 200) { println("请求链路正常") } else { println("请求链路异常，请检查 Key 和网络") } } }运行方式：
export TAOTOKEN_API_KEY=你的API_KEY ./gradlew verifyApiLink如果输出「请求链路正常」，说明你的网络出口、TLS、鉴权都没问题，Gradle 报的网络错就大概率是特定仓库域名的问题。如果这个任务也失败，那说明是整体网络问题，改仓库地址也没用，需要先解决网络出口。
这里要强调三件套的完整性：Base URL 是https://taotoken.net/api，Key 从控制台获取，Model ID 从文档选。三者缺一不可，任何一个错了都会导致验证失败。如果你用的是 Claude Code，它的配置也是同样的三件套，文档在 https://taotoken.net/doc 有详细说明。
配置片段给完了，下一节我会讲怎么验证请求成功，以及看到什么样的返回才算真的通了。
4. 验证请求与成功结果：从日志确认 Gradle 和 API 链路都正常
配置写完之后，最关键的一步是验证。很多人改完配置就直接跑构建，成功了也不知道为什么成功，失败了也不知道哪一步错了。正确的做法是分层验证：先验证 API 链路，再验证 Gradle 依赖解析，最后验证完整构建。
先验证 API 链路。运行上一节的自定义任务：
export TAOTOKEN_API_KEY=你的API_KEY ./gradlew verifyApiLink成功的输出应该类似：
> Task :app:verifyApiLink API 响应码: 200 请求链路正常看到 200 和「请求链路正常」，说明你的机器能正常访问https://taotoken.net/api，Key 有效，TLS 握手正常。这一步是整个排查的基准线。如果这里就失败了，后面的 Gradle 排查没有意义，先解决网络出口问题。
接着验证 Gradle 依赖解析。用dependencies任务打印依赖树，确认所有依赖都能解析到具体版本：
./gradlew :app:dependencies --configuration debugRuntimeClasspath成功的输出会列出完整的依赖树，每个依赖后面跟着版本号，比如：
+--- com.squareup.okhttp3:okhttp:4.12.0 +--- com.google.code.gson:gson:2.10.1 +--- androidx.appcompat:appcompat:1.6.1如果某个依赖显示FAILED或者->后面跟着(conflict resolution)，说明有版本冲突。如果显示Could not resolve，说明下载失败。这时候可以针对性处理：冲突的用resolutionStrategy强制版本，下载失败的检查仓库配置。
然后验证完整构建：
./gradlew assembleDebug --info加--info能看到详细的下载日志，包括每个依赖从哪个仓库下载、耗时多少。成功的标志是最后出现BUILD SUCCESSFUL。如果失败，日志里会明确告诉你哪个依赖、哪个仓库、什么错误。
我实测下来，有几个成功信号值得关注。第一，--info日志里如果看到Downloading https://...后面跟着Downloaded in xxx ms，说明网络下载正常。第二，如果看到Cached resource ... is up-to-date，说明缓存命中，没有重复下载。第三，如果看到Resolving dependencies之后没有报错，说明依赖树解析成功。
还有一个验证技巧：用--refresh-dependencies强制刷新一次，确认不是缓存掩盖了问题：
./gradlew assembleDebug --refresh-dependencies如果强制刷新也能成功，说明远程仓库真的可达，配置是稳的。如果只有用缓存才能成功，说明远程仓库其实有问题，只是被缓存掩盖了，换台机器或者清缓存就会暴露。
对于 API 链路的验证，除了自定义任务，也可以直接用 curl 确认返回结构：
curl -s -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"你的Model_ID","messages":[{"role":"user","content":"ping"}]}' \ | head -c 500成功的返回里会有choices数组，每个元素包含message字段。如果返回{"error":...}，说明鉴权或参数有问题。如果返回空或者超时，说明网络有问题。
这里要提醒：验证的时候不要只看「有没有报错」，要看「返回内容对不对」。有时候请求返回 200 但内容是错误信息，比如 Key 过期、模型不存在，这些都会以 200 状态码返回错误体。所以一定要检查返回的 JSON 结构。
验证通过之后，你就有了一个稳定的基准。后面再遇到 Gradle 报错，可以快速对比：是 API 链路也不通了（整体网络问题），还是只有 Gradle 依赖下载失败（特定仓库问题）。这个对比能帮你省下大量试错时间。
下一节我会列出本篇最常见的几类报错，以及对应的排查步骤。这些都是真实会遇到的错误信息，我会给出具体的定位方法和解决路径。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 逐条对照
这一节把最常见的几类报错逐条拆开。每条都按「报错原文 → 原因 → 排查步骤 → 解决」的结构写，你可以直接对照自己的日志找。
第一类，401 Unauthorized。这个在 API 链路验证时最常见。报错原文通常是：
{"error":{"message":"Invalid API key","type":"invalid_request_error"}}或者 HTTP 状态码直接返回 401。原因是 Key 不对、没带上、或者格式错了。排查步骤：先确认环境变量TAOTOKEN_API_KEY是否设置成功，用echo $TAOTOKEN_API_KEY看有没有值。然后确认请求头是Authorization: Bearer 你的KEY，注意 Bearer 后面有一个空格。再确认 Key 没有多余的空格或换行，从控制台复制时容易带上。如果都对了还是 401，去控制台确认 Key 是否被禁用或删除。解决方式就是重新创建一个 Key，更新环境变量。
第二类，local proxy failed。这个报错通常出现在 Gradle 或命令行工具里，原文类似：
Could not GET 'https://xxx'. Received status code 502 from server: Bad Gateway或者：
Failed to connect to localhost port 7890: Connection refused原因是系统或工具配置了本地代理，但代理服务没启动或者端口不对。排查步骤：检查环境变量HTTP_PROXY、HTTPS_PROXY、ALL_PROXY是否设置了，用env | grep -i proxy看。如果设置了但代理没开，就会报这个错。另外检查~/.gradle/gradle.properties里有没有systemProp.http.proxyHost之类的配置。解决方式是取消代理配置，或者确保代理服务正常运行。注意这里说的是本地代理配置问题，不涉及任何网络访问方式的选择，只是排查配置一致性。
第三类，reading choices。这个报错出现在解析 API 返回时，原文类似：
Cannot read property 'choices' of undefined或者：
TypeError: Cannot read properties of undefined (reading 'choices')原因是请求返回的结构和预期不符，通常是返回了错误体而不是正常的choices数组。排查步骤：先把原始返回打印出来，不要直接取choices。用 curl 发同样的请求，看返回的完整 JSON。如果返回里有error字段，说明请求本身失败了，先解决错误。如果返回是空的，说明网络或鉴权有问题。解决方式是加防御性判断，先检查返回里有没有choices再取，同时修复导致错误返回的根本原因。
第四类，OAuth 相关报错。这个在 Claude Code 或类似工具的配置里常见，原文类似：
OAuth token expired或者：
Failed to authenticate: invalid_grant原因是工具的鉴权方式和 API Key 不匹配，或者 token 过期了。排查步骤：确认你用的是 API Key 方式而不是 OAuth 方式。Claude Code 的配置文档在 https://taotoken.net/doc ，里面会说明用 Base URL + Key + Model ID 的方式接入。如果工具默认走 OAuth，需要改成 API Key 模式。解决方式是按文档重新配置三件套：Base URL 填https://taotoken.net/api，Key 用控制台创建的，Model ID 按文档选。
除了这四类，还有几个 Gradle 特有的报错值得单独说。Could not resolve com.xxx:xxx通常是仓库里没有这个依赖，或者版本号写错了。排查时先去 Maven 中央仓库搜一下这个坐标是否存在，再确认版本号。Duplicate class是依赖冲突，用dependencies任务找到重复的库，用exclude排除或者resolutionStrategy强制版本。Program type already present也是冲突，通常是 support 库和 androidx 混用，统一到 androidx 即可。
TransactionTooLargeException和CursorWindowAllocationException这类运行时异常，虽然不直接是 Gradle 构建问题，但在 Android 异常解决方法里也很常见。前者是 Binder 传输数据超过 1M 限制，解决方式是把大数据拆开传，或者用文件、数据库做中转。后者是 Cursor 没关闭导致窗口分配失败，解决方式是在 finally 里调用cursor.close()。这两个异常和构建无关，但排查思路是一样的：先定位触发点，再针对性处理。
NoClassDefFoundError是编译通过但运行时报错，通常是依赖没有正确打包进 APK。排查时确认依赖用的是implementation还是compileOnly，compileOnly的依赖不会打包。如果是本地 jar 包，确认已经放到libs目录并在build.gradle里声明了implementation files('libs/xxx.jar')。
排查的核心方法论是：先看报错的第一行和Caused by，确定错误类型；再用最小复现验证，排除干扰因素；最后针对性修改，改完立即验证。不要一次改多个地方，否则成功了也不知道是哪个改动生效的。
下一节是 CTA 分流，我会按你的具体场景给出对应的入口。
6. 按场景选入口：排障、验证模型、长期编码分别走哪条路
排查到这一步，你应该已经能区分网络、缓存、依赖冲突三类问题了。接下来按你的实际场景选入口，不要只停留在首页。
如果你是在排障或接入阶段，比如正在解决 Gradle 报错、配置请求链路、或者接入 Claude Code，那核心入口是 API Keys 和接入文档。先去 https://taotoken.net/api-keys 创建和管理 Key，再去 https://taotoken.net/doc 看具体的接入配置。这两个页面配合使用，能覆盖大部分接入和排障场景。文档里有 Base URL、Model ID、请求示例，照着配就行。
如果你是想验证某个模型的效果，比如确认某个模型能不能处理你的代码、响应速度如何，那用模型对话入口最直接。地址是 https://taotoken.net/chat ，可以在网页上直接发请求，不用写代码。适合快速试模型、对比不同模型的表现。验证通过之后再写进代码或构建脚本。
如果你是长期做编码或 Agent 类任务，比如每天都要调用模型做代码生成、代码审查、自动化任务，那 Coding Plan 更合适。地址是 https://taotoken.net/coding-plan ，它针对高频调用场景做了优化。相比按次调用，长期编码场景用 Coding Plan 成本更可控。
最后说一个实用技巧：把请求链路验证做成一个固定动作。每次遇到 Gradle 网络报错，先跑一次./gradlew verifyApiLink，确认基准线是否正常。如果基准线正常，就专心查 Gradle 仓库配置；如果基准线也不正常，就先解决网络出口。这个习惯能帮你快速缩小问题范围，避免在错误的方向上浪费时间。
另外，Key 的管理要规范。不要硬编码到代码里，不要提交到 Git，用环境变量或 CI Secret。如果团队多人协作，每个人用自己的 Key，方便追踪调用来源。Key 泄露了立即在控制台删除重建。
Android 异常解决方法的核心不是记住所有报错，而是建立一套分层排查的思路：先确认请求链路，再确认依赖解析，最后确认构建产物。这套思路适用于 Gradle 构建，也适用于其他网络相关的异常。把基准线建好，后面的排查就是对比和缩小范围的过程。
