SDK Manager镜像源配置与Gradle依赖下载加速指南

简介：面向Android开发者的SDK代理配置参考文档，聚焦官方渠道下载缓慢、组件更新不稳定等常见问题，适合需要改善SDK Manager网络访问效率的初中级开发者查阅。压缩包内共1个docx文件，大小约102KB，内容精简，便于快速了解代理设置所涉及的镜像源、主机端口、身份验证等参数，也提到教育网镜像与企业云镜像的选用思路。文档围绕自动检测和手动代理两种模式整理说明，并提示代理需随网络环境变化及时调整，可作为配置失败或下载受阻时的对照材料。已有862人学习，能帮助读者理解镜像源选择、代理生效范围以及Gradle插件、Google服务框架等依赖更新场景，减少反复试错的时间消耗，提升Android开发环境搭建与同步的稳定性，对频繁更新组件的开发场景也较实用，并降低环境同步成本。

1. 从一次 SDK Manager 卡在 2% 说起：镜像源设置到底改了什么

SDK 设置镜像源这件事，很多人第一次是在 SDK Manager 里卡住的。新装 Android 开发环境，勾选平台和构建工具，进度条走到 2% 不动，日志里只有重复的重试记录。默认下载链路要访问海外仓库，索引文件和几十 MB 的组件包在普通宽带上很容易断。把 SDK Manager 的网络出口指到国内镜像站后，同一批组件往往几分钟内下完。它解决的是 SDK 组件下载慢、反复失败的问题，适合刚配环境的新手，也适合需要批量装多版本 SDK 的从业者。需要先说明：这里改的是 SDK Manager 的 HTTP 转发配置，不是系统全局网络设置，也不是每个项目都要改的 Gradle 仓库；两件事分开看，后面才不会白折腾。

2. 在 SDK Manager 里配 HTTP 转发：界面路径、参数与一次跑通

2.1 先弄清 SDK Manager 的下载链路：为什么改一个地址就能提速

SDK Manager 不是一个简单的下载器。它先拉取仓库索引，再根据索引里的包名、版本、校验值和文件路径去取具体组件。默认情况下，索引和包都指向海外仓库，普通家庭宽带访问时容易出现首包慢、连接重置、下载到一半断流。镜像站做的是同构同步：把仓库目录、索引文件、zip 包按原结构放一份在国内入口，SDK Manager 仍然按原来的协议请求，只是请求先到达镜像主机。这个动作落在 SDK Manager 自己的网络设置里，不会改操作系统的全局路由，也不会影响浏览器和其他开发工具。

我一般把这条链路拆成三段看。第一段是索引请求，常见文件是repository2-1.xml一类的仓库描述；第二段是组件包请求，按platforms;android-xx、build-tools;xx.x.x这样的包名定位；第三段是本地解压和校验，落在 SDK 根目录和缓存目录里。镜像源配置只影响前两段，第三段出问题通常表现成“下载完了但安装失败”，排查方向完全不同。很多人把下载慢、安装失败、Gradle 依赖慢混成一件事，最后在 SDK Manager 里反复改 Host，问题却没动。

还有一点容易混淆：SDK Manager 里的网络设置是给当前 IDE 实例用的，不是给整个系统用的。你在里面填了镜像主机，命令行工具sdkmanager不一定自动继承；你在 Gradle 里配了 Maven 镜像，SDK Manager 也不会跟着变。后面第 3 章会讲 Gradle 那条链路，这里先把 SDK Manager 这一段走通。不同版本的 IDE 界面文案会有差异，有的把设置放在齿轮图标里，有的叫 SDK Manager Settings，但核心字段就那几个：自动检测、手动配置、Host、Port、用户名、密码。记住这个结构，换版本也不容易迷路。

2.2 操作步骤：从 Tools 到 SDK Manager Settings 的完整点击路径

先打开 Android 开发 IDE，进入主界面后不要急着点新建项目。顶部菜单栏找到 Tools，下拉里选 SDK Manager；如果当前项目已经打开，也可以在欢迎页的右下角找到 SDK Manager 入口。窗口打开后，左侧或底部会看到 SDK Platforms、SDK Tools 等标签页，先切到 SDK Tools，因为这里才是管理构建工具、平台工具、模拟器组件的地方。右上角或左下角有一个齿轮图标，点开后出现 SDK Manager Settings，网络配置就在这个弹窗里。

