简介《SDK设置代理》是一份面向Android应用开发者及移动端学习者的docx操作文档聚焦官方SDK下载缓慢、网络受限时如何借助代理与国内镜像提升获取效率。文档围绕Android Studio的SDK Manager展开梳理自动检测与手动代理两种配置思路并说明主机地址、端口、身份验证信息及保存生效等关键环节同时提及Gradle插件、Google服务框架等依赖的同步更新和镜像源切换的注意事项。资源包仅含1个docx文件约102KB体量轻便适合随时查阅。已有862人学习说明其在SDK环境配置场景中具有一定参考价值。读者可据此快速定位代理设置入口理解镜像站点与端口填写逻辑减少反复试错并在网络环境变化时及时调整代理配置。1. 现象列表刷新不出来进度条卡在 3%装完 Android Studio 第一次打开 SDK Manager组件列表转圈刷不出、进度条卡在 3% 不动这是绝大多数人接触 SDK 设置代理的起点。SDK 并不是一个大压缩包而是几十个可单独下载的组件平台 API、构建工具、平台工具、模拟器系统镜像单是一个模拟器镜像就上 GB。这些组件默认从远端官方仓库拉取跨境链路长、并发连接多、断点续传体验差一次全量拉取能耗掉大半天。SDK 设置代理要做的事很具体把下载请求交给一个可达、稳定的中转节点让列表刷得出来、大包下得完。刚搭环境的新手、要给 CI 机器批量配环境的人、以及给团队统一开发环境的老手最终都会走到这一步。2. SDK Manager 的代理面板从 Tools 菜单到四个字段的完整落点2.1 为什么代理必须设在 SDK Manager 内部很多人第一次配置会走错门在 IDE 的 Settings → Appearance Behavior → System Settings → HTTP Proxy 里填完插件市场确实通了切回 SDK Manager 一看该转圈还是转圈。原因是 SDK Manager 有自己独立的 HTTP 客户端和下载调度逻辑它并不复用 IDE 主进程的代理设置。IDE 层的代理影响的是插件仓库、许可证校验这类请求SDK 组件清单repository XML和各组件的归档包zip由 SDK Manager 自己发请求。这两条管道的配置是分开的只配一处另一处就会出现「插件能装、SDK 装不动」这种反直觉现象。再往下还有一层要分清SDK Manager 面板里配的代理作用域是当前这个 IDE 实例。换一个 IDE 大版本、新开一个 profile、或者干脆改用命令行工具sdkmanager这份 GUI 配置都不一定被继承。我见过有人在 GUI 里配得好好的结果 CI 机器上跑sdkmanager --install一路超时排查了半天才发现命令行压根没读那份配置。所以面板是入口不是终点后面第 3 章会补上命令行和构建脚本那两套参数。还有一个容易被忽略的点代理和镜像站不是同一回事。代理是把请求交给中转节点由它替你取回镜像站是直接指向另一套仓库地址。原文给的那台高校镜像mirrors.neusoft.edu.cn严格来说属于镜像站用法把它填进 Host 字段是因为 SDK Manager 的代理面板只接受 host port 这种形式本质上是把那台服务器当成了一个 HTTP 中转在用。理解这点很重要后面第 4 章会讲清楚为什么 Maven 依赖不能靠这个面板解决。2.2 打开面板的路径与实际界面元素操作路径本身不复杂但每一步都有版本差异写清楚一点能少走弯路打开 Android Studio停在欢迎页或任意已打开工程都可以顶部菜单栏找Tools。下拉菜单里选SDK Manager。旧版本这个入口在Configure齿轮菜单里找不到 Tools 项的话去右下角找齿轮。SDK Manager 窗口打开后注意顶部或左侧的标签页切到SDK Tools。这里和 SDK Platforms 是两套清单代理设置对两者都生效但从 Tools 页进入设置更顺。找窗口里的齿轮图标或Settings按钮。不同版本它的位置在右上角或右下角图标形态是一个小齿轮鼠标悬停会显示 SDK Manager Settings。弹出SDK Manager Settings窗口找到HTTP Proxy区块。这个区块里通常有三个单选No proxy、Auto-detect proxy settings、Manual proxy configuration。原文只提了后两个实际排错时第一个同样关键——你怀疑配置被污染、想验证直连能不能通时就是切回 No proxy 做一次对照实验。切换后要点Apply或OK保存SDK Manager 会在下一次刷新清单时使用新设置。界面上还有一行小字提示大意是「这些设置只影响 SDK Manager 自身的下载」。这句话值得认真读它就是 2.1 那套结论的官方确认。2.3 Host、Port、用户名密码四个字段怎么填填错字段是最高频的翻车点逐项拆开说字段该填什么常见取值填错的典型症状Host纯域名或 IP不带协议头、不带路径mirror.example.edu.cn这类机构镜像或内网代理地址填了http://xxx或带/路径点 OK 后报 URL 非法或下载直接 400Port与协议对应的端口号80HTTP、443HTTPS、内网代理常见8080/3128端口错填成 443 但镜像只开 80表现为连接被拒或 TLS 握手超时Username需要认证时才填内网代理的域账号不需要认证时乱填请求会返回 407Password同上—密码含特殊字符未转义认证失败Host 字段的坑要重点说。这个框只接受主机名你写https://mirror.example.edu.cn/sdk这种完整 URL 进去它不会帮你解析出主机部分只会原样拼进请求路径里结果就是一个语法正确但语义荒谬的地址。原资源里给的是mirrors.neusoft.edu.cn实际使用时把域名换成你自己网络环境下可达的那台镜像或代理主机即可方法论不变主机名进 Host端口进 Port协议靠端口号隐式表达。端口这一项的判断依据是镜像站对外暴露的服务。多数公共镜像同时开 80 和 443优先用 443因为 SDK 清单和包下载走 HTTPS 时链路更不容易被中间设备干扰。如果镜像只开了 80 而你填 443症状是连接超时而不是快速失败会误以为是网络慢。注意认证信息是明文存在 IDE 配置里的团队共用机器或把配置目录提交进版本库之前先确认里面没有账号密码。2.4 Auto-detect 与 Manual 的选择边界Auto-detect 的语义是读取系统级代理设置或 PAC 脚本。它适合两种场景一是公司统一配了系统代理PAC 自动分流你不想手动维护二是移动办公系统代理随网络环境自动切换。它的短板也很明显——PAC 的判定逻辑对 Java 进程不一定友好SDK Manager 拿到的可能是「直连」这个结论而实际上你需要走代理。表现就是系统浏览器能开网页SDK Manager 却一直转圈。Manual 是确定性最高的选项四五个字段填死不受系统设置漂移影响。工程实践里我一般直接选 Manual把 Host 和 Port 写死理由很简单环境问题最怕的就是「有时候能通有时候不能通」Manual 至少能把变量收敛到一个地方。真正需要自动化的场景CI、多环境切换交给第 3 章的命令行参数和环境变量而不是指望这个 GUI 单选。还有一个中间态先在 Manual 里填好镜像跑一次全量下载或一次--list如果失败切 Auto-detect 再试一次。两次结果对比能快速判断问题出在代理地址本身还是系统的代理策略上。2.5 保存之后怎么确认设置真的生效点完 OK 不代表生效得有一次可观察的验证。最省事的做法是回到 SDK Manager 主界面切到SDK Platforms勾选Show Package Details然后看列表能不能在十几秒内刷出带版本号的完整清单。清单文件本身很小如果连它都要等一两分钟说明请求没有走到你配的那个节点上。更可靠的是看日志。SDK Manager 窗口里有Show Log之类的入口或者去 IDE 的日志文件里搜Downloading、Connection、proxy这几个关键词能看到实际请求的目标地址。请求 URL 里的域名应该和你填的 Host 一致如果不一致说明配置没被读到或者被更高优先级的设置覆盖了第 3 章的优先级顺序会讲。还有一种情况设置生效了但缓存里存着上一次失败留下的半截文件导致重试仍然报错。这时候清掉本地缓存目录再试路径一般在用户目录下的.android/cache把它挪走而不是直接删方便回溯。3. 只点 GUI 不够gradle.properties 与命令行 sdkmanager 两套参数3.1 GUI 配置的三个漏配点GUI 面板只覆盖 SDK Manager 这一条下载通道剩下三条常见通道它都管不到第一条是Gradle 自身的依赖下载。项目 sync 时拉插件、拉依赖库走的是 Gradle 的 HTTP 客户端跟 SDK Manager 完全是两套东西。表现是 SDK 装得好好的一 sync 就卡在Downloading https://...不动。第二条是命令行sdkmanager。它在cmdline-tools/latest/bin/下是独立可执行程序不读 IDE 的配置。CI 机器上只有命令行工具没有 IDE所以必须用参数或环境变量单独配。第三条是avdmanager和模拟器镜像下载。镜像包动辄几个 GB走的通道和 SDK 组件下载接近但不完全等同GUI 里配的代理能覆盖一部分命令行场景下依然要单独处理。这三条通道各自的配置语法还不一样混用是最常见的错误来源。下面逐条给可抄的写法。3.2 gradle.properties 里的 systemProp 四行在项目根目录的gradle.properties或者用户目录下的~/.gradle/gradle.properties里追加# HTTP 通道代理很多镜像站的清单走 http systemProp.http.proxyHostmirror.example.edu.cn systemProp.http.proxyPort80 # HTTPS 通道代理端口单独写不要想当然复用上面那个 systemProp.https.proxyHostmirror.example.edu.cn systemProp.https.proxyPort443 # 需要认证时才有用不需要就整行删掉 systemProp.http.proxyUseryour_account systemProp.http.proxyPasswordyour_password # 内网地址不走代理分隔符是竖线不是逗号 systemProp.http.nonProxyHostslocalhost|127.0.0.1|*.internal.example逻辑说明systemProp.前缀是 Gradle 设 JVM 系统属性的约定等价于启动时加-Dhttp.proxyHost...。http 和 https 是两套独立属性这是 Java 网络栈的历史设计只配 http 那一对时所有 https 请求仍然直连症状就是「http 镜像能通、https 依赖拉不下来」。proxyUser/proxyPassword只在目标需要 Basic 认证时生效不需要认证时留着反而可能干扰。nonProxyHosts的分隔符必须是|写逗号不生效而且它不支持 CIDR 网段只认主机名和*.通配。公司内网有私有仓库时这一行不加的后果是私有仓库请求也被送去代理直接 404 或超时。放在用户级~/.gradle/gradle.properties而不是项目里的好处是不用担心误提交坏处是换机器要重新配一遍团队协作场景建议项目里放一份脱敏模板真实凭据走环境变量注入。3.3 命令行 sdkmanager 的 --proxy 参数命令行工具的代理参数是独立的一组写法如下# 先确认 sdkmanager 在 PATH 里或用绝对路径调用 # 常见位置$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager # 列出可安装包用代理走一次验证链路 sdkmanager --list \ --proxyhttp \ --proxy_hostmirror.example.edu.cn \ --proxy_port80 # 确认清单能拉到之后再装具体组件 sdkmanager --install platform-tools platforms;android-34 \ --proxyhttp \ --proxy_hostmirror.example.edu.cn \ --proxy_port80逻辑说明--proxyhttp指定代理协议类型--proxy_host和--proxy_port分别对应 GUI 里的 Host 和 Port三个参数必须同时给少一个会直接报参数错误而不是静默直连——这点比 GUI 友好。安装具体组件时包名要写全platforms;android-34这种带分号的写法在 shell 里要加引号否则分号会被 shell 解释成命令分隔符这是纯语法坑报错信息完全看不出原因。--list这一步不要跳过。它请求的清单文件很小能在几秒内返回就说明代理链路是通的返回慢或者超时问题在代理地址或端口而不是网络带宽。先小后大是排查下载类问题的基本节奏。3.4 环境变量兜底与优先级有些工具链不读gradle.properties也不吃命令行参数只认环境变量。通用写法# 注意这里必须带协议头和 gradle.properties 的写法完全不同 export HTTP_PROXYhttp://mirror.example.edu.cn:80 export HTTPS_PROXYhttp://mirror.example.edu.cn:443 export NO_PROXYlocalhost,127.0.0.1,.internal.example逻辑说明环境变量版本必须带http://前缀而gradle.properties里的proxyHost绝对不能带前缀。这两个规则正好相反是最高频的混淆点。NO_PROXY用逗号分隔也接受域名后缀形式和nonProxyHosts的竖线分隔不同。大小写方面多数工具同时认HTTP_PROXY和小写版本为兼容性建议大写。优先级大致是命令行显式参数 项目级gradle.properties 用户级gradle.properties 环境变量。真出问题时不要靠猜用第 3.5 节的验证手段直接看请求落到哪儿。3.5 三种验证手法从粗到细第一种用curl直接探镜像的清单地址确认主机和端口可达# -I 只取响应头快速判断连通性-m 设超时避免长时间挂着 curl -I -m 10 http://mirror.example.edu.cn/android/repository/repository2-3.xml返回 200 或 304 说明主机和端口没问题返回连接超时说明端口填错了返回 403/407 说明认证缺失。第二种跑sdkmanager --list并观察耗时。清单能出来但组件下载仍然停滞说明代理只覆盖了清单请求大包下载可能走了另一条通道回去检查gradle.properties和实际安装命令是否都带了参数。第三种Gradle 加--info跑一次 sync日志里搜Downloading和Resource missing看请求 URL 里的主机名。主机名不对说明配置没生效主机名对但状态码是 4xx说明代理侧的策略或路径有问题。4. 换镜像不只改代理把 google() 换成镜像仓库的三处写法4.1 代理和换源解决的不是同一件事代理是中转请求还是发往原地址只是绕了一个节点换源是改变目标地址请求直接打到另一套仓库。SDK 组件下载和 Maven 依赖下载是两条不同的管道前者靠 SDK Manager 的代理配置后者靠 Gradle 的仓库声明。很多人把这两件事混为一谈配完代理发现 sync 还是慢就是因为 Maven 仓库那一侧压根没动。判断依据很直接看卡住的那一行日志里的 URL。域名是dl.google.com、repo.maven.apache.org这类属于 Maven 依赖要换仓库域名是 SDK 清单或组件包属于 SDK Manager要走代理。两者可以同时配互不冲突。4.2 settings.gradle 里的 repository 声明顺序新版本 Gradle 把仓库声明收敛到了settings.gradle示例// settings.gradle dependencyResolutionManagement { // 禁止子模块自行声明仓库统一收口避免各处配置不一致 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { // 镜像放最前命中就返回命中不了才往下走 maven { url https://maven.example-cn.example/repository/public/ allowInsecureProtocol false } // 官方仓库兜底保证镜像缺包时项目还能构建 google() mavenCentral() } }逻辑说明仓库按声明顺序依次尝试命中即停所以镜像必须放在官方仓库前面否则等于没换。allowInsecureProtocol false是显式声明只用 HTTPS避免被降级到明文 HTTP如果你的内网镜像确实只有 HTTP才需要打开它同时要清楚这意味着凭据和内容在链路上是可见的。FAIL_ON_PROJECT_REPOS这一行的作用是让子模块里的repositories {}直接报错强制所有仓库声明集中在settings.gradle。多人协作项目里这条能省掉大量「我这能编你那不能编」的扯皮代价是老项目迁移时要清一遍子模块配置。Kotlin DSL 项目写法等价只是语法变成maven { url uri(...) }语义不变。4.3 三种镜像形态的取舍形态做法优点短板适用全量公共镜像一个地址代理全部公共仓库配置最简一行搞定冷门 artifact 可能缺同步有延迟个人项目、学习环境只镜像特定源只把 Google 系仓库指过去其余走官方缺包风险小职责清晰配置行数多要逐个对齐依赖 Google 系组件的中大型项目内网聚合仓库自建或团队维护一个聚合入口统一出网可控、可审计、可缓存需要人维护首次拉取仍慢团队协作、CI 环境选择逻辑按团队规模走一个人开发全量公共镜像够用三五个人的小团队聚合仓库的维护成本摊下来是划算的因为缓存命中率高了以后 CI 时间能明显下降再大的团队基本都会有内部的制品管理方案这时候settings.gradle里的地址就应该只指向内网公网仓库作为兜底甚至可以不写。4.4 换源后解析失败的三类报错第一类Could not resolve后面跟着Received status code 404。原因是镜像没有同步到那个 artifact或者路径拼错了。处理方式是临时把官方仓库提到前面验证一次能过就说明是镜像缺包把该 group 加进镜像的排除列表让它走官方。第二类Could not GET ... Received status code 407。这是代理认证错误通常发生在镜像本身又套了一层需要认证的代理或者gradle.properties里残留了失效的凭据。清掉proxyUser/proxyPassword两行再试。第三类校验和不匹配或Checksum failed。原因是镜像返回的内容和官方校验值对不上可能是同步中断留下了损坏文件也可能是中间设备改写了响应。这类问题不要试图绕过校验换一个镜像源或等同步完成。5. 排查清单五条踩坑记录与逐条定位手法5.1 现象清单能刷出来大包下载始终 0 KB/s原因清单文件是几百 KB 的 XML走的是轻量请求组件包是几百 MB 到几 GB 的归档走的是分块下载。很多镜像站对清单做了完整缓存对归档包却是回源转发回源链路一旦拥塞表现就是清单秒开、包不动。另一个可能是并发数被限SDK Manager 默认会开多个连接镜像侧限流后全部挂起。解决先换一个时间点重试排除源站高峰期。持续不动的话把大包拆成单个组件装别一次勾十几个——sdkmanager --install platform-tools单独跑一次能通说明是并发或总量问题而非链路不通。仍然不行就换镜像或者直接走离线包方案第 6 章。5.2 现象Host 填完点 OK 直接弹红字提示 URL 非法原因Host 字段只接受主机名填进去的内容如果带了http://、https://、结尾斜杠或者路径校验就过不去。另一个隐蔽原因是复制粘贴时带进了不可见字符比如从文档里拷过来的全角冒号或尾部空格。解决把 Host 清空重打一遍只留xxx.yyy.zzz这种纯主机名形态端口单独填在 Port。粘贴来源不可靠时先粘到纯文本编辑器里过一遍再手工敲进输入框。5.3 现象Gradle sync 报 407但 SDK Manager 一切正常原因SDK Manager 的 GUI 配置不作用于 Gradle。Gradle 走的是gradle.properties里的systemProp或环境变量这两处如果还留着旧的、需要认证的代理地址就会返回 407。也可能是认证凭据里有特殊字符没转义比如密码里的或:。解决检查项目根目录和用户目录下两份gradle.properties把proxyUser/proxyPassword两行注释掉跑一次 sync 看报错是否变成 401 或直接超时。变成超时就说明是认证问题回去确认凭据仍是 407 说明代理侧策略要求认证而你没给。凭据含特殊字符时优先改用环境变量注入而不是写进 properties 文件。5.4 现象改回直连、删掉配置请求仍然走代理原因配置有多个落点——GUI 面板、项目gradle.properties、用户级gradle.properties、shell 环境变量、IDE 启动脚本里的 JVM 参数。你删了其中一个其余还在生效。环境变量尤其隐蔽因为它写在~/.bashrc/~/.zshrc里新开的终端全都带着。解决按优先级从高到低逐层排查。先在当前 shell 里env | grep -i proxy看有没有残留有就unset掉再试再检查两份gradle.properties最后回 GUI 面板切到No proxy保存。三层都清干净后重开 IDE配置文件是在启动时读的热改不一定立刻生效。5.5 现象能 ping 通镜像主机443 端口却连不上原因ICMP 可达不代表 TCP 可达。镜像站可能只对特定来源开放端口或者只监听 80 不监听 443也可能是中间网络设备对 TLS 握手做了限制。还有一种可能是本地防火墙对 Java 进程单独放行规则缺失浏览器能连、JVM 连不上。解决用curl -I -m 10分别测 80 和 443 两个端口的实际响应别用 ping 下结论。80 通 443 不通就把 Port 改成 80 再试两个都不通检查本地出站规则和镜像站的访问说明。TLS 握手阶段超时且 http 正常时说明问题在加密通道而不是网络可达性。6. 把代理配置固化下来离线包与模板化的收尾手法配置这件事最怕的是「每次换机器重来一遍」。做到第 5 章那些排查本质上都是在为一次没配好买单。真正省时间的做法是把不确定性提前消掉我一般走两条路。第一条是离线包。SDK Manager 支持导出和导入本地仓库结构思路是把已经下好的组件目录整体打包换机器时解压到ANDROID_HOME对应位置让 SDK Manager 认为这些组件已安装。要点是目录层级必须和官方仓库一致platforms/、build-tools/、platform-tools/各归各位package.xml这类元数据文件不能丢丢了就会出现「文件在但列表里显示未安装」。适合团队统一环境、CI 机器预热、以及网络条件确实很差的场景。代价是包体大、更新不及时所以我一般只在固定版本的构建机上用开发机还是走代理在线拉。第二条是配置模板化。把gradle.properties里那几行做成带占位符的模板真实的主机和凭据从环境变量读# gradle.properties 模板提交进版本库 systemProp.http.proxyHost${SDK_PROXY_HOST} systemProp.http.proxyPort${SDK_PROXY_PORT} systemProp.https.proxyHost${SDK_PROXY_HOST} systemProp.https.proxyPort${SDK_PROXY_PORT}这个写法有个前提Gradle 读gradle.properties时不做环境变量展开占位符得靠 CI 的模板渲染步骤或者启动脚本替换成实际值。所以我更常用的是反过来——文件里不写代理完全靠GRADLE_OPTS注入# CI 启动脚本里注入凭据从密钥管理系统读不落盘 export GRADLE_OPTS-Dhttp.proxyHost${SDK_PROXY_HOST} -Dhttp.proxyPort${SDK_PROXY_PORT} \ -Dhttps.proxyHost${SDK_PROXY_HOST} -Dhttps.proxyPort${SDK_PROXY_PORT}这样仓库里的配置文件是干净的谁也不需要为了跑一次构建去问别人要账号密码。验证是否注入成功跑一次./gradlew --version输出末尾会打印 JVM 参数能看到-D开头的几项就说明生效了。这个检查我加进了所有 CI 流水线的第一步比事后从构建日志里翻下载超时便宜得多。有个细节值得单独提端口号一定不要在两处写不同值。我吃过一次亏gradle.properties里 http 写 80、https 写 8080本地跑得好好的换到 CI 上所有 https 依赖全部超时日志里只有一句Connection timed out看不出任何线索。从那以后我每次改代理配置都强制走一遍「curl -I探两个端口 →sdkmanager --list探清单 →gradlew --version看 JVM 参数」这个三步验证再动项目代码。希望帮到你。本文还有配套的精品资源点击获取
简介《SDK设置代理》是一份面向Android应用开发者及移动端学习者的docx操作文档聚焦官方SDK下载缓慢、网络受限时如何借助代理与国内镜像提升获取效率。文档围绕Android Studio的SDK Manager展开梳理自动检测与手动代理两种配置思路并说明主机地址、端口、身份验证信息及保存生效等关键环节同时提及Gradle插件、Google服务框架等依赖的同步更新和镜像源切换的注意事项。资源包仅含1个docx文件约102KB体量轻便适合随时查阅。已有862人学习说明其在SDK环境配置场景中具有一定参考价值。读者可据此快速定位代理设置入口理解镜像站点与端口填写逻辑减少反复试错并在网络环境变化时及时调整代理配置。1. 现象列表刷新不出来进度条卡在 3%装完 Android Studio 第一次打开 SDK Manager组件列表转圈刷不出、进度条卡在 3% 不动这是绝大多数人接触 SDK 设置代理的起点。SDK 并不是一个大压缩包而是几十个可单独下载的组件平台 API、构建工具、平台工具、模拟器系统镜像单是一个模拟器镜像就上 GB。这些组件默认从远端官方仓库拉取跨境链路长、并发连接多、断点续传体验差一次全量拉取能耗掉大半天。SDK 设置代理要做的事很具体把下载请求交给一个可达、稳定的中转节点让列表刷得出来、大包下得完。刚搭环境的新手、要给 CI 机器批量配环境的人、以及给团队统一开发环境的老手最终都会走到这一步。2. SDK Manager 的代理面板从 Tools 菜单到四个字段的完整落点2.1 为什么代理必须设在 SDK Manager 内部很多人第一次配置会走错门在 IDE 的 Settings → Appearance Behavior → System Settings → HTTP Proxy 里填完插件市场确实通了切回 SDK Manager 一看该转圈还是转圈。原因是 SDK Manager 有自己独立的 HTTP 客户端和下载调度逻辑它并不复用 IDE 主进程的代理设置。IDE 层的代理影响的是插件仓库、许可证校验这类请求SDK 组件清单repository XML和各组件的归档包zip由 SDK Manager 自己发请求。这两条管道的配置是分开的只配一处另一处就会出现「插件能装、SDK 装不动」这种反直觉现象。再往下还有一层要分清SDK Manager 面板里配的代理作用域是当前这个 IDE 实例。换一个 IDE 大版本、新开一个 profile、或者干脆改用命令行工具sdkmanager这份 GUI 配置都不一定被继承。我见过有人在 GUI 里配得好好的结果 CI 机器上跑sdkmanager --install一路超时排查了半天才发现命令行压根没读那份配置。所以面板是入口不是终点后面第 3 章会补上命令行和构建脚本那两套参数。还有一个容易被忽略的点代理和镜像站不是同一回事。代理是把请求交给中转节点由它替你取回镜像站是直接指向另一套仓库地址。原文给的那台高校镜像mirrors.neusoft.edu.cn严格来说属于镜像站用法把它填进 Host 字段是因为 SDK Manager 的代理面板只接受 host port 这种形式本质上是把那台服务器当成了一个 HTTP 中转在用。理解这点很重要后面第 4 章会讲清楚为什么 Maven 依赖不能靠这个面板解决。2.2 打开面板的路径与实际界面元素操作路径本身不复杂但每一步都有版本差异写清楚一点能少走弯路打开 Android Studio停在欢迎页或任意已打开工程都可以顶部菜单栏找Tools。下拉菜单里选SDK Manager。旧版本这个入口在Configure齿轮菜单里找不到 Tools 项的话去右下角找齿轮。SDK Manager 窗口打开后注意顶部或左侧的标签页切到SDK Tools。这里和 SDK Platforms 是两套清单代理设置对两者都生效但从 Tools 页进入设置更顺。找窗口里的齿轮图标或Settings按钮。不同版本它的位置在右上角或右下角图标形态是一个小齿轮鼠标悬停会显示 SDK Manager Settings。弹出SDK Manager Settings窗口找到HTTP Proxy区块。这个区块里通常有三个单选No proxy、Auto-detect proxy settings、Manual proxy configuration。原文只提了后两个实际排错时第一个同样关键——你怀疑配置被污染、想验证直连能不能通时就是切回 No proxy 做一次对照实验。切换后要点Apply或OK保存SDK Manager 会在下一次刷新清单时使用新设置。界面上还有一行小字提示大意是「这些设置只影响 SDK Manager 自身的下载」。这句话值得认真读它就是 2.1 那套结论的官方确认。2.3 Host、Port、用户名密码四个字段怎么填填错字段是最高频的翻车点逐项拆开说字段该填什么常见取值填错的典型症状Host纯域名或 IP不带协议头、不带路径mirror.example.edu.cn这类机构镜像或内网代理地址填了http://xxx或带/路径点 OK 后报 URL 非法或下载直接 400Port与协议对应的端口号80HTTP、443HTTPS、内网代理常见8080/3128端口错填成 443 但镜像只开 80表现为连接被拒或 TLS 握手超时Username需要认证时才填内网代理的域账号不需要认证时乱填请求会返回 407Password同上—密码含特殊字符未转义认证失败Host 字段的坑要重点说。这个框只接受主机名你写https://mirror.example.edu.cn/sdk这种完整 URL 进去它不会帮你解析出主机部分只会原样拼进请求路径里结果就是一个语法正确但语义荒谬的地址。原资源里给的是mirrors.neusoft.edu.cn实际使用时把域名换成你自己网络环境下可达的那台镜像或代理主机即可方法论不变主机名进 Host端口进 Port协议靠端口号隐式表达。端口这一项的判断依据是镜像站对外暴露的服务。多数公共镜像同时开 80 和 443优先用 443因为 SDK 清单和包下载走 HTTPS 时链路更不容易被中间设备干扰。如果镜像只开了 80 而你填 443症状是连接超时而不是快速失败会误以为是网络慢。注意认证信息是明文存在 IDE 配置里的团队共用机器或把配置目录提交进版本库之前先确认里面没有账号密码。2.4 Auto-detect 与 Manual 的选择边界Auto-detect 的语义是读取系统级代理设置或 PAC 脚本。它适合两种场景一是公司统一配了系统代理PAC 自动分流你不想手动维护二是移动办公系统代理随网络环境自动切换。它的短板也很明显——PAC 的判定逻辑对 Java 进程不一定友好SDK Manager 拿到的可能是「直连」这个结论而实际上你需要走代理。表现就是系统浏览器能开网页SDK Manager 却一直转圈。Manual 是确定性最高的选项四五个字段填死不受系统设置漂移影响。工程实践里我一般直接选 Manual把 Host 和 Port 写死理由很简单环境问题最怕的就是「有时候能通有时候不能通」Manual 至少能把变量收敛到一个地方。真正需要自动化的场景CI、多环境切换交给第 3 章的命令行参数和环境变量而不是指望这个 GUI 单选。还有一个中间态先在 Manual 里填好镜像跑一次全量下载或一次--list如果失败切 Auto-detect 再试一次。两次结果对比能快速判断问题出在代理地址本身还是系统的代理策略上。2.5 保存之后怎么确认设置真的生效点完 OK 不代表生效得有一次可观察的验证。最省事的做法是回到 SDK Manager 主界面切到SDK Platforms勾选Show Package Details然后看列表能不能在十几秒内刷出带版本号的完整清单。清单文件本身很小如果连它都要等一两分钟说明请求没有走到你配的那个节点上。更可靠的是看日志。SDK Manager 窗口里有Show Log之类的入口或者去 IDE 的日志文件里搜Downloading、Connection、proxy这几个关键词能看到实际请求的目标地址。请求 URL 里的域名应该和你填的 Host 一致如果不一致说明配置没被读到或者被更高优先级的设置覆盖了第 3 章的优先级顺序会讲。还有一种情况设置生效了但缓存里存着上一次失败留下的半截文件导致重试仍然报错。这时候清掉本地缓存目录再试路径一般在用户目录下的.android/cache把它挪走而不是直接删方便回溯。3. 只点 GUI 不够gradle.properties 与命令行 sdkmanager 两套参数3.1 GUI 配置的三个漏配点GUI 面板只覆盖 SDK Manager 这一条下载通道剩下三条常见通道它都管不到第一条是Gradle 自身的依赖下载。项目 sync 时拉插件、拉依赖库走的是 Gradle 的 HTTP 客户端跟 SDK Manager 完全是两套东西。表现是 SDK 装得好好的一 sync 就卡在Downloading https://...不动。第二条是命令行sdkmanager。它在cmdline-tools/latest/bin/下是独立可执行程序不读 IDE 的配置。CI 机器上只有命令行工具没有 IDE所以必须用参数或环境变量单独配。第三条是avdmanager和模拟器镜像下载。镜像包动辄几个 GB走的通道和 SDK 组件下载接近但不完全等同GUI 里配的代理能覆盖一部分命令行场景下依然要单独处理。这三条通道各自的配置语法还不一样混用是最常见的错误来源。下面逐条给可抄的写法。3.2 gradle.properties 里的 systemProp 四行在项目根目录的gradle.properties或者用户目录下的~/.gradle/gradle.properties里追加# HTTP 通道代理很多镜像站的清单走 http systemProp.http.proxyHostmirror.example.edu.cn systemProp.http.proxyPort80 # HTTPS 通道代理端口单独写不要想当然复用上面那个 systemProp.https.proxyHostmirror.example.edu.cn systemProp.https.proxyPort443 # 需要认证时才有用不需要就整行删掉 systemProp.http.proxyUseryour_account systemProp.http.proxyPasswordyour_password # 内网地址不走代理分隔符是竖线不是逗号 systemProp.http.nonProxyHostslocalhost|127.0.0.1|*.internal.example逻辑说明systemProp.前缀是 Gradle 设 JVM 系统属性的约定等价于启动时加-Dhttp.proxyHost...。http 和 https 是两套独立属性这是 Java 网络栈的历史设计只配 http 那一对时所有 https 请求仍然直连症状就是「http 镜像能通、https 依赖拉不下来」。proxyUser/proxyPassword只在目标需要 Basic 认证时生效不需要认证时留着反而可能干扰。nonProxyHosts的分隔符必须是|写逗号不生效而且它不支持 CIDR 网段只认主机名和*.通配。公司内网有私有仓库时这一行不加的后果是私有仓库请求也被送去代理直接 404 或超时。放在用户级~/.gradle/gradle.properties而不是项目里的好处是不用担心误提交坏处是换机器要重新配一遍团队协作场景建议项目里放一份脱敏模板真实凭据走环境变量注入。3.3 命令行 sdkmanager 的 --proxy 参数命令行工具的代理参数是独立的一组写法如下# 先确认 sdkmanager 在 PATH 里或用绝对路径调用 # 常见位置$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager # 列出可安装包用代理走一次验证链路 sdkmanager --list \ --proxyhttp \ --proxy_hostmirror.example.edu.cn \ --proxy_port80 # 确认清单能拉到之后再装具体组件 sdkmanager --install platform-tools platforms;android-34 \ --proxyhttp \ --proxy_hostmirror.example.edu.cn \ --proxy_port80逻辑说明--proxyhttp指定代理协议类型--proxy_host和--proxy_port分别对应 GUI 里的 Host 和 Port三个参数必须同时给少一个会直接报参数错误而不是静默直连——这点比 GUI 友好。安装具体组件时包名要写全platforms;android-34这种带分号的写法在 shell 里要加引号否则分号会被 shell 解释成命令分隔符这是纯语法坑报错信息完全看不出原因。--list这一步不要跳过。它请求的清单文件很小能在几秒内返回就说明代理链路是通的返回慢或者超时问题在代理地址或端口而不是网络带宽。先小后大是排查下载类问题的基本节奏。3.4 环境变量兜底与优先级有些工具链不读gradle.properties也不吃命令行参数只认环境变量。通用写法# 注意这里必须带协议头和 gradle.properties 的写法完全不同 export HTTP_PROXYhttp://mirror.example.edu.cn:80 export HTTPS_PROXYhttp://mirror.example.edu.cn:443 export NO_PROXYlocalhost,127.0.0.1,.internal.example逻辑说明环境变量版本必须带http://前缀而gradle.properties里的proxyHost绝对不能带前缀。这两个规则正好相反是最高频的混淆点。NO_PROXY用逗号分隔也接受域名后缀形式和nonProxyHosts的竖线分隔不同。大小写方面多数工具同时认HTTP_PROXY和小写版本为兼容性建议大写。优先级大致是命令行显式参数 项目级gradle.properties 用户级gradle.properties 环境变量。真出问题时不要靠猜用第 3.5 节的验证手段直接看请求落到哪儿。3.5 三种验证手法从粗到细第一种用curl直接探镜像的清单地址确认主机和端口可达# -I 只取响应头快速判断连通性-m 设超时避免长时间挂着 curl -I -m 10 http://mirror.example.edu.cn/android/repository/repository2-3.xml返回 200 或 304 说明主机和端口没问题返回连接超时说明端口填错了返回 403/407 说明认证缺失。第二种跑sdkmanager --list并观察耗时。清单能出来但组件下载仍然停滞说明代理只覆盖了清单请求大包下载可能走了另一条通道回去检查gradle.properties和实际安装命令是否都带了参数。第三种Gradle 加--info跑一次 sync日志里搜Downloading和Resource missing看请求 URL 里的主机名。主机名不对说明配置没生效主机名对但状态码是 4xx说明代理侧的策略或路径有问题。4. 换镜像不只改代理把 google() 换成镜像仓库的三处写法4.1 代理和换源解决的不是同一件事代理是中转请求还是发往原地址只是绕了一个节点换源是改变目标地址请求直接打到另一套仓库。SDK 组件下载和 Maven 依赖下载是两条不同的管道前者靠 SDK Manager 的代理配置后者靠 Gradle 的仓库声明。很多人把这两件事混为一谈配完代理发现 sync 还是慢就是因为 Maven 仓库那一侧压根没动。判断依据很直接看卡住的那一行日志里的 URL。域名是dl.google.com、repo.maven.apache.org这类属于 Maven 依赖要换仓库域名是 SDK 清单或组件包属于 SDK Manager要走代理。两者可以同时配互不冲突。4.2 settings.gradle 里的 repository 声明顺序新版本 Gradle 把仓库声明收敛到了settings.gradle示例// settings.gradle dependencyResolutionManagement { // 禁止子模块自行声明仓库统一收口避免各处配置不一致 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { // 镜像放最前命中就返回命中不了才往下走 maven { url https://maven.example-cn.example/repository/public/ allowInsecureProtocol false } // 官方仓库兜底保证镜像缺包时项目还能构建 google() mavenCentral() } }逻辑说明仓库按声明顺序依次尝试命中即停所以镜像必须放在官方仓库前面否则等于没换。allowInsecureProtocol false是显式声明只用 HTTPS避免被降级到明文 HTTP如果你的内网镜像确实只有 HTTP才需要打开它同时要清楚这意味着凭据和内容在链路上是可见的。FAIL_ON_PROJECT_REPOS这一行的作用是让子模块里的repositories {}直接报错强制所有仓库声明集中在settings.gradle。多人协作项目里这条能省掉大量「我这能编你那不能编」的扯皮代价是老项目迁移时要清一遍子模块配置。Kotlin DSL 项目写法等价只是语法变成maven { url uri(...) }语义不变。4.3 三种镜像形态的取舍形态做法优点短板适用全量公共镜像一个地址代理全部公共仓库配置最简一行搞定冷门 artifact 可能缺同步有延迟个人项目、学习环境只镜像特定源只把 Google 系仓库指过去其余走官方缺包风险小职责清晰配置行数多要逐个对齐依赖 Google 系组件的中大型项目内网聚合仓库自建或团队维护一个聚合入口统一出网可控、可审计、可缓存需要人维护首次拉取仍慢团队协作、CI 环境选择逻辑按团队规模走一个人开发全量公共镜像够用三五个人的小团队聚合仓库的维护成本摊下来是划算的因为缓存命中率高了以后 CI 时间能明显下降再大的团队基本都会有内部的制品管理方案这时候settings.gradle里的地址就应该只指向内网公网仓库作为兜底甚至可以不写。4.4 换源后解析失败的三类报错第一类Could not resolve后面跟着Received status code 404。原因是镜像没有同步到那个 artifact或者路径拼错了。处理方式是临时把官方仓库提到前面验证一次能过就说明是镜像缺包把该 group 加进镜像的排除列表让它走官方。第二类Could not GET ... Received status code 407。这是代理认证错误通常发生在镜像本身又套了一层需要认证的代理或者gradle.properties里残留了失效的凭据。清掉proxyUser/proxyPassword两行再试。第三类校验和不匹配或Checksum failed。原因是镜像返回的内容和官方校验值对不上可能是同步中断留下了损坏文件也可能是中间设备改写了响应。这类问题不要试图绕过校验换一个镜像源或等同步完成。5. 排查清单五条踩坑记录与逐条定位手法5.1 现象清单能刷出来大包下载始终 0 KB/s原因清单文件是几百 KB 的 XML走的是轻量请求组件包是几百 MB 到几 GB 的归档走的是分块下载。很多镜像站对清单做了完整缓存对归档包却是回源转发回源链路一旦拥塞表现就是清单秒开、包不动。另一个可能是并发数被限SDK Manager 默认会开多个连接镜像侧限流后全部挂起。解决先换一个时间点重试排除源站高峰期。持续不动的话把大包拆成单个组件装别一次勾十几个——sdkmanager --install platform-tools单独跑一次能通说明是并发或总量问题而非链路不通。仍然不行就换镜像或者直接走离线包方案第 6 章。5.2 现象Host 填完点 OK 直接弹红字提示 URL 非法原因Host 字段只接受主机名填进去的内容如果带了http://、https://、结尾斜杠或者路径校验就过不去。另一个隐蔽原因是复制粘贴时带进了不可见字符比如从文档里拷过来的全角冒号或尾部空格。解决把 Host 清空重打一遍只留xxx.yyy.zzz这种纯主机名形态端口单独填在 Port。粘贴来源不可靠时先粘到纯文本编辑器里过一遍再手工敲进输入框。5.3 现象Gradle sync 报 407但 SDK Manager 一切正常原因SDK Manager 的 GUI 配置不作用于 Gradle。Gradle 走的是gradle.properties里的systemProp或环境变量这两处如果还留着旧的、需要认证的代理地址就会返回 407。也可能是认证凭据里有特殊字符没转义比如密码里的或:。解决检查项目根目录和用户目录下两份gradle.properties把proxyUser/proxyPassword两行注释掉跑一次 sync 看报错是否变成 401 或直接超时。变成超时就说明是认证问题回去确认凭据仍是 407 说明代理侧策略要求认证而你没给。凭据含特殊字符时优先改用环境变量注入而不是写进 properties 文件。5.4 现象改回直连、删掉配置请求仍然走代理原因配置有多个落点——GUI 面板、项目gradle.properties、用户级gradle.properties、shell 环境变量、IDE 启动脚本里的 JVM 参数。你删了其中一个其余还在生效。环境变量尤其隐蔽因为它写在~/.bashrc/~/.zshrc里新开的终端全都带着。解决按优先级从高到低逐层排查。先在当前 shell 里env | grep -i proxy看有没有残留有就unset掉再试再检查两份gradle.properties最后回 GUI 面板切到No proxy保存。三层都清干净后重开 IDE配置文件是在启动时读的热改不一定立刻生效。5.5 现象能 ping 通镜像主机443 端口却连不上原因ICMP 可达不代表 TCP 可达。镜像站可能只对特定来源开放端口或者只监听 80 不监听 443也可能是中间网络设备对 TLS 握手做了限制。还有一种可能是本地防火墙对 Java 进程单独放行规则缺失浏览器能连、JVM 连不上。解决用curl -I -m 10分别测 80 和 443 两个端口的实际响应别用 ping 下结论。80 通 443 不通就把 Port 改成 80 再试两个都不通检查本地出站规则和镜像站的访问说明。TLS 握手阶段超时且 http 正常时说明问题在加密通道而不是网络可达性。6. 把代理配置固化下来离线包与模板化的收尾手法配置这件事最怕的是「每次换机器重来一遍」。做到第 5 章那些排查本质上都是在为一次没配好买单。真正省时间的做法是把不确定性提前消掉我一般走两条路。第一条是离线包。SDK Manager 支持导出和导入本地仓库结构思路是把已经下好的组件目录整体打包换机器时解压到ANDROID_HOME对应位置让 SDK Manager 认为这些组件已安装。要点是目录层级必须和官方仓库一致platforms/、build-tools/、platform-tools/各归各位package.xml这类元数据文件不能丢丢了就会出现「文件在但列表里显示未安装」。适合团队统一环境、CI 机器预热、以及网络条件确实很差的场景。代价是包体大、更新不及时所以我一般只在固定版本的构建机上用开发机还是走代理在线拉。第二条是配置模板化。把gradle.properties里那几行做成带占位符的模板真实的主机和凭据从环境变量读# gradle.properties 模板提交进版本库 systemProp.http.proxyHost${SDK_PROXY_HOST} systemProp.http.proxyPort${SDK_PROXY_PORT} systemProp.https.proxyHost${SDK_PROXY_HOST} systemProp.https.proxyPort${SDK_PROXY_PORT}这个写法有个前提Gradle 读gradle.properties时不做环境变量展开占位符得靠 CI 的模板渲染步骤或者启动脚本替换成实际值。所以我更常用的是反过来——文件里不写代理完全靠GRADLE_OPTS注入# CI 启动脚本里注入凭据从密钥管理系统读不落盘 export GRADLE_OPTS-Dhttp.proxyHost${SDK_PROXY_HOST} -Dhttp.proxyPort${SDK_PROXY_PORT} \ -Dhttps.proxyHost${SDK_PROXY_HOST} -Dhttps.proxyPort${SDK_PROXY_PORT}这样仓库里的配置文件是干净的谁也不需要为了跑一次构建去问别人要账号密码。验证是否注入成功跑一次./gradlew --version输出末尾会打印 JVM 参数能看到-D开头的几项就说明生效了。这个检查我加进了所有 CI 流水线的第一步比事后从构建日志里翻下载超时便宜得多。有个细节值得单独提端口号一定不要在两处写不同值。我吃过一次亏gradle.properties里 http 写 80、https 写 8080本地跑得好好的换到 CI 上所有 https 依赖全部超时日志里只有一句Connection timed out看不出任何线索。从那以后我每次改代理配置都强制走一遍「curl -I探两个端口 →sdkmanager --list探清单 →gradlew --version看 JVM 参数」这个三步验证再动项目代码。希望帮到你。本文还有配套的精品资源点击获取
