在国外折腾过 Android 开发的人都知道一个新建项目卡在 Gradle 下载、依赖同步转半天、SDK 组件装不上是什么体验。在国内做 Android 开发第一件事不是写代码而是先把“网络基础设施”收拾利索。Android Studio 快速配置国内镜像源和 HTTP 代理就是每个开发者绕不开的第一道坎。这篇文章不整虚的我会把镜像源、代理、Gradle 分发版、依赖缓存这些配置逐一拆开讲清楚给出能直接抄作业的配置方案最后附上我踩过几次坑之后总结的排查思路。不管是刚装好 Android Studio 的新手还是被同步问题折磨的老手都能照着改完一遍跑通。1. 先搞清楚一件事你到底卡在哪一步1.1 慢的三个典型症状配置之前我强烈建议你先花两分钟判断一下自己到底卡在哪一层。Android 开发环境的下载和同步涉及三条链路Android Studio 本身和 SDK 组件的下载、Gradle 工具链的分发下载、以及项目依赖库的拉取。这三条链路的服务器都在境外任何一个环节慢都会让你觉得“整个环境没法用”。我见过太多人一股脑改了一堆配置最后发现改的地方和瓶颈根本不在同一层。比如有人折腾了半天镜像源结果卡的是 Android Studio 启动时的 SDK 组件下载这两者完全不搭边。先定位症状再动手配置效率会高很多。通常症状分为三类第一类是新建项目或导入项目时进度条卡在“Downloading Gradle”或者长时间停留在“Gradle sync”阶段这多半是 Gradle 分发包下载慢第二类是项目同步时后台日志一直报错显示拉取某些依赖超时这是 Maven 仓库访问不畅第三类是 Android Studio 右下角一直提示安装某个 SDK Platform 或 Build Tools装了几十分钟还没动静这是 SDK 服务器连接不稳定。1.2 镜像源和代理到底在解决什么问题很多人把镜像源和代理混为一谈其实它们解决的是不同层面的问题。镜像源解决的是“下载源”问题它把原本要访问的境外服务器地址替换成国内的缓存服务器也就是让数据从离你更近的地方传过来。而 HTTP 代理解决的是“访问路径”问题它让你本机的请求先到达代理服务器再由代理服务器去请求目标地址。生活里找个类比就好理解了镜像源相当于你在本地开了一家超市卖的东西和境外仓库一样但送货快得多代理则相当于你找了个跑腿小哥你的快递问题由他统一处理你只需要把地址给他就行。两者最好的协作方式是镜像源负责处理国内能访问到的仓库代理负责处理必须走特定网络环境的场景。这里有必要强调一下HTTP 代理在开发环境中的合规应用场景非常普遍公司内网统一要求所有流量走指定代理办公网络认证需要代理转发本地调试工具通过代理做缓存加速这些都属于正常的技术配置。配置方法本身不涉及任何特殊用途我只讲技术层面怎么配、怎么排错大家按自己的合规场景使用即可。2. 国内镜像源配置详解从全局到项目2.1 全局统一配置init.gradle 方案我先说我自己最推荐的方式全局配置 init.gradle。这个配置文件放在 Gradle 用户目录下对所有的项目生效。好处是你新建一个项目、导入一个别人的开源项目都不用再去改里面的 build.gradle只要项目用的是同一个 Gradle 版本体系依赖解析就会自动走你配置的镜像。init.gradle 的搜索路径是固定的一般在三个位置~/.gradle/init.gradlemacOS/Linux、C:\Users\用户名\.gradle\init.gradleWindows也可以放在GRADLE_USER_HOME指定的目录下。如果文件不存在直接新建一个即可文件名必须是init.gradle。下面是我用的一个简洁版本allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/central } google() mavenCentral() } }这个配置把阿里云的几个核心仓库都注册进去了。你可能注意到我在最后保留了一行google()和mavenCentral()有些人会问既然已经配了镜像还要保留官方源做什么我的习惯是保留原因很简单镜像仓库在极少数情况下会出现不同步或者新包更新不及时的问题保留官方源作为兜底依赖解析时如果镜像没有会自动去官方源拉取不会直接报错。虽然速度慢一点但至少在镜像同步出问题的时刻构建不会中断。2.2 项目级配置settings.gradle 方案如果你的项目是多人协作或者你希望某个项目独立使用特定的仓库配置那就不要用全局 init.gradle而是直接在项目的settings.gradle里配置仓库。新版 Android Studio 默认生成的项目会启用dependencyResolutionManagement块里面有RepositoriesMode.FAIL_ON_PROJECT_REPOS设置。这段配置要改的地方在dependencyResolutionManagement下的repositories部分dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/central } google() mavenCentral() } }很多人在这一步会犯一个错误把镜像仓库直接加到了repositories列表的末尾。这样做在解析依赖时依然会先走官方源因为 Gradle 默认按顺序依次尝试各个仓库直到找到依赖为止。如果官方源连接超时Gradle 会等很久才会换到下一个仓库。所以正确做法是让镜像源排在前面官方源排在后面对吧其实也不全对。Gradle 对仓库的遍历顺序有内部逻辑并不是简单按照声明顺序但有一点是确定的声明越靠前的仓库越早被尝试。为了让镜像源优先生效务必把镜像仓库放在列表头部google()和mavenCentral()放在末尾当兜底。2.3 常见国内镜像地址与选型国内能用的 Maven 镜像服务不少我分别列一下并给出适用建议。镜像服务地址特点阿里云公共仓库https://maven.aliyun.com/repository/public综合性强稳定覆盖最广阿里云 Google 镜像https://maven.aliyun.com/repository/google解决 Google Maven 访问问题阿里云 Gradle Plugin 镜像https://maven.aliyun.com/repository/gradle-plugin插件解析专用腾讯云 Maven 镜像https://mirrors.cloud.tencent.com/nexus/repository/maven-public/聚合仓库地址较长华为云 Maven 镜像https://repo.huaweicloud.com/repository/maven/国内速度也不错实际使用时我建议优先选择阿里云因为它的仓库划分最细public、google、gradle-plugin、central分开管理能覆盖 Android 构建场景下几乎所有需要访问的仓库类型。腾讯云和华为云的特点是聚合不需要你区分仓库类型一条地址走天下如果你不想在细节上费心思直接用也行。还有一个点值得注意仓库里的public实际上聚合了 JCenter 和 Maven Central 的内容。虽然 JCenter 已经宣布停更但很多老的 Android 库还躺在里面public聚合仓库依然能解析到这些老库这也是我始终坚持配置public仓库的原因之一。3. Gradle 分发包镜像配置把卡脖子的第一步解决掉3.1 修改 distributionUrl最容易被忽略的坑先问你一个问题你在 Android Studio 里新建一个项目进度条卡在 80% 不动你知道它卡在哪吗大部分情况下它卡在下载 Gradle 分发包上。Android Studio 新建项目时会根据项目模板中的gradle-wrapper.properties里的distributionUrl去下载对应的 Gradle 版本。默认情况下这个 URL 指向的是services.gradle.org在本地网络环境下访问这个地址速度完全是随缘的。我踩过的最大的坑是我花了一晚上配置好了所有的 Maven 镜像但新建项目依旧卡顿。后来才发现项目在同步的第一个阶段是下载 Gradle 工具本身这一步根本没走 Maven 仓库走的是distributionUrl指向的地址。Maven 镜像管不到这个环节这里是单独的下载链路。解决办法十分简单找到项目根目录下的gradle/wrapper/gradle-wrapper.properties把distributionUrl改成国内镜像地址distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists腾讯云的 Gradle 镜像支持比较全地址格式是https://mirrors.cloud.tencent.com/gradle/gradle-版本-bin.zip。改完之后新建项目时 Gradle 分发包的下载速度会有质的提升。3.2 离线模式与缓存策略同步失败的兜底方案还有一个实用的技巧是充分利用 Gradle 的本地缓存。Gradle 会把下载过的依赖和分发包缓存到GRADLE_USER_HOME目录里具体来说分发包在wrapper/dists下依赖在caches/modules-2下。如果你已经成功构建过一个使用同样依赖的项目那么另一个项目同步时大概率能直接从缓存里命中不需要重新下载。在 Android Studio 的 Gradle 设置面板里有一个“Offline work”的开关。网络环境特别差的时候可以打开离线模式Gradle 会强制只从本地缓存中解析依赖任何缓存中没有的依赖都会直接报错。这个模式不是用来正常开发的但它能用最快的速度帮你验证“缓存里都有什么”排查到底是网络问题还是配置问题。用缓存做诊断有个顺序先关掉离线模式看同步是否正常如果正常说明网络链路没问题如果失败再去开离线模式能定位到具体是哪个依赖没有缓存。这个思路在我排查复杂构建问题时反复用到建议大家都试试。4. HTTP 代理配置实操什么场景需要怎么配不踩坑4.1 Android Studio 内置代理设置说完了镜像源再来说 HTTP 代理。在合规的开发场景里最常见的是公司内网或者办公网络要求所有 HTTP 流量经过统一代理服务。Android Studio 本身提供了代理设置入口路径是Settings或者Preferences-Appearance Behavior-System Settings-HTTP Proxy。在代理页面里通常有四个选项手动配置代理、无代理、自动检测、自动代理配置 URL。我实际开发中的经验是如果你的网络环境有明确的代理服务器地址和端口号选择手动配置填入地址和端口如果代理要求身份认证勾选上“Authentication”输入用户名和密码如果是公司统一推的 PAC 文件选择自动配置 URL填上 PAC 文件地址即可。需要注意Android Studio 内置的代理配置管的是 IDE 自身的网络请求包括 SDK 组件下载、插件市场访问、检查更新等。但它并不一定能完全覆盖 Gradle 的依赖下载因为 Gradle 是独立的构建进程它走的是 JVM 的网络栈需要单独配置才能让代理生效。4.2 Gradle 独立代理配置如果你确认了 Gradle 下载依赖时的网络请求需要走代理那就要在gradle.properties文件里显式声明代理配置。gradle.properties可以从多个位置读取推荐放在~/.gradle/gradle.properties用户级对所有项目生效也可以放在项目根目录下项目级只对本项目生效。配置内容是标准的 Java 系统属性格式systemProp.http.proxyHost127.0.0.1 systemProp.http.proxyPort7890 systemProp.https.proxyHost127.0.0.1 systemProp.https.proxyPort7890 systemProp.http.nonProxyHostslocalhost|127.0.0.1|*.aliyun.com|*.cloud.tencent.com systemProp.https.nonProxyHostslocalhost|127.0.0.1|*.aliyun.com|*.cloud.tencent.com这段配置里最关键的是nonProxyHosts这一项它声明了哪些地址不需要走代理。把国内镜像源的域名加进去意味着访问镜像站时直接连接不经过代理能避免代理层额外增加延迟。很多人配置了代理后发现下载依赖反而更慢了十有八九就是没设置nonProxyHosts所有请求都往代理服务器挤代理又不具备针对镜像源的特殊优化自然快不了。如果你的代理服务器需要认证账号密码还需额外加入两个字段systemProp.http.proxyUser你的用户名 systemProp.http.proxyPassword你的密码 systemProp.https.proxyUser你的用户名 systemProp.https.proxyPassword你的密码4.3 代理与镜像源的优先级和配合镜像源和代理不是对立的而是配合关系。合理的情况下应该把镜像源作为默认下载地址代理作为兜底通道。也就是说能通过镜像源直连的就直连镜像源没有的库再去走代理访问官方仓库。这正是nonProxyHosts存在的意义。我在实际开发中见过两种极端的配置都不可取。一种是不配镜像源只配代理结果依赖下载全部走代理延迟高速度不稳另一种是只配镜像源完全不配置代理遇到镜像源同步不及时的库构建直接卡死。正确配置的核心思路是镜像源兜底主流依赖代理兜底边缘依赖双保险。还有一个小细节Android Studio 和 Gradle 的代理配置最好是保持一致的否则会出现 IDE 里能看到代理但 Gradle 构建时依然报连接超时的诡异情况。配置完代理后记得重启 Android Studio同时清理掉 Gradle 的守护进程命令是./gradlew --stop否则旧的守护进程可能还带着旧的网络配置新的配置不生效。5. 完整配置示例新建项目也能一把过5.1 一份可以直接抄的 init.gradle 模板前面讲了各种配置的拆解这里我整合一份完整的全局配置方案你照着建文件就行。第一步创建init.gradle文件到 Gradle 用户目录// ~/.gradle/init.gradle 或 C:\Users\用户名\.gradle\init.gradle allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/central } google() mavenCentral() } buildscript { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/central } google() mavenCentral() } } }第二步修改项目gradle/wrapper/gradle-wrapper.properties中的distributionUrl为腾讯云镜像。第三步在~/.gradle/gradle.properties中按需配置代理和nonProxyHosts。三步做完新建任何项目都不用再为网络问题发愁。这里提一句buildscript块在以前的构建脚本中很常见现在虽然很多项目改成用plugins块声明插件但buildscript仓库依然在一些老项目里发挥作用。在全局配置里保留buildscript块的镜像配置是为了兼容导入了老项目时插件依赖也能走到镜像源。5.2 验证配置是否生效的三个方法配置改完之后你需要确认它真的生效了而不是“感觉”生效了。我每次配置完环境都会用三个方法来验证。方法一开一个全新的空白项目看首次同步时间。从触发同步到构建完成如果时间从原来的十几分钟缩短到几分钟以内基本可以断定分发包和依赖下载链路都正常了。方法二观察 Gradle 的下载日志。在 Android Studio 的Build窗口切到Gradle Sync或Build Output能看到实际下载的 URL 地址。如果日志里出现的是maven.aliyun.com或者mirrors.cloud.tencent.com说明网络请求已经走了镜像配置生效。如果日志里出现的还是repo.maven.apache.org或者dl.google.com说明配置加载有问题。方法三直接检查本地缓存。Gradle 下载的依赖会落在~/.gradle/caches/modules-2/files-2.1目录下。同步完成后到对应目录看有没有新增的.jar或.aar文件变更时间是不是刚刚就能确认依赖确实被拉取到了本地缓存。6. 常见问题排查速查6.1 配置了镜像还是慢怎么定位瓶颈如果你已经按照上面的步骤配置完了同步还是慢先不要急着继续折腾配置按照我下面的排查思路走一遍能省下大量时间。第一步确认卡在哪个环节。在 Android Studio 底部打开Build窗口切到日志视图看当前停留在哪个任务上。如果正在下载 Gradle 分发包检查distributionUrl是否正确指向镜像如果正在解析依赖检查仓库列表顺序如果是 SDK 组件下载需要去 SDK Manager 里看是不是有组件没装那部分走的是另一个下载通道。第二步测试实际的网络连通性。在终端里用curl直接测一个镜像地址的响应速度比如curl -o /dev/null -s -w HTTP状态码:%{http_code} 总耗时:%{time_total}s\n https://maven.aliyun.com/repository/public/如果返回的状态码不对或者总耗时高得离谱说明你的网络环境和镜像服务器之间的连接本身就有问题这时候才需要检查是不是代理配置干扰了镜像访问排查nonProxyHosts设置。第三步确认 Gradle 守护进程重启了没有。守护进程会缓存 JVM 系统和网络配置如果配置修改后没有重启守护进程新配置可能压根没被加载。运行./gradlew --stop停止所有守护进程再重新同步能让配置变更更快生效。6.2 典型问题速查表症状大概率原因解决方案新建项目卡在 Gradle 下载distributionUrl 指向境外地址改成腾讯云等国内镜像地址Gradle 同步报 Could not GET 某个依赖仓库未走镜像或镜像未包含该依赖检查仓库顺序开启官方源兜底配置了代理反而更慢镜像地址也走了代理代理层增加延迟在 nonProxyHosts 中加入镜像域名依赖解析报证书错误代理代理服务器拦截了 HTTPS 证书在 Gradle JVM 参数中导入代理根证书改了配置但没有任何变化Gradle 守护进程缓存旧配置执行./gradlew --stop后重启 IDE每次同步都重复下载依赖本地缓存目录权限异常或磁盘空间不足检查GRADLE_USER_HOME目录读写权限和剩余空间6.3 我的经验心得最后分享几句实际工作中总结出来的话。第一镜像源不是万能的遇到镜像同步不及时的情况留一个官方源兜底比任何高级配置都有效。第二代理配置一定不要盲抄网上的模板尤其是nonProxyHosts里的白名单要根据你实际用的镜像域名来写否则效果适得其反。第三Android Studio 的配置界面和 Gradle 的配置文件是两套体系改任何一处之前先想清楚它管的是哪条链路千万不要混。我在一次团队协作中有同事碰到过一个诡异的问题同一份项目代码他的机器上同步正常而另一位同事的机器上每次都报某个依赖下载超时。最后发现那位正常机器上的init.gradle里配置了流程中提到的全局镜像而报错的机器上用的是项目级配置项目里的settings.gradle覆盖了全局配置。这个案例提醒我排查这类问题时第一步永远是先看当前项目的配置究竟加载的是哪一层全局的和项目的是不是一致避免在错误的地方反复纠结。配置这项功夫看起来琐碎但把底层机制弄明白之后就能稳定复现也不会被各种表面现象带着走。