接下来的操作按顺序走：

1. 在 SDK Manager Settings 里找到 HTTP 转发区域，先看是自动检测还是手动配置。
2. 如果公司网络有透明出口，自动检测可能能用；但大多数家庭网络和普通办公网络建议直接选手动配置，避免自动检测拿到一个不可用的系统设置。
3. Host 填镜像站主机名，不要带http://，也不要带路径。比如示例地址写成mirrors.example.edu.cn，不是https://mirrors.example.edu.cn/android。
4. Port 填镜像站提供的端口，常见是 80 或 443；如果镜像站只开了 HTTPS，就填 443，如果只提供 HTTP 入口，就填 80。
5. 如果镜像站要求认证，再填用户名和密码；不需要认证就留空，不要随手填一个，否则会出现 407。
6. 点 Apply 或 OK 保存，关掉设置弹窗，回到 SDK Manager 主界面。
7. 勾一个体积较小的组件先试，比如platform-tools或某个build-tools，不要一上来就勾十几个 GB 的模拟器镜像。
8. 观察下载日志和进度条，如果速度明显变化，再继续勾选其他组件。

在填之前，我习惯先用命令行确认镜像主机是否可达，避免在 IDE 里反复点 Apply。下面这段只做连通性检查，不修改任何系统配置：

# 检查镜像站是否响应 Android SDK 仓库的索引文件 # -I 只取响应头，--max-time 8 避免长时间卡住 curl -I --max-time 8 \ https://mirrors.example.edu.cn/android/repository/repository2-1.xml # 如果上面返回 403/404，换一个常见路径再试，确认是路径问题还是主机问题 curl -I --max-time 8 \ http://mirrors.example.edu.cn/android/repository/repository2-1.xml

这段代码里的域名是示例占位，实际要换成你手头可用的镜像站地址。-I的作用是只发 HEAD 请求，速度快，不会把整个索引文件拉下来；--max-time 8是给自己一个止损时间，超过 8 秒没响应就先别在 IDE 里折腾。返回 200 或 304 说明主机和路径基本可达；返回 403 可能是目录没开放，返回 404 多半是仓库前缀写错，连接超时则先检查本机网络和端口。注意，这里测的是镜像站的仓库路径，不是镜像站首页，首页能打开不代表 SDK 仓库目录可用。

2.3 参数怎么填：Host、Port、认证与镜像目录的对应关系

Host 字段最容易填错。它要的是主机名，不是完整 URL，也不是仓库路径。有人把https://mirrors.example.edu.cn/android/repository整段粘进去，SDK Manager 会把它当成一个奇怪的主机名，结果就是一直转圈。正确做法是只留mirrors.example.edu.cn，协议和路径由 SDK Manager 自己拼接。Port 也要和协议对上：如果镜像站提供的是 HTTPS 入口，通常填 443；如果只提供 HTTP 入口，填 80。不要看到浏览器地址栏是 HTTPS 就默认端口一定是 443，有些镜像站会用非标准端口，这种信息只能从镜像站说明里拿，不能猜。

认证字段要看镜像站要求。公开镜像一般不需要用户名密码，留空即可；如果填了认证信息但镜像站不校验，有的客户端会直接发认证头，反而被网关拒绝。需要认证的镜像，用户名密码通常由镜像站管理员提供，不要拿自己的邮箱密码去试。还有一类情况是公司内网镜像，需要域名加端口，但不需要认证，这种就把认证字段清空，只保留 Host 和 Port。

如果镜像站只同步了部分仓库，还要看它是否包含你需要的组件。比如某些镜像只同步platforms和build-tools，没有同步模拟器镜像，那你勾模拟器时仍然会慢，甚至回落到默认源。这个时候不要怀疑 Host 填错，先看镜像站的目录说明。实际排查时，我会把浏览器地址栏里的仓库索引路径和 SDK Manager 日志里的请求路径对一遍，路径一致但包不存在，就是镜像同步范围的问题；路径不一致，才是 Host 或 Port 填错。

2.4 配完后的验证：看日志、看下载速度、看缓存目录

点完 Apply 不代表配置生效。最直接的验证是回 SDK Manager 勾一个几十 MB 的组件，观察进度条是否在动，以及日志里请求的主机是不是你填的镜像站。如果日志里仍然出现默认仓库域名，说明设置没保存成功，或者当前窗口没有重新读取配置。这个时候先关掉 SDK Manager 再重新打开，不要连续点 Apply，重复保存有时会让旧连接继续挂着。

