简介面向Android开发者与初学者的SDK代理配置指南旨在解决官方渠道下载SDK组件缓慢、容易中断的问题。文档从Android Studio的SDK Manager入口讲起将操作步骤拆解到具体菜单与选项卡区分自动检测与手动代理两种模式详细说明镜像主机、端口、用户名密码等参数填写要点同时列出东软、阿里云、腾讯云等常用镜像源并强调代理设置同样适用于Gradle插件和Google服务框架的加速下载以及镜像失效时的切换与恢复方法。资源共1个docx文档体积约102KB内容组织紧凑、操作路径清晰可配合实际开发环境边看边操作适合需要搭建或优化Android开发环境、提升依赖下载速度的开发者。目前已有861人学习不失为开发环境搭建与网络配置的实用笔记。1. SDK 下载慢不一定是网的问题先搞清楚代理管的是哪一段路装过 Android 开发环境的人基本都经历过同一个场景Android Studio 装好了打开 SDK Manager 一加载组件列表进度条就在那转圈转几个小时都下不完几个几百 MB 的 SDK 包。这不是你带宽不行是请求要去海外的源站绕一圈。第一次碰这问题我也没想明白后来才知道 SDK Manager 本身支持走 HTTP 代理出海而 SDK Manager 的这个代理也能把整个 Gradle 依赖下载链路一起救活。本文就照着 SDK 设置代理这件事把从原理、图形界面配置到命令行写法和常见坑完整过一遍。适合刚被 SDK 下载速度折磨过的新手也适合想给 CI 环境配好代理的工程师。2. 代理和镜像的关系SDK Manager 的请求到底走了哪条链路2.1 为什么直连海外下载会这么慢TLS 握手与断点续传Android SDK 默认的下载源是 Google 的官方仓库域名在海外面向全球提供服务。对大陆开发者来说直连这个域名要经过出境链路中间任何一段出现拥塞或者丢包表现出来就是下载速度极慢甚至直接卡死。这里有个细节经常被忽略SDK Manager 不是简单地把文件拉下来就完了它要先请求一个 XML 清单文件获取所有可用组件的版本号、依赖关系、文件 URL 和 SHA-1 校验值然后才逐个下载。如果第一个清单请求就超时整个 SDK Manager 界面就停留在加载状态你以为没反应其实是请求根本没回来。慢的第二个原因在传输层。TLS 握手需要多轮往返走海外链路时延迟本身就高加上丢包导致的重传握手阶段就可能卡住十几秒。到了实际下载阶段SDK 组件的压缩包很多在 100 MB 以上普通 HTTP 下载对丢包非常敏感一旦 TCP 窗口调整不过来速度会急剧下降。还有一点是 SDK Manager 的下载器在断点续传上做得并不好我碰到过好几次下载到 80% 然后连接断开重新来一遍的情况。2.2 SDK Manager 的代理机制HTTP 代理与镜像替换的区别SDK Manager 的代理设置有两种形态很多人混着用但没搞清楚区别。第一种是 HTTP 代理Proxy你给 SDK Manager 指定一个代理服务器的地址和端口SDK Manager 把原本要发往 Google 源的请求先发给这台代理服务器由它转发。这种情况适合你有一台能稳定访问海外、带宽也够的代理服务器你的 SDK 请求仍然访问的是官方源只是换了条路。第二种是镜像源Mirror替换SDK Manager 也支持直接修改下载源地址让它去访问一个内容与官方一致的国内镜像。镜像站点会把官方仓库的 XML 清单和所有组件文件同步一份你的请求不再出海直接访问国内服务器。走镜像的好处是链路短速度稳定不依赖额外代理服务缺点是镜像同步存在延迟有时官方刚发布的新版本组件镜像上要过一两天才有。项目里提到的配置方式本质上就属于把代理服务器指向一个国内镜像站点相当于用 HTTP 代理的协议包装了一层镜像加速。SDK Manager 的 HTTP Proxy 设置里填的 Host 是一个国内镜像域名时所有请求会先去这个镜像由它决定是直接返回文件还是去源站拉取。理解这一点很重要因为你后续要判断配置是否正确看的就是请求最终落到了哪个地址。2.3 选镜像还是选代理几种场景的取舍实际工程里怎么选我一般是按场景来的。如果你只是个人开发机想快点下完 SDK 和依赖直接用国内镜像作为代理 Host 最省事不需要额外维护代理服务器而且教育网、云厂商的镜像长期稳定。如果你在的公司或实验室已经有一台专门的代理服务器那在 SDK Manager 里填内网代理更合适因为这种代理通常能同时解决 SDK、Gradle、Maven 仓库等多类流量的加速问题。还有一种混合情况就是你的网络环境本身访问某些网站没问题但访问 Google 仓库特定路径会超时。这种时候只给 SDK Manager 配代理其他流量走原网络是最干净的做法。配代理也好、配镜像也好本质都是把慢链路替换成快链路但两者不是等价的代理服务器本身如果在国内它访问海外源依然要过出境链路所以用国内镜像作为代理 Host 时其实是镜像站点帮你在国内完成了内容分发速度才有质的提升。3. Tools → SDK Manager图形界面下的代理配置全流程3.1 打开入口并认准版本差异GUI 配置代理的入口在 Android Studio 里通常有两处一处是顶部菜单栏的 Tools → SDK Manager另一处是欢迎界面右下角的 Configure → SDK Manager。打开 SDK Manager 窗口后左下角能看到 SDK Tools 标签页里面是各版本 Build Tools、平台工具、命令行工具的列表。代理设置在窗口右下角或者右上角不同版本位置稍有差异。老版本3.x 早期的入口是右下角的Proxy Settings点开是单独的小弹窗新版本4.x 之后改为右上角的齿轮图标点开后是完整的 SDK Manager Settings 窗口HTTP Proxy 区域就在里面。这个差异卡住过不少人网上搜到的截图经常和本地版本对不上。我的做法是认准齿轮图标不管它在右上角还是右下角点开来找 Proxy 字样就不会错。项目正文提到的步骤对应的就是带齿轮图标的这个版本。在 SDK Manager Settings 窗口中HTTP Proxy 部分有两个单选项Auto-detect proxy settings 和 Manual proxy configuration。选项适用场景风险Auto-detect proxy settings系统级代理已配好SDK Manager 直接沿用自动探测可能误判把系统代理用于内网访问时反而失败Manual proxy configuration明确知道代理/镜像地址和端口地址填错或端口不通时报错也直白3.2 手动代理配置Host、Port、账号密码的填写规则选择 Manual proxy configuration 之后界面会出现几个输入框。Host 填镜像域名注意不要带 http:// 前缀只填域名本身。Port 填镜像服务的端口常见是 80 或 443。如果镜像站点提供的是 HTTP 服务填 80HTTPS 服务填 443。有个容易弄错的点SDK Manager 这里填的代理端口是指该镜像对外提供 HTTP 代理服务的端口不是 Linux 上 SSH 或 Git 代理那种随机高端口。Host: mirrors.xxx.edu.cn Port: 80如果镜像站需要认证再在 Username 和 Password 里填入分配的凭证不需要认证的公共镜像这两个框留空即可。填完之后点 Apply 或 OK我建议先点 Apply 再点 OK因为 Apply 会立即让 SDK Manager 尝试用新配置连接仓库如果填错了当场就能在日志里看到报错不用等关闭窗口再打开。这里有个隐藏细节代理配置是全局的SDK Manager 窗口内所有标签页的组件下载都会走这个代理包括 SDK Platforms、SDK Tools、SDK Update Sites。项目正文里也提到Gradle 插件和 Google 服务框架的更新同样受这个代理影响。但要注意这只是 SDK Manager 自身的更新通道项目里的 Gradle 依赖下载如果走的是 Gradle 自己的网络栈那是另一套配置后面第 4 章会单独说。3.3 配置完成后验证代理是否生效很多人在这一步填完地址就以为是好了然后去装组件遇到失败又不知道问题在哪。其实配置完有必要的验证手段。先看 SDK Manager 主界面的左下角一般会有一个状态栏显示最近的网络活动如果显示正在连接或者正在刷新组件列表说明清单请求已经发出去了。这个时候打开 Android Studio 的日志Help → Show Log in Explorer会看到 SDK Manager 对应的日志文件里有当前 HTTP 代理地址的记录。更直接的验证方式是在系统终端里模拟一次请求看看目标镜像端口是否可达、响应是否正常# 检查镜像服务器 80 端口是否开放并测一下 HTTPS 通不通 nc -vz mirrors.xxx.edu.cn 80 # 用 curl 走代理拉取官方仓库的清单文件看能否取到内容 curl -o /dev/null -s -w HTTP %{http_code} 耗时 %{time_total}s\n \ --proxy http://mirrors.xxx.edu.cn:80 \ https://dl.google.com/android/repository/repository2-1.xml第一行命令验证端口连通性能通说明镜像服务器本身可达第二行命令验证代理转发能力走代理能拉到 200 响应说明 SDK Manager 配好之后请求链路是通的。如果第二行命令超时就去查是不是端口填错了或者镜像站不支持 HTTPS 请求的代理转发。验证完这两步再回 Android Studio 里点安装组件基本上不会再遇到配置完还是下载失败的情况。4. 不点界面的方案gradle.properties 与 sdkmanager 命令行的代理写法4.1 gradle.properties 里的 systemProp 系列参数SDK Manager 的图形界面配置只管 Android Studio 自身的组件下载但很多项目的依赖是要从 Google Maven 仓库拉取的这一层走的是 Gradle。Gradle 的代理配置独立于 SDK Manager写在项目根目录的 gradle.properties 文件里。这套参数以 systemProp 开头作用是给 Gradle 守护进程注入 JVM 系统属性从而影响它发起的网络连接。# 作用域项目级 Gradle 依赖下载Maven / 插件 systemProp.http.proxyHostmirrors.xxx.edu.cn systemProp.http.proxyPort80 systemProp.https.proxyHostmirrors.xxx.edu.cn systemProp.https.proxyPort80 # 若镜像站不需要代理访问内网地址用 noProxy 排除 systemProp.http.nonProxyHostslocalhost|127.0.0.1 systemProp.https.nonProxyHostslocalhost|127.0.0.1这些配置里http 和 https 要分开写因为 Gradle 拉取依赖时两种协议都会用到nonProxyHosts 用来绕过代理访问本机地址。需要留意的是gradle.properties 的代理配置优先级低于环境变量如果你的系统里已经设置了 HTTP_PROXY 环境变量Gradle 会优先读环境变量这时候改 gradle.properties 不生效。常见做法是不设置全局环境变量只在项目配置里管理代理这样每个项目的代理策略是独立的不会因为环境变量不同导致行为不一致。4.2 sdkmanager 命令行连接代理下载组件如果不想打开 Android Studio 界面或者做 CI 脚本需要在命令行装 SDK 组件可以用 sdkmanager 工具。这个工具在 SDK 的 cmdline-tools 目录下它自身支持代理参数。下面的命令演示了在命令行里配好代理并下载一个 Android 平台组件的过程# 列出可用组件前先确认代理能连通仓库 sdkmanager --list \ --proxyhttp \ --proxy_hostmirrors.xxx.edu.cn \ --proxy_port80 # 带代理下载 API 34 平台 sdkmanager --install platforms;android-34 \ --proxyhttp \ --proxy_hostmirrors.xxx.edu.cn \ --proxy_port80sdkmanager 的代理参数是三个独立的开关--proxy 指定协议http 或 socks--proxy_host 和 --proxy_port 分别指定代理地址和端口。第一次运行时它还会提示接受许可协议CI 环境里通常要加一个 yes 管道来跳过交互确认。这里有个参数细节sdkmanager 的代理协议只写 http但走的是 HTTP CONNECT 隧道所以访问 HTTPS 的仓库也是可行的不需要改成 socks。# CI 里自动接受所有许可协议再装组件 yes | sdkmanager --licenses --proxyhttp \ --proxy_hostmirrors.xxx.edu.cn --proxy_port804.3 设置后的验证方法curl 探测与依赖树检查配置完 Gradle 代理之后怎么确认生效我一般做两步验证。第一步看 Gradle 运行时实际走的链路可以在项目目录下执行构建命令时加上调试日志参数输出里能看到 HTTP 连接的目标地址。如果你看到连接的是官方的仓库域名说明代理没生效如果连接的是镜像域名说明 systemProp 已经被 Gradle 读取了。第二步用 curl 对比直连和走代理两种方式访问 Maven 仓库确认镜像确实在提供服务且内容完整# 直连测试 curl -o /dev/null -s -w 直连: HTTP %{http_code} 耗时 %{time_total}s\n \ https://dl.google.com/dl/android/maven2/com/android/tools/build/gradle/8.2.0/gradle-8.2.0.pom # 走代理测试 curl -o /dev/null -s -w 代理: HTTP %{http_code} 耗时 %{time_total}s\n \ --proxy http://mirrors.xxx.edu.cn:80 \ https://dl.google.com/dl/android/maven2/com/android/tools/build/gradle/8.2.0/gradle-8.2.0.pom看到代理那行 HTTP 200 且耗时明显低于直连Gradle 依赖这一步就算彻底通了。我在 CI 环境里还会把这两行 curl 的输出写入构建日志这样每次构建都能确认代理状态正常而不是等到依赖解析失败再回来查原因。5. 避坑代理配完仍然下载失败的五个常见问题5.1 现象填了代理地址点 OK 后 SDK Manager 白屏转圈原因Host 填的是镜像域名但端口填错成 443 而镜像只开放了 80 端口。SDK Manager 连接超时会一直卡在加载界面界面上没有任何错误提示。解决先用 nc 或 curl 确认正确端口再回 SDK Manager 修改。我踩过这个坑之后每次都会先用命令行确认端口通了再填 GUI避免界面白等。注意检查 Host 里是不是误带了 http:// 前缀带前缀也会导致解析失败。5.2 现象代理配置生效了但下载速度反而比直连还慢原因填的镜像站点本身质量不行。有些镜像因为使用者多或者带宽限制高峰期速度并不理想还有的镜像已经不再维护部分文件缺失SDK Manager 会回源获取缺失文件速度就回到直连水平。解决换一个镜像源优先选高校和大型云厂商维护的仓库。项目正文给的 mirrors.xxx.edu.cn 格式在 2020 年以前很稳定近年部分教育网镜像陆续关停选源的时候先看镜像的更新频率再用前面 3.3 节的 curl 命令测速挑一个下载耗时最低的。不要一直守着旧地址不放。5.3 现象代理配好后能刷新组件列表但安装组件时校验失败原因镜像同步不完整某个压缩包的校验值SHA-1和官方仓库不一致。SDK Manager 下载完文件后会和 XML 清单里的 SHA-1 比对不一致就报校验失败。解决这种情况不是本地配置的问题是镜像同步的问题。有点耐心等镜像同步完成或者换成另一个镜像源。我在 CI 脚本里做了本地缓存校验检测到 SHA-1 mismatch 就自动换源重试一次比手工换源效率高很多。5.4 现象Gradle 同步报错提示连接超时但 SDK Manager 下载正常原因SDK Manager 的代理配置和 Gradle 的代理配置是两套SDK Manager 走代理正常不代表 Gradle 也走了代理。Gradle 需要单独在 gradle.properties 里配置 systemProp 系列参数。解决按第 4.1 节的方法在项目根目录 gradle.properties 里补全代理配置。如果项目是多人协作我通常把代理配置放到全局的 ~/.gradle/gradle.properties避免每台机器都要改项目文件。5.5 现象代理配置正确但内网依赖下载报 403 或超时原因代理把访问内网仓库的请求也转发到了外网镜像镜像拒绝或超时。这是 nonProxyHosts 没配置导致的。SDK Manager 和 Gradle 都默认把代理应用于所有 HTTP/HTTPS 请求内网地址也不例外。解决在 gradle.properties 里设置 nonProxyHosts 排除内网域名比如公司内部的 Maven 仓库地址。SDK Manager 界面没有排除列表的选项所以如果你的项目还用内网的 SDK 镜像或者仓库Gradle 层一定要配 nonProxyHosts否则内网地址的请求被代理接管之后必挂。6. 进阶多镜像自动切换脚本告别手动改地址代理地址不稳定是常态今天这个镜像快明天可能就被关停了。手动改地址改到后面很烦躁尤其 CI 环境有几台机器要同步维护的时候。我写了一个简单的 bash 脚本自动探测多个镜像的连通性和速度选出最快的写入 gradle.properties整个流程十几秒就能完成。#!/usr/bin/env bash # mirror-switch.sh —— 自动探测可用镜像并写代理配置 MIRROR_HOSTS( mirrors.xxx.edu.cn:80 mirrors.example1.edu.cn:80 mirrors.example2.org:443 ) BEST_HOST BEST_TIME999 for item in ${MIRROR_HOSTS[]}; do host${item%%:*} port${item##*:} time_value$(curl -o /dev/null -s -w %{time_total} \ --connect-timeout 3 --proxy http://${host}:${port} \ https://dl.google.com/android/repository/repository2-1.xml) if [ $(echo $time_value $BEST_TIME | bc) 1 ]; then BEST_TIME$time_value BEST_HOST$host:$port fi done if [ -n $BEST_HOST ]; then cat ~/.gradle/gradle.properties EOF systemProp.http.proxyHost${BEST_HOST%%:*} systemProp.http.proxyPort${BEST_HOST##*:} systemProp.https.proxyHost${BEST_HOST%%:*} systemProp.https.proxyPort${BEST_HOST##*:} EOF echo 已切换到 ${BEST_HOST}探测耗时 ${BEST_TIME}s fi脚本的核心逻辑是遍历候选镜像列表用 curl 携带代理访问官方仓库的 XML 清单文件计时得到每个镜像的响应耗时挑出最小值的镜像写入全局 Gradle 配置。这里有几个参数值得注意connect-timeout 设为 3 秒避免某个镜像不可达时白白等待用 bc 命令做浮点数比较因为 curl 返回的 time_total 是带小数的秒数。脚本最后把配置写到用户目录的全局 gradle.properties而不是项目目录这样当前用户所有项目的 Gradle 依赖下载都会自动走最快的镜像。这个脚本解决的不只是手动改地址的麻烦它把代理配置变成了可自动化、可观测的环节。从那以后我每次配新环境都强制走一遍这个脚本再在终端确认输出里选了哪个镜像确认比手动点界面快得多。如果你也需要管理多台机器的 Android 环境试着把它集成进初始化脚本希望帮到你。本文还有配套的精品资源点击获取