自己在本地环境里被Connect timed out坑过多少次估计很多 Android 开发者都数不清了。我最近把积压已久的老项目重新拉回电脑Android Studio 版本刚升完打开工程等着 Gradle Sync进度条在某个依赖上停了两分钟后构建窗口抛出一串Connect timed out。那一刻我的第一反应是“断网了”但手机Wi-Fi明明满格。后来反复排查才意识到这句话就像一张没有写清楚收件地址的快递单Gradle 同步、ADB 连接、模拟器调试、SDK 下载每一个环节都可能吐出一句 Connect timed out每次背后的原因和修法完全不同。这篇文章把我在实际项目中遇到过的各种“Connect timed out”场景串起来讲一遍。你会看到我真正用过的排查命令、改过的配置文件和踩过的坑按顺序走一遍大部分问题都能定位到根上。1. 先分清这个Connect timed out是从哪一层冒出来的不管报错文案多吓人动手改配置之前一定要先做一件事确定这个超时发生在哪一层。Android Studio 是个“多进程 多网络链路”的大家伙Gradle 进程、ADB 服务、模拟器进程、SDK 下载组件各自有独立的网络通道每个通道超时的原因、排查范围、修复手段完全不同。如果在还没定位的情况下盲目改镜像配置往往白忙一下午。1.1 看Build窗口还是Logcat窗口最简单的方法就是看报错出现在哪个窗口。Build窗口里出现Connect timed out大概率是 Gradle 在解析或下载依赖时网络受阻。Logcat窗口里出现连接超时或者Run窗口在启动阶段卡住则多半是 ADB、调试器、模拟器链路的问题。我把平时常遇到的报错场景整理成了对照表排查时直接对号入座报错出现的环节典型文案大概率原因优先检查项Gradle SyncCould not resolve all files / Connect timed out依赖仓库不可达镜像仓库、DNS、Gradle 配置Gradle BuildArtifact download timed out依赖下载超时网络环境、本地缓存Run / 调试器Unable to open debugger port端口冲突、ADB 链路异常5037端口、adb devicesLogcat 启动Failed to connect to localhost模拟器访问宿主机地址错误10.0.2.2、adb reverseSDK ManagerDownload interrupted / timed outSDK 下载地址不可达dl.google.com 连通性Plugins 市场Could not connect to plugins server插件市场 CDN 响应慢官网手动下载插件这张表虽简单但能省掉大量重复排查。别人找我处理类似问题时我第一句永远问报错是在哪个窗口、哪一步操作之后出现的这不是客套话报错位置基本决定了排查方向。1.2 看日志里真正连的那个地址第二步是找到日志中包含的 URL。Gradle 同步超时时错误信息里大概率会残留完整地址。最常见的几个地址是dl.google.com、repo.maven.apache.org以及公司内网仓库地址。不同地址对应的策略完全不同超时地址是dl.google.com或maven.google.com负责 Android Gradle Plugin 和 Google 系依赖的分发。国内环境下直连经常不稳定优先考虑切换仓库镜像。超时地址是repo.maven.apache.orgMaven Central 的连接问题同样用镜像解决。超时地址是公司内部的 Nexus 仓库先问运维仓库服务是否在线再查本机 hosts 和防火墙。超时地址是services.gradle.orgGradle Wrapper 正在下载发行包和依赖仓库无关属于另一类问题。把上面这个地址复制到浏览器直接访问一遍如果浏览器都打不开说明问题根本不在 Android Studio而在系统网络层面。这时回去折腾 IDE 设置就是浪费时间。2. Gradle依赖同步超时一套完整的排查与修复流程如果确认是 Gradle 依赖下载超时那就可以按下面这套流程处理。这套流程是我在多个项目上验证过的按顺序执行能覆盖绝大多数情况。2.1 先验证本机到仓库的网络连通性打开终端用 curl 测一下仓库的响应状态。以国内最常用的阿里云镜像为例curl -I -m 10 https://maven.aliyun.com/repository/google如果返回HTTP/1.1 200 OK说明本机到镜像站的链路是通的问题大概率出在 Gradle 配置或 DNS 缓存。如果是Connection timed out说明确实到了网络层需要继续查 DNS。接着执行nslookup maven.aliyun.com ping maven.aliyun.com如果域名解析出来但 ping 不通或者解析结果非常诡异就要检查系统的 hosts 文件。Windows 上在C:\Windows\System32\drivers\etc\hostsmacOS 和 Linux 在/etc/hosts。我曾在同事电脑上发现过安全软件往 hosts 里塞了一行dl.google.com的内网沙箱地址结果 Android Studio 同步什么依赖都超时排查了很久才发现是这行残留记录在捣乱。2.2 把Maven仓库切换成镜像仓库确认网络没问题后最直接的操作就是改仓库配置。新版 Android Studio 项目默认把仓库配置写在settings.gradle的dependencyResolutionManagement里我建议改成下面的样子dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }这里把镜像仓库放在google()和mavenCentral()前面Gradle 解析依赖时会优先从镜像拉取。镜像服务本质上是在本地或国内节点缓存了上游仓库的构件响应速度和稳定性都会好很多。要注意两个细节FAIL_ON_PROJECT_REPOS会禁止子模块再单独声明仓库避免各个模块的仓库列表不一致导致解析混乱。部分冷门第三方 SDK 只发布在已停止维护的 JCenter 路径上镜像也不一定覆盖。这类构件只能用公共镜像兜底或者干脆把 jar/aar 下载到本地用implementation files()引入。2.3 调大Gradle的HTTP超时时间加了镜像之后还有少数场景会超时尤其是体积较大的依赖下载。Gradle 默认的 HTTP 连接超时只有 30 秒左右在高峰期从远程拉一个几十 MB 的包很容易触发。此时可以修改gradle.propertiesorg.gradle.internal.http.connectionTimeout180000 org.gradle.internal.http.socketTimeout180000单位是毫秒connectionTimeout是建立 TCP 连接的超时时间socketTimeout是建立连接后等待数据的超时时间。我一般直接配置成 180000也就是 3 分钟既不会让一次失败卡太久也足够应对正常的大包下载。2.4 确认是不是Gradle Wrapper本身在下载还有一种容易忽略的超时发生在 Gradle 同步最开始的阶段报错信息里带有gradle-8.x-bin.zip之类的字样。这是因为项目里的gradle/wrapper/gradle-wrapper.properties指向了services.gradle.org而 Gradle 需要先下载对应发行版才能执行构建。我的处理办法有两种手动下载对应版本的 Gradle 压缩包放到本地目录然后修改gradle-wrapper.propertiesdistributionUrlfile\:/D:/tools/gradle-8.7-bin.zip在 Android Studio 的 Settings - Build Tools - Gradle 里选择 Local distribution直接指定本地已解压的 Gradle 目录。这个方法尤其适合经常新建项目的场景。新建项目时 Android Studio 经常会拉一个你本地没有的 Wrapper 版本跑一次全量下载很容易碰上超时换成本地版本能彻底绕开。2.5 依赖缓存和离线模式兜底如果项目之前已经成功同步过一次那么所有依赖其实都缓存在本地的~/.gradle/caches目录里。此时可以直接打开 Android Studio 的离线模式File - Settings - Build, Execution, Deployment - Build Tools - Gradle勾选 Offline work。离线模式会跳过所有远程仓库检查直接使用本地缓存构建速度快得多。我的习惯是只有在新增依赖或切换分支时才切回在线模式拉取一次其余时间保持离线。注意离线模式下如果在缓存中找不到某个构件构建会立刻报“找不到依赖”这时候不用慌切回在线模式同步一次就行。3. 模拟器里连不上本机调试服务一个很容易踩的坑另一种极其常见的场景是项目已经跑起来了App 成功安装到模拟器但应用里请求本地后端接口时一直Connect timed out。很多人把这个问题归咎于电脑网络其实问题恰恰出在“localhost 的理解方式不同”。3.1 模拟器里的localhost不是你宿主机Android 模拟器内部是一个虚拟的 NAT 网络环境它在自己内部维护了一个独立的环回地址。你在模拟器里访问localhost访问到的是模拟器自己而不是开发电脑。宿主机在模拟器网络栈里有专门的映射地址也就是10.0.2.2。所以代码里的 BaseUrl 如果写成http://localhost:8080在模拟器里必然连不上表现就是连接超时或连接拒绝。正确写法是http://10.0.2.2:8080另外提醒一句如果后端跑的是 HTTP 明文接口Android 9 及以上系统默认禁止明文流量。这时候还需要在res/xml/network_security_config.xml里做允许配置否则你可能会看到另一个“连接失败”的错误很容易和超时混在一起。3.2 用adb reverse把端口映射到模拟器如果你不想为了调试环境去改 BaseUrl更优雅的办法是使用adb reverse。这个命令可以把模拟器里的端口反向映射到宿主机adb reverse tcp:8080 tcp:8080执行之后模拟器里访问http://localhost:8080请求会通过 ADB 转发到宿主机的 8080 端口。这个方案对真机调试同样适用而且不要求手机和电脑在同一网段。唯一要注意的是设备重连或 ADB 服务重启后映射会失效需要重新执行定期使用建议写进启动脚本里。3.3 真机Wi-Fi调试时容易被忽略的网络限制真机无线调试的场景里最常见的超时原因是手机和电脑不在同一个局域网。Android 11 及以上可以用系统的无线调试配对功能Android Studio 会通过 mDNS 发现设备。如果发现设备后连接一直卡在timed out先检查路由器是否开启了 AP 隔离。很多办公路由默认开启这个功能它会让同一 Wi-Fi 下的设备互相不能访问。其次是检查手机和电脑是否落在同一网段跨网段时该路由就不可达。这两点确认之后无线调试基本都能稳定连上。4. ADB连接层的超时从重启发到端口占用还有一种情况是点了 Run 按钮Android Studio 一直卡在Connect timed out: adb或者弹Unable to open debugger port。这类问题属于 ADB 链路故障我按下面的顺序逐一排查。4.1 先看adb devices的输出在终端执行adb devices正常输出会显示一串设备列表设备名右侧的状态是device。如果状态是offline说明链路已经异常如果是unauthorized说明手机上的 USB 调试授权弹窗还没确认如果列表为空则属于 ADB 服务没识别到设备。一个容易被忽略的点是Android Studio 的设备列表里能看到设备并不代表 ADB 链路正常。很多时候设备虽然出现在列表里但状态是 offline点 Run 照样超时。所以每次先以命令行的adb devices状态为准。4.2 重启ADB并处理端口占用最常见的修复动作是重置 ADB 服务adb kill-server adb start-server adb devices如果执行后卡在* daemon not running. starting it now on port 5037并一直无响应说明 5037 端口被占用。Windows 上可以查看netstat -ano | findstr 5037macOS 和 Linux 上可以用lsof -i :5037找到占用端口的进程号后去任务管理器或进程管理工具确认是不是其他硬件调试工具占用了这个端口。我之前遇到过一个串口调试软件把 5037 占了Android Studio 怎么连都报超时关掉那个软件后重置 ADB 马上恢复。4.3 防火墙和安全软件对ADB的拦截这个原因不太显眼但发生概率不低。部分安全软件会拦截 ADB 回连设备时使用的临时端口现象是手机端已经显示 USB 调试已连接授权弹窗也点了允许但 ADB 依旧超时。这时候试着把 Android Studio 和 adb 进程加入防火墙白名单或者临时关闭安全软件再做一次adb kill-server adb start-server大概率立刻恢复。这类问题即使重装 Android Studio 也依然存在因为拦截发生在系统层。5. SDK下载与插件市场超时Android Studio自身的网络问题除了项目构建链路Android Studio 本身也有联网需求。SDK Manager 下载组件时偶尔会超时插件市场加载列表时也经常转圈半天然后报错。这类问题不能通过项目配置解决得从 Android Studio 的角度去处理。5.1 SDK组件的下载地址与DNS刷新Android Studio 的 SDK 组件默认从dl.google.com拉取。如果你所在的网络环境对这条链路不稳定下载进度条就会卡住。首选动作是刷新 DNS 缓存排除域名解析脏数据的影响。Windows 上执行ipconfig /flushdnsmacOS 上执行sudo dscacheutil -flushcache如果刷新后仍超时可以把需要下载的 SDK 组件拿到另一台网络环境正常的机器上先下载好 Platform 和 Build-Tools 完整目录再拷贝到本机的~/Library/Android/sdkmacOS或C:\Users\你的用户名\AppData\Local\Android\SdkWindows下。Android Studio 启动时会自动识别这些组件完全不需要走下载流程。5.2 插件市场超时的另类安装方式Plugins 页面加载不出列表甚至报Connect timed out很多时候是插件市场的 CDN 响应慢。插件市场本身没有太多可配置项我推荐绕开它直接到 JetBrains 官网搜索需要的插件下载 zip 包然后在 Settings - Plugins 里选择 Install Plugin from Disk。这个方式不受市场页面连接状态影响我一直在用稳定且省时间。6. 最后一次整理一组能有效防复发的配置和习惯前面讲了那么多排查手段最后说说怎么让这个问题少发生。依赖下载超时这种事修好一次容易难的是不要在下个网络环境里再次爆发。6.1 gradle.properties里的合理默认值把下面这些配置放进gradle.properties基本能保证大多数项目的同步过程更稳org.gradle.daemontrue org.gradle.paralleltrue org.gradle.cachingtrue org.gradle.internal.http.connectionTimeout180000 org.gradle.internal.http.socketTimeout180000 org.gradle.jvmargs-Xmx2048m -XX:MaxMetaspaceSize512m需要留意的是超大项目的多模块并行构建对内存依赖较高。如果配置了并行构建之后构建反而变慢甚至卡死把org.gradle.parallel改回false再试别一味追求并行。6.2 团队共享一份依赖缓存依赖拉取问题最烦人的地方在于一个人修好了换台机器照样踩。如果开发团队的网络环境普遍一般可以考虑在局域网内共享 Gradle 缓存。将其中一台网络较好的机器作为“编译机”先在编译机上完成一次全量依赖同步然后通过共享目录让其他成员复用~/.gradle/caches。这种方法比每个人各自下载省事得多新加入的成员首次构建也能很快完成。6.3 离线构建作为最终兜底最后想分享一个我坚持了很久的习惯在项目依赖锁定之后专门用一次离线模式跑完整构建确认所有构件都已经落进缓存。这样即使后续网络彻底抽风至少还能保持一个可用的构建环境。之前出差途中遇到酒店网络半瘫痪我就是靠离线构建完成了当天所有任务的交付关键时刻真的能救命。