第二个验证点是缓存目录。SDK Manager 下载过程中会在用户目录下写临时文件，下载完成后解压到 SDK 根目录。可以用下面这段命令看最近半小时有没有新文件落盘：

# 查看 SDK 缓存目录大小，以及最近 30 分钟内修改过的文件 du -sh ~/.android/cache 2>/dev/null find ~/.android/cache -type f -mmin -30 \ -printf '%TY-%Tm-%Td %TH:%TM %p\n' 2>/dev/null | head -20 # 如果 SDK 根目录是自定义的，把路径换成自己的 du -sh "$HOME/Android/Sdk" 2>/dev/null

du -sh看的是目录总大小，用来判断缓存有没有增长；find -mmin -30筛最近 30 分钟修改过的文件，用来确认下载动作确实发生了；head -20防止输出太长。如果缓存目录一直不增长，但进度条在走，可能是 IDE 把临时文件放在别处，或者下载被代理层拦截后反复重试。这个时候不要只看 UI，去日志里搜Download、Failed、Timeout这些关键字，比盯着进度条有用。

第三个验证点是安装结果。下载完成后，SDK Manager 会显示组件的版本和状态；如果状态是 Installed，但新建项目仍然报找不到 SDK，问题就不在下载链路，而在项目里的 SDK 路径配置。这种“下载成功但项目不认”的情况，我见过好几次，最后都是local.properties里的sdk.dir指到了旧目录。把下载和项目配置分开验证，能少走很多弯路。

3. 不止 SDK：把镜像配置同步到 Gradle、插件与依赖下载

3.1 Gradle 与 SDK Manager 是两条链路：为什么 SDK 快了 Gradle 还慢

SDK Manager 的镜像源配好之后，很多人会以为新建项目也会跟着快，结果 Gradle 同步仍然卡在下载插件。原因是两条链路完全独立：SDK Manager 下载的是 Android SDK 组件，走的是 SDK 仓库；Gradle 下载的是构建插件和 Java 依赖，走的是 Maven 仓库和插件门户。你在 SDK Manager 里填的 Host 只对前者生效，后者不读这个设置。要把 Gradle 也提速，得单独改仓库地址，或者用初始化脚本统一替换。

这一步的选型要看团队习惯。个人开发可以在项目根目录的settings.gradle和build.gradle里改仓库，但项目一多，每个仓库都要改一遍，后面合并代码还容易冲突。更稳妥的做法是用用户目录下的init.gradle，在 Gradle 启动时统一注入仓库，项目文件保持干净。公司团队可以把这份脚本放进开发环境初始化流程，新机器装完 IDE 后跑一次，后面新建项目就不用重复配。注意，init.gradle的优先级和仓库顺序会影响解析结果，镜像仓库要放在前面，但不要把所有官方仓库都删掉，保留一个兜底入口，镜像缺包时还能回落。

还有一种常见误判：SDK Manager 下载快了，但 Gradle 同步慢，于是回头把 SDK Manager 的 Host 改成另一个地址，结果 SDK 又慢了。正确顺序是先分别确认两条链路的日志，再决定改哪边。Gradle 同步卡住时，看--info日志里正在请求哪个仓库；SDK Manager 卡住时，看它请求的是哪个索引。两边日志里的域名不一样，改错地方就是白忙。

3.2 用 init.gradle 统一替换仓库：避免每个项目改 build.gradle

下面这份init.gradle放在用户目录的.gradle下，Gradle 启动时会自动加载。它把项目仓库和插件仓库都指到示例镜像，同时保留中央仓库作为兜底。实际使用时把示例域名换成你确认可用的镜像地址：

// ~/.gradle/init.gradle // 统一给所有项目注入镜像仓库，避免逐个改 build.gradle allprojects { repositories { // 示例镜像，按团队实际可用地址替换 maven { url "https://maven.example.com/repository/android/" } maven { url "https://maven.example.com/repository/central/" } // 保留兜底仓库，镜像缺包时不至于直接失败 maven { url "https://repo.example.com/central/" } } } settingsEvaluated { settings -> settings.pluginManagement { repositories { maven { url "https://maven.example.com/repository/gradle-plugins/" } maven { url "https://maven.example.com/repository/central/" } // 插件门户作为兜底 gradlePluginPortal() } } }

这段脚本分两块：allprojects管普通依赖，settingsEvaluated管插件解析。很多项目只改前者，结果插件还是从默认门户拉，同步依旧慢。maven { url ... }里的地址必须指向 Maven 仓库根路径，不是浏览器页面地址；末尾斜杠建议保留，避免部分镜像对路径拼接敏感。gradlePluginPortal()是兜底，不建议全部删掉，镜像没有同步某个插件时，没有兜底会直接报找不到插件。

放好脚本后，用gradle --version或 IDE 的 Gradle 同步验证是否加载。如果项目里原本写了repositoriesMode之类的限制，初始化脚本可能不生效，需要看项目自身的仓库策略。还有一种情况是镜像仓库有包但元数据不全，Gradle 会报“找不到某个 classifier”，这种不是网络问题，换回兜底仓库或换镜像版本更直接。

3.3 插件与移动服务框架的下载：哪些能走镜像，哪些不能

不是所有组件都适合走同一个镜像。Android SDK 组件、Gradle 插件、Java 依赖、移动服务框架，这四类东西的仓库结构不一样，镜像同步范围也不一样。下面这张表是我排查时常用的对照：

移动服务框架这类组件最容易踩坑。有些框架的包放在专用仓库里，镜像站没有同步，你把 Host 指过去也找不到；有些框架同时提供 SDK 仓库和 Maven 仓库两个入口，需要分别配置。判断方法很简单：看依赖坐标里的 group 和 artifact，再到镜像仓库的目录里找对应路径。找不到就说明镜像没同步，换回默认仓库或者找团队内部制品库，不要在一个 Host 上反复试。

3.4 批量装 SDK 组件的命令行方式：sdkmanager 与缓存核对

IDE 里勾选适合第一次配置，批量装多版本时命令行更省事。sdkmanager在 SDK 的cmdline-tools目录下，先确认它用的是哪个 SDK 根目录，再列出可安装包。下面这段只做列表和安装，不涉及系统网络设置：

# 指定 SDK 根目录，列出前 40 行可安装组件 sdkmanager --sdk_root="$HOME/Android/Sdk" --list | sed -n '1,40p' # 安装指定平台和构建工具，包名必须和列表里完全一致 sdkmanager --sdk_root="$HOME/Android/Sdk" \ "platforms;android-34" \ "build-tools;34.0.0" # 查看已安装包，确认版本和路径 sdkmanager --sdk_root="$HOME/Android/Sdk" --list_installed

--sdk_root很重要，不指定时它可能用环境变量里的旧路径，装完你在 IDE 里看不到。--list输出很长，用sed -n '1,40p'只看开头，确认命令能跑通；--list_installed用来核对结果。命令行的网络设置不一定和 IDE 界面完全同步，如果命令行仍然慢，先看它读的是哪个配置文件，不要直接改系统环境变量。实际排查时，我会先用命令行装一个小包，确认路径和权限没问题，再回到 IDE 批量勾选。

4. 避坑与排查：镜像地址填错、端口不通、证书拦截的 5 个现场

4.1 现象：点 Apply 后一直转圈，日志里 403 或 404

这是最常见的翻车现场。现象是 SDK Manager 进度条不动，日志里反复出现 403 或 404，偶尔夹着超时。原因通常有两个：Host 填了完整 URL 或仓库路径，客户端把它当主机名解析；或者镜像站没有同步你要的那个组件，索引能拉到，但具体包路径不存在。解决方法是先把 Host 改成纯主机名，去掉https://和后面的路径；再用浏览器或curl测仓库索引路径，确认镜像站确实提供 SDK 仓库。如果索引可达但某个包 404，换一个组件试，能下就说明是镜像同步范围问题，不是配置问题。

我遇到过一种更隐蔽的情况：镜像站首页能打开，但仓库目录需要特定前缀，比如/android/repository，而 SDK Manager 只填主机名时默认拼的是根路径，结果就是 404。这种只能看镜像站说明，确认它兼容的仓库结构。不要靠猜路径，猜错一次浪费十几分钟。

4.2 现象：设置保存了，下载速度却没变化

现象是 Apply 成功，重新打开设置也能看到 Host，但下载还是慢。原因可能是当前 SDK Manager 窗口没有重新建立连接，旧连接还在用之前的设置；也可能是你只改了 SDK Manager，但实际卡住的是 Gradle 同步。先关掉 SDK Manager 再打开，勾一个小包试；如果小包快、大包慢，看是不是镜像限速或大文件回落到默认源。再看日志里的请求域名，确认走的是镜像主机。如果日志里仍是默认域名，检查是不是开了自动检测，自动检测有时会覆盖手动配置。

还有一种情况是镜像站对并发连接有限制，你一次勾太多组件，每个连接都排队，看起来就像没提速。解决方法是先装平台工具和构建工具，模拟器镜像单独装，不要一次性全选。

4.3 现象：SSL handshake failed 或证书校验失败

现象是下载刚开始就报 SSL 握手失败，或者提示证书不受信任。原因可能是公司网络做了中间证书拦截，也可能是镜像站只提供 HTTP 入口，而你填了 443。先确认镜像站支持的协议和端口，HTTP 入口就填 80，不要硬套 443；如果是公司网络证书问题，找网络管理员要根证书并导入开发环境，不要关掉证书校验，关掉之后其他依赖下载也会出问题。临时验证可以用curl -I看握手是否成功，再决定是换端口还是换镜像。

4.4 现象：407 认证失败，或者填了用户名密码反而更慢

现象是日志里出现 407，或者填了认证信息后请求被反复拒绝。原因通常是镜像站不需要认证，但你在 Username 和 Password 里填了内容；或者镜像站需要认证，但账号密码不对。解决方法是先清空认证字段，只留 Host 和 Port 试一次；如果镜像站明确要求认证，再按提供的信息填，不要用个人邮箱密码。认证失败时不要连续重试，有些网关会临时封禁频繁失败的来源。

4.5 现象：下载到一半卡住，重试后提示缓存损坏

现象是进度条走到一半停住，关掉重开提示某个 zip 校验失败。原因多半是断点续传的文件不完整，或者磁盘空间不足。解决方法是先看磁盘剩余空间，再删掉对应的临时缓存文件，重新下载。不要直接删整个 SDK 目录，那样已安装的组件也要重装。缓存目录通常在用户目录的.android/cache下，删之前确认没有其他下载任务在跑。如果同一个包反复损坏，换镜像站或换时间段再试，别在同一个入口上死磕。

5. 进阶：用脚本验证镜像可用性与固化团队配置

5.1 三行脚本做镜像健康检查

换开发机、换网络、换镜像站之后，我第一件事不是打开 IDE，而是跑一遍镜像健康检查。下面这段脚本接受一个镜像仓库前缀作为参数，检查索引文件和附加列表的响应码：

#!/usr/bin/env bash # 用法：./check_mirror.sh https://mirrors.example.edu.cn/android/repository set -euo pipefail MIRROR="${1:-https://mirrors.example.edu.cn/android/repository}" for path in repository2-1.xml addons_list-5.xml; do code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 8 "$MIRROR/$path") echo "$path -> $code" done

$1是镜像仓库前缀，不传就用示例地址；for循环里放的是常见索引文件名，不同镜像可能只同步其中一个；curl -s -o /dev/null -w '%{http_code}'只输出状态码，不刷屏。200 或 304 表示路径可用，403 看目录权限，404 看前缀是否写错，000 多半是连接超时或 DNS 没解析。这个脚本不修改任何配置，适合放进团队初始化文档里，让每个人先自检再动手。

5.2 把配置写进团队初始化脚本

个人开发可以手动点，团队里最好把 SDK Manager 的配置和 Gradle 的init.gradle一起固化。我的习惯是准备一个初始化目录，里面放三样东西：镜像健康检查脚本、init.gradle模板、一份字段说明。新机器装完 IDE 后，先跑健康检查，再把init.gradle拷到用户目录的.gradle下，最后在 SDK Manager 里填 Host 和 Port。这样新人不用理解每条链路，也能一次配好。

提示：镜像站地址会变，端口和目录结构也可能调整，初始化脚本里不要把地址写死在一个地方，留一个变量或配置文件，换的时候只改一处。

从那以后我每次换开发机，都会先跑一遍镜像健康检查，再打开 SDK Manager，最后才新建项目。这个顺序看起来多了一步，但能少掉很多“到底哪条链路慢”的争论。希望帮到你。

本文还有配套的精品资源，点击获取