简介围绕Android开发中SDK下载缓慢、连接不稳定的常见问题这份文档面向需要配置Android Studio开发环境、尤其是初次使用SDK Manager的开发者提供代理设置的参考材料。内容涉及镜像源选择、自动检测与手动代理两种模式以及Host、Port和身份验证等关键参数适合作为环境搭建阶段的速查笔记也可用于理解Gradle插件等依赖下载的代理思路。资源包仅含1个docx文件大小约102KB篇幅紧凑便于随开发环境归档或按需查阅。文档以步骤化说明配合参数提示帮助读者减少因网络问题反复试错的时间并在镜像失效或网络条件变化时快速调整配置方案提升组件获取的稳定性。目前已有862人学习说明该主题在Android开发环境配置中具有较普遍的参考需求。对于希望改善SDK及相关依赖下载效率的开发者这份材料可作为配置思路与参数填写的辅助参考。1. 下载进度卡在 0% 的那二十分钟SDK 设置代理到底改了哪一层某开发者在一台新笔记本上装 Android 开发环境SDK Manager 里勾了 Platform-Tools、Build-Tools 和两个 API Level点了 Apply进度条在 0% 停了二十分钟最后超时。他以为把 SDK 设置代理这件事填个 Host 就完事结果真正卡住的不是网络而是“填在哪一层”。SDK 这条链路上其实有三个各自独立的下载通道SDK Manager 自己的 GUI 下载、命令行 sdkmanager、以及 Gradle 拉依赖。前两个走 IDE 或命令行里的 HTTP 代理配置第三个完全不认 IDE 的设置只认gradle.properties或者 JVM 启动参数。三者配错任何一个出现的现象都长得很像——组件列表刷得出来下载就是不动。这篇记录写的就是把这三层一次对齐的过程适合需要在一台干净机器上从零拉齐 SDK 的人尤其是出口受限、只能走镜像站的办公网和实验室网络。2. 装之前先对齐环境JDK 17、SDK 路径与 SDK Manager 的三个入口先把版本和路径定下来比装到一半再返工省事得多。SDK Manager 本身不挑 JDK但它下载下来的构建工具、以及后面调它的 Gradle对 JDK 版本是有要求的。近几年的 Android Gradle 插件基本都以 JDK 17 为基线机器上同时躺着一堆 JDK 8、JDK 11 的项目文件夹时JAVA_HOME指向哪个直接决定你后面./gradlew跑起来是正常还是直接报一串看不懂的字节码版本错误。2.1 版本对照JDK 17 打底别自己造版本组合我一般按下面这张表取不做花活组件取法说明JDK17IDE 自带的运行时也是这一档命令行单独装也建议跟它一致Android Studio近两年任一正式版界面文字略有差异菜单路径基本没变Gradle跟工程gradle/wrapper走不单独装避免和工程对不上cmdline-tools随 SDK Manager 安装提供命令行sdkmanagerPlatform-Tools / Build-Tools由 SDK Manager 拉取版本跟着工程编译要求走表里最容易被忽略的是 Gradle 那一行。很多人看到 IDE 提示“Gradle 版本过低”就去官网下一个最新版解压然后PATH一改结果 IDE 用的还是 wrapper 里的旧版命令行用的却是新版两边行为对不上排查起来像在猜。常见做法是只认工程目录下的gradlew和gradlew.bat全局 Gradle 能不开就不开。先确认一遍 JDK 现状别嫌这一步啰嗦# 看当前 shell 认到的是哪个 JDK echo $JAVA_HOME # Windows CMD 用 echo %JAVA_HOME% java -version # 输出里应含 17不要出现 1.8 # 装了多个 JDK 时把 17 指过去路径按自己机器改 export JAVA_HOME/usr/lib/jvm/jdk-17 export PATH$JAVA_HOME/bin:$PATH逻辑很简单JAVA_HOME决定绝大多数构建工具用哪个 JDKPATH只是让java命令能找到它。两条都要设只设PATH不设JAVA_HOME时Gradle 有可能去翻别的目录。参数上唯一要留意的是export只在当前终端有效写进~/.zshrc或~/.bashrc才算落地Windows 下这类变量建议走系统环境变量面板不要靠临时set。SDK 的安装目录也在这里一次性定死。我的习惯是放在用户主目录下的纯英文路径比如~/Android/Sdk而不是C:\Program Files\...或者带中文的文件夹。原因在后面 4.3 会细说简单讲就是解压、写权限、以及某些工具对非 ASCII 路径的处理这三件事任意一个出问题症状都是“装到一半失败”而且报错信息往往指不到真正原因。2.2 三个入口对应三份配置别指望配一个全通把入口认清楚后面填参数才不至于填错地方。SDK 相关的下载入口一共三个第一个是 IDE 里的图形入口。打开 Android Studio顶部菜单 Tools 里找到 SDK Manager窗口打开后切到 SDK Tools 标签页右上角有一个齿轮图标点开就是 SDK Manager Settings代理选项都在里面。这条通道负责 GUI 里勾选的那些组件下载。第二个是命令行入口。cmdline-tools解压之后bin目录下会有sdkmanager它有自己的--proxy系列参数跟 IDE 里填的那份是两套东西互不读取。第三个是 Gradle 入口。严格说它不是 SDK Manager但编译时缺组件AGP 会自己去仓库拉这条通道走的是仓库地址而不是 SDK 镜像配置写在gradle.properties或者工程里的仓库声明。三份配置落在不同位置这是很多人配完“看起来生效了但又没完全生效”的根源。大致对应关系如下入口配置写在哪影响范围IDE 图形入口IDE 配置目录下的proxy.settings.xml只影响 IDE 内触发的下载命令行 sdkmanager命令行参数或环境变量只影响该次命令Gradlegradle.properties的systemProp.*影响依赖解析与下载先确认命令行工具到底能不能用后面所有验证都依赖它# 确认 cmdline-tools 已解压并加入 PATH which sdkmanager # Windows 用 where sdkmanager sdkmanager --version # 能打印出版本号说明可用 # 打印时如果报 JAVA_HOME is not set回到 2.1 先把 JDK 定了这段没什么参数可调纯粹是探活。--version能出版本号说明 JDK 找到了、脚本权限也对如果报权限拒绝那是bin/sdkmanager少了可执行位chmod x补一下就行。Windows 上则是sdkmanager.bat的问题通常是PATH里带空格导致解析截断。3. 手动填 HTTP ProxyHost、Port 与镜像地址的六个字段真正落到填写的环节先说结论绝大多数卡住的人需要的都是 Manual proxy configuration而不是 Auto-detect。自动检测读的是系统级代理设置只在机器上确实配了系统代理、并且那个代理支持 PAC 规则时才有意义。如果你的网络是直连但跨境出口很慢自动检测的结果就是“什么都没检测到”然后你会在原地等一个永远不会变快的进度条。3.1 Auto-detect 什么时候管用什么时候纯属浪费时间判断方法很朴素去看操作系统的网络设置里有没有配代理。配了且那个代理允许被应用读取Auto-detect 就能用没配或者配的是只对浏览器生效的那类设置自动检测基本等于没开。我踩过一次坑某台办公机系统代理是开着的Auto-detect 也确实读到了组件列表刷得飞快但下载到一半断掉。原因是那个系统代理对长连接有时限SDK 的大包一断就得重来。后来改成 Manual指向园区自建的镜像站同一条网线速度立刻不一样。所以自动检测“能用”和“好用”是两件事凡是下载大包我一般直接上 Manual。Manual 模式下的字段一共就那几个但每个都有讲究。下面这张表是我自己的填法字段填什么常见错法Host镜像站域名写成mirrors.example.edu.cn这种纯域名把http://或结尾斜杠一起粘进去Port先填 80不通再试 443默认填 8080那是本地代理的习惯端口Username镜像站需要认证时才填把账号密码拼进 HostPassword同上注意特殊字符密码含、#时没做转义No proxy for本机地址和内部域名什么都不填导致本机服务也绕出去表里的域名是文档占位写法实际要换成你能访问到的那个镜像地址。这一点必须说清楚镜像站的可用性跟网络位置强相关同一个地址在办公网能通回家可能就不通所以配置属于“随环境走”的东西不是一次配好永久有效。3.2 字段逐个填以及命令行通道的等效写法图形界面按这个顺序走Tools → SDK Manager → SDK Tools 标签页 → 右上角齿轮 → SDK Manager Settings → 选 Manual proxy configuration → 填 Host 和 Port → Apply。这一步没什么技术含量重点在于填完之后 GUI 只解决了一半问题。命令行通道要单独配一遍否则你在终端里敲sdkmanager依然是直连。等效写法是这样# 命令行方式拉取组件列表代理参数直接跟在命令后面 sdkmanager --list \ --proxyhttp \ --proxy_hostmirrors.example.edu.cn \ --proxy_port80 # 需要认证的镜像站再加两个参数 sdkmanager --list \ --proxyhttp \ --proxy_hostmirrors.example.edu.cn \ --proxy_port80 \ --proxy_useryour_account \ --proxy_passyour_password--proxyhttp表示走 HTTP 代理协议不是 HTTPS这一项写错会直接连不上。--proxy_host只要域名不要协议头也不要路径。--proxy_port跟图形界面填的保持一致两边不一致时会出现“IDE 能下、命令行不能下”的诡异局面。后面两个认证参数只在镜像站明确要求账号时才加多数园区镜像站是免认证的。顺带提一句端口的选择逻辑。镜像站的 SDK 仓库大多挂在 80 端口走 HTTP443 一般是给网页或者另一套服务用的。所以先试 80报连接被拒或者超时再换 443如果 443 报的是 SSL 握手失败那基本可以判断这个地址在 443 上不是同一个服务换回 80 或者换一个镜像地址别在协议上死磕。还有一个容易被忽略的字段No proxy for。本机回环地址和内部域名应该排除在外否则 IDE 连本地的一些服务也会被绕到代理上表现是一些莫名其妙的功能超时。填法就是逗号或竖线分隔的一串localhost,127.0.0.1,*.internal.example这种形式具体分隔符看输入框提示。3.3 保存之后怎么确认真的生效点了 Apply 不代表生效了得看配置文件有没有真的写下去。IDE 的代理设置会落到它自己的配置目录里文件名通常是proxy.settings.xml。找它的命令# macOS / Linux在配置目录里找代理配置文件 find ~/.config -name proxy.settings.xml 2/dev/null find ~/Library/Application\ Support -name proxy.settings.xml 2/dev/null # 找到后看一眼内容确认 host 和 port 与界面一致 cat 上一步输出的路径路径里会有一段厂商目录不同安装方式命名不一样所以用find通配比硬记路径靠谱。文件里能看到PROXY_TYPE_MANUAL、proxyHost、proxyPort这几个字段值跟你填的一致就说明写进去了。如果文件不存在或者还是PROXY_TYPE_NONE那就是 Apply 没点到或者点到了但 IDE 没有写权限。Windows 下对应的是%APPDATA%目录同样用资源管理器搜文件名最快。这一步的价值在于排错时能分清楚“是配置没写进去”还是“写进去了但不生效”这两类问题的处理方向完全不同混在一起查会浪费大量时间。4. 配套改三处才算配完Gradle、仓库镜像与 SDK 目录权限SDK Manager 的代理只保证 GUI 里的组件能下下来。一个工程能不能跑起来还差 Gradle 那一层。很多人 SDK 装完了、新建空工程结果 Sync 卡在 “Downloading” 上一动不动就是这一层没配。区别很好认SDK Manager 里下的是平台和构建工具Gradle 下的是依赖库两者域名往往都不是同一个。4.1 gradle.properties 里的代理四件套Gradle 不读 IDE 的代理配置它有自己的一套写法是通过 JVM 系统属性透传# 放在 ~/.gradle/gradle.properties全局或工程根目录 gradle.properties单工程 systemProp.http.proxyHostmirrors.example.edu.cn systemProp.http.proxyPort80 systemProp.https.proxyHostmirrors.example.edu.cn systemProp.https.proxyPort80 # 本机和内部域名不走代理用竖线分隔 systemProp.http.nonProxyHostslocalhost|127.0.0.1|*.internal.example四行必须成对出现只写 http 不写 https结果就是一部分依赖能下、另一部分一直重试。nonProxyHosts用竖线分隔这一点跟命令行环境变量用逗号不一样混用会导致规则不生效而且不报错属于典型的“配了但没起作用”。放全局还是放工程里取舍在于全局配置简单但换网络时容易忘掉后面会变成 502 的来源放工程里跟随代码走但要注意别把带账号密码的行提交进仓库。我的习惯是全局放域名和端口账号密码这类敏感项一律走环境变量或者干脆依赖免认证的镜像。如果不想改文件也可以临时用环境变量顶一下# 仅当前终端有效适合临时验证 export http_proxyhttp://mirrors.example.edu.cn:80 export https_proxyhttp://mirrors.example.edu.cn:80 export no_proxylocalhost,127.0.0.1注意环境变量的值是带协议头的完整地址跟gradle.properties里拆成 host 和 port 两行的写法不同这两种格式互相粘贴会直接报错。验证完记得unset不然下次开会话还在。4.2 仓库镜像不等于 SDK 镜像这一条值得单独拎出来说。SDK Manager 里的代理指向的是 SDK 仓库镜像Gradle 依赖走的是 Maven 仓库两者是不同的服务地址也往往不同。配好前者不代表后者通了反过来也一样。工程里的仓库声明一般长这样把镜像地址加在最前面// settings.gradle.kts dependencyResolutionManagement { repositories { maven { // 镜像仓库地址换成你自己能访问的那个 url uri(https://maven.example-mirror.cn/repository/public/) isAllowInsecureProtocol false } // 原有的官方仓库声明保持不动作为兜底 } }逻辑是就近优先请求先打到镜像镜像没有的再回落到官方源。isAllowInsecureProtocol保持false只有镜像地址确实是 http 时才需要放开放开意味着这段流量不加密能不放开就不放开。这段配置生效之后./gradlew拉依赖的速度会有明显变化。判断有没有真的走镜像加--info看日志里的下载地址就行日志里出现的是镜像域名而不是官方域名说明配置吃到了。这一步比看进度条靠谱得多进度条只告诉你快慢日志告诉你走的是哪条路。4.3 SDK 目录写入权限与非 ASCII 路径最后一项是最不技术、但翻车率最高的一项SDK 装在哪。两个硬性要求。第一路径必须当前用户可写。装在C:\Program Files或者系统级目录下SDK Manager 解压时会因为没有写权限失败报错信息通常是解压异常而不是权限拒绝容易带偏方向。第二路径不要带中文和空格。部分构建工具在拼接路径时不做过多的转义处理带空格的路径被截断之后报错会指向一个根本不存在的文件。检查权限的命令很简单# 确认 SDK 目录归属当前用户 ls -ld $ANDROID_HOME # 归属不对就改回来谨慎使用确认路径无误再执行 sudo chown -R $(whoami) $ANDROID_HOME$ANDROID_HOME指向 SDK 根目录新版工具里也有用ANDROID_SDK_ROOT的两个都设上不冲突但没必要认准一个即可。chown -R会递归改掉目录下所有文件的归属执行前把路径 echo 出来核对一遍改错目录的后果比权限问题严重得多。目录定好之后把这个路径同时写进 IDE 的 SDK Location 和命令行环境变量两边指同一个位置。见过不止一次“IDE 里能看到 SDK命令行sdkmanager --list却是空的”就是因为两处指向了不同目录各自装各自的最后磁盘上躺着两份 SDK。5. 避坑与排查代理配完还是 0% 的五条血泪记录下面这五条都是实际撞过的按现象、原因、解决三段写。顺序大致按出现频率排前面几条覆盖了大部分情况。5.1 五个现象对照第一条现象是组件列表能刷出来但下载进度条纹丝不动。原因通常是列表请求走了代理实际下载走了另一条通道最常见的是 GUI 配了、命令行没配或者反过来。解决办法是回到第 3 章把 GUI 和命令行两条通道分别用sdkmanager --list和界面里勾一个小体积组件各测一次哪条不通补哪条别一起改。第二条现象是填了 443 端口之后报 SSL 握手失败。原因是这个镜像地址的 443 端口跑的不是 SDK 仓库服务协议对不上。解决办法是换回 80 重试仍然不通就换一个镜像地址不要在端口上反复试错试到第十次也不会通。第三条现象是 SDK 装完了新建工程 Sync 失败报Could not resolve一类。原因是 Gradle 完全不吃 IDE 的代理设置它只认gradle.properties或者环境变量。解决就是 4.1 那四行补齐 https 那一对同时确认nonProxyHosts用的是竖线分隔。第四条现象是换个网络环境之后所有请求报 502或者一直转圈。原因是旧的代理配置还留着而那个镜像地址在新网络下不可达。解决办法是把 IDE 里切回 No proxy同时把gradle.properties里那几行注释掉两边一起切只切一边会得到更奇怪的现象。第五条现象是代理认证一直返回 407。原因是账号或密码里带了特殊字符被 URL 解析吃掉了或者是把账号密码拼进了 Host 字段。解决办法是老老实实用Username和Password两个独立字段不要搞拼接密码里有、#、:这类字符时优先怀疑是它们。这五条里前三条占了绝大多数。排查顺序建议固定下来先确认命令行通道通不通再确认 Gradle 通道通不通最后才去看 IDE 界面因为命令行输出的错误信息最完整界面上的提示往往只有一句“下载失败”信息量约等于零。提示排查时把 IDE 的日志窗口打开日志里的实际请求地址会明确告诉你走的是哪条通道、打到哪个域名。这比盯着进度条猜效率高得多。5.2 换镜像之前先做回滚别把后悔药弄丢代理配置有个特点改动很小但散落在三四个地方改的时候记得住过两周就忘干净了。所以换镜像地址之前先把现状备份一份这是最便宜的一份后悔药。# 备份 Gradle 全局配置 cp ~/.gradle/gradle.properties ~/.gradle/gradle.properties.bak.$(date %Y%m%d) # 备份 IDE 的代理配置路径用 3.3 里 find 出来的结果 find ~/.config -name proxy.settings.xml -exec cp {} {}.bak \; # 顺手记一下当前环境变量方便对照 env | grep -i proxy ~/proxy-env-$(date %Y%m%d).txt备份完之后再动手改。回滚的动作就是把.bak文件覆盖回去、把环境变量unset、IDE 里切回 No proxy三步走完再重启 IDE。别小看重启这一步IDE 的代理设置有一部分是启动时读进内存的不重启的话界面显示已经改了实际请求还在用旧的。还有一个习惯值得养成把当前这套配置写进一个自己的 setup 记录里哪怕只是几行文本记清楚镜像地址、端口、有没有认证、对应的网络环境。换机器的时候照着抄一遍比凭记忆重配快得多也不容易漏掉 Gradle 那四行。6. 验证跑通从空工程到第一个 APK 的三个检查点配置写完不等于通了。我一般用三个检查点串起来验每一个都对应一条独立通道任意一个不过就说明那一层还有问题不用往下走。第一关是命令行通道。执行sdkmanager --list | head -n 20能在一两分钟内刷出组件列表说明 JDK、PATH、代理参数三样都对。如果刷不出来先看报错是连接超时还是认证失败前者查 Host 和 Port后者查账号字段。第二关是 Gradle 通道。随便新建一个空工程或者用现成工程跑./gradlew :app:dependencies --configuration debugRuntimeClasspath --info在输出里找下载地址确认域名是镜像而不是官方源。这一关的价值在于把“依赖能不能拉到”和“代码能不能编译”分开验证出了问题定位范围小很多。第三关是产物。跑./gradlew :app:assembleDebug然后看app/build/outputs/apk/debug/目录下有没有生成 apk。这一关过完说明 SDK、构建工具、依赖三样都齐了。检查点通过标准不通过先查命令行通道sdkmanager --list正常出列表JDK、PATH、--proxy_*参数Gradle 通道日志里的下载域名是镜像地址gradle.properties的四行与仓库声明构建产物生成 debug apk 文件Build-Tools 版本、SDK 目录权限三关里最容易出问题的是第二关因为它的配置和第一关完全独立很多人验完第一关就以为大功告成。实际经验是第一关过了第二关卡住的比例相当高而卡住之后的报错又特别像“网络问题”一不留神就往代理上找原因其实只是少写了systemProp.https.*那两行。最后提一个技巧把这三个检查点写成一个小脚本放在工程根目录换机器时一条命令跑完输出里哪一关红了就补哪一关。脚本内容不用复杂三段命令加几个 echo 就够。这东西看着粗糙但它能把你从“感觉配好了”拉到“确认配好了”。从那以后我每换一台机器都先做一次完整的备份再按这三关走一遍确认全部通过才动手写第一行业务代码。吃过一次 SDK 半装不装、工程报错指向莫名其妙文件的亏就再也不想靠猜了。希望帮到你。本文还有配套的精品资源点击获取
简介围绕Android开发中SDK下载缓慢、连接不稳定的常见问题这份文档面向需要配置Android Studio开发环境、尤其是初次使用SDK Manager的开发者提供代理设置的参考材料。内容涉及镜像源选择、自动检测与手动代理两种模式以及Host、Port和身份验证等关键参数适合作为环境搭建阶段的速查笔记也可用于理解Gradle插件等依赖下载的代理思路。资源包仅含1个docx文件大小约102KB篇幅紧凑便于随开发环境归档或按需查阅。文档以步骤化说明配合参数提示帮助读者减少因网络问题反复试错的时间并在镜像失效或网络条件变化时快速调整配置方案提升组件获取的稳定性。目前已有862人学习说明该主题在Android开发环境配置中具有较普遍的参考需求。对于希望改善SDK及相关依赖下载效率的开发者这份材料可作为配置思路与参数填写的辅助参考。1. 下载进度卡在 0% 的那二十分钟SDK 设置代理到底改了哪一层某开发者在一台新笔记本上装 Android 开发环境SDK Manager 里勾了 Platform-Tools、Build-Tools 和两个 API Level点了 Apply进度条在 0% 停了二十分钟最后超时。他以为把 SDK 设置代理这件事填个 Host 就完事结果真正卡住的不是网络而是“填在哪一层”。SDK 这条链路上其实有三个各自独立的下载通道SDK Manager 自己的 GUI 下载、命令行 sdkmanager、以及 Gradle 拉依赖。前两个走 IDE 或命令行里的 HTTP 代理配置第三个完全不认 IDE 的设置只认gradle.properties或者 JVM 启动参数。三者配错任何一个出现的现象都长得很像——组件列表刷得出来下载就是不动。这篇记录写的就是把这三层一次对齐的过程适合需要在一台干净机器上从零拉齐 SDK 的人尤其是出口受限、只能走镜像站的办公网和实验室网络。2. 装之前先对齐环境JDK 17、SDK 路径与 SDK Manager 的三个入口先把版本和路径定下来比装到一半再返工省事得多。SDK Manager 本身不挑 JDK但它下载下来的构建工具、以及后面调它的 Gradle对 JDK 版本是有要求的。近几年的 Android Gradle 插件基本都以 JDK 17 为基线机器上同时躺着一堆 JDK 8、JDK 11 的项目文件夹时JAVA_HOME指向哪个直接决定你后面./gradlew跑起来是正常还是直接报一串看不懂的字节码版本错误。2.1 版本对照JDK 17 打底别自己造版本组合我一般按下面这张表取不做花活组件取法说明JDK17IDE 自带的运行时也是这一档命令行单独装也建议跟它一致Android Studio近两年任一正式版界面文字略有差异菜单路径基本没变Gradle跟工程gradle/wrapper走不单独装避免和工程对不上cmdline-tools随 SDK Manager 安装提供命令行sdkmanagerPlatform-Tools / Build-Tools由 SDK Manager 拉取版本跟着工程编译要求走表里最容易被忽略的是 Gradle 那一行。很多人看到 IDE 提示“Gradle 版本过低”就去官网下一个最新版解压然后PATH一改结果 IDE 用的还是 wrapper 里的旧版命令行用的却是新版两边行为对不上排查起来像在猜。常见做法是只认工程目录下的gradlew和gradlew.bat全局 Gradle 能不开就不开。先确认一遍 JDK 现状别嫌这一步啰嗦# 看当前 shell 认到的是哪个 JDK echo $JAVA_HOME # Windows CMD 用 echo %JAVA_HOME% java -version # 输出里应含 17不要出现 1.8 # 装了多个 JDK 时把 17 指过去路径按自己机器改 export JAVA_HOME/usr/lib/jvm/jdk-17 export PATH$JAVA_HOME/bin:$PATH逻辑很简单JAVA_HOME决定绝大多数构建工具用哪个 JDKPATH只是让java命令能找到它。两条都要设只设PATH不设JAVA_HOME时Gradle 有可能去翻别的目录。参数上唯一要留意的是export只在当前终端有效写进~/.zshrc或~/.bashrc才算落地Windows 下这类变量建议走系统环境变量面板不要靠临时set。SDK 的安装目录也在这里一次性定死。我的习惯是放在用户主目录下的纯英文路径比如~/Android/Sdk而不是C:\Program Files\...或者带中文的文件夹。原因在后面 4.3 会细说简单讲就是解压、写权限、以及某些工具对非 ASCII 路径的处理这三件事任意一个出问题症状都是“装到一半失败”而且报错信息往往指不到真正原因。2.2 三个入口对应三份配置别指望配一个全通把入口认清楚后面填参数才不至于填错地方。SDK 相关的下载入口一共三个第一个是 IDE 里的图形入口。打开 Android Studio顶部菜单 Tools 里找到 SDK Manager窗口打开后切到 SDK Tools 标签页右上角有一个齿轮图标点开就是 SDK Manager Settings代理选项都在里面。这条通道负责 GUI 里勾选的那些组件下载。第二个是命令行入口。cmdline-tools解压之后bin目录下会有sdkmanager它有自己的--proxy系列参数跟 IDE 里填的那份是两套东西互不读取。第三个是 Gradle 入口。严格说它不是 SDK Manager但编译时缺组件AGP 会自己去仓库拉这条通道走的是仓库地址而不是 SDK 镜像配置写在gradle.properties或者工程里的仓库声明。三份配置落在不同位置这是很多人配完“看起来生效了但又没完全生效”的根源。大致对应关系如下入口配置写在哪影响范围IDE 图形入口IDE 配置目录下的proxy.settings.xml只影响 IDE 内触发的下载命令行 sdkmanager命令行参数或环境变量只影响该次命令Gradlegradle.properties的systemProp.*影响依赖解析与下载先确认命令行工具到底能不能用后面所有验证都依赖它# 确认 cmdline-tools 已解压并加入 PATH which sdkmanager # Windows 用 where sdkmanager sdkmanager --version # 能打印出版本号说明可用 # 打印时如果报 JAVA_HOME is not set回到 2.1 先把 JDK 定了这段没什么参数可调纯粹是探活。--version能出版本号说明 JDK 找到了、脚本权限也对如果报权限拒绝那是bin/sdkmanager少了可执行位chmod x补一下就行。Windows 上则是sdkmanager.bat的问题通常是PATH里带空格导致解析截断。3. 手动填 HTTP ProxyHost、Port 与镜像地址的六个字段真正落到填写的环节先说结论绝大多数卡住的人需要的都是 Manual proxy configuration而不是 Auto-detect。自动检测读的是系统级代理设置只在机器上确实配了系统代理、并且那个代理支持 PAC 规则时才有意义。如果你的网络是直连但跨境出口很慢自动检测的结果就是“什么都没检测到”然后你会在原地等一个永远不会变快的进度条。3.1 Auto-detect 什么时候管用什么时候纯属浪费时间判断方法很朴素去看操作系统的网络设置里有没有配代理。配了且那个代理允许被应用读取Auto-detect 就能用没配或者配的是只对浏览器生效的那类设置自动检测基本等于没开。我踩过一次坑某台办公机系统代理是开着的Auto-detect 也确实读到了组件列表刷得飞快但下载到一半断掉。原因是那个系统代理对长连接有时限SDK 的大包一断就得重来。后来改成 Manual指向园区自建的镜像站同一条网线速度立刻不一样。所以自动检测“能用”和“好用”是两件事凡是下载大包我一般直接上 Manual。Manual 模式下的字段一共就那几个但每个都有讲究。下面这张表是我自己的填法字段填什么常见错法Host镜像站域名写成mirrors.example.edu.cn这种纯域名把http://或结尾斜杠一起粘进去Port先填 80不通再试 443默认填 8080那是本地代理的习惯端口Username镜像站需要认证时才填把账号密码拼进 HostPassword同上注意特殊字符密码含、#时没做转义No proxy for本机地址和内部域名什么都不填导致本机服务也绕出去表里的域名是文档占位写法实际要换成你能访问到的那个镜像地址。这一点必须说清楚镜像站的可用性跟网络位置强相关同一个地址在办公网能通回家可能就不通所以配置属于“随环境走”的东西不是一次配好永久有效。3.2 字段逐个填以及命令行通道的等效写法图形界面按这个顺序走Tools → SDK Manager → SDK Tools 标签页 → 右上角齿轮 → SDK Manager Settings → 选 Manual proxy configuration → 填 Host 和 Port → Apply。这一步没什么技术含量重点在于填完之后 GUI 只解决了一半问题。命令行通道要单独配一遍否则你在终端里敲sdkmanager依然是直连。等效写法是这样# 命令行方式拉取组件列表代理参数直接跟在命令后面 sdkmanager --list \ --proxyhttp \ --proxy_hostmirrors.example.edu.cn \ --proxy_port80 # 需要认证的镜像站再加两个参数 sdkmanager --list \ --proxyhttp \ --proxy_hostmirrors.example.edu.cn \ --proxy_port80 \ --proxy_useryour_account \ --proxy_passyour_password--proxyhttp表示走 HTTP 代理协议不是 HTTPS这一项写错会直接连不上。--proxy_host只要域名不要协议头也不要路径。--proxy_port跟图形界面填的保持一致两边不一致时会出现“IDE 能下、命令行不能下”的诡异局面。后面两个认证参数只在镜像站明确要求账号时才加多数园区镜像站是免认证的。顺带提一句端口的选择逻辑。镜像站的 SDK 仓库大多挂在 80 端口走 HTTP443 一般是给网页或者另一套服务用的。所以先试 80报连接被拒或者超时再换 443如果 443 报的是 SSL 握手失败那基本可以判断这个地址在 443 上不是同一个服务换回 80 或者换一个镜像地址别在协议上死磕。还有一个容易被忽略的字段No proxy for。本机回环地址和内部域名应该排除在外否则 IDE 连本地的一些服务也会被绕到代理上表现是一些莫名其妙的功能超时。填法就是逗号或竖线分隔的一串localhost,127.0.0.1,*.internal.example这种形式具体分隔符看输入框提示。3.3 保存之后怎么确认真的生效点了 Apply 不代表生效了得看配置文件有没有真的写下去。IDE 的代理设置会落到它自己的配置目录里文件名通常是proxy.settings.xml。找它的命令# macOS / Linux在配置目录里找代理配置文件 find ~/.config -name proxy.settings.xml 2/dev/null find ~/Library/Application\ Support -name proxy.settings.xml 2/dev/null # 找到后看一眼内容确认 host 和 port 与界面一致 cat 上一步输出的路径路径里会有一段厂商目录不同安装方式命名不一样所以用find通配比硬记路径靠谱。文件里能看到PROXY_TYPE_MANUAL、proxyHost、proxyPort这几个字段值跟你填的一致就说明写进去了。如果文件不存在或者还是PROXY_TYPE_NONE那就是 Apply 没点到或者点到了但 IDE 没有写权限。Windows 下对应的是%APPDATA%目录同样用资源管理器搜文件名最快。这一步的价值在于排错时能分清楚“是配置没写进去”还是“写进去了但不生效”这两类问题的处理方向完全不同混在一起查会浪费大量时间。4. 配套改三处才算配完Gradle、仓库镜像与 SDK 目录权限SDK Manager 的代理只保证 GUI 里的组件能下下来。一个工程能不能跑起来还差 Gradle 那一层。很多人 SDK 装完了、新建空工程结果 Sync 卡在 “Downloading” 上一动不动就是这一层没配。区别很好认SDK Manager 里下的是平台和构建工具Gradle 下的是依赖库两者域名往往都不是同一个。4.1 gradle.properties 里的代理四件套Gradle 不读 IDE 的代理配置它有自己的一套写法是通过 JVM 系统属性透传# 放在 ~/.gradle/gradle.properties全局或工程根目录 gradle.properties单工程 systemProp.http.proxyHostmirrors.example.edu.cn systemProp.http.proxyPort80 systemProp.https.proxyHostmirrors.example.edu.cn systemProp.https.proxyPort80 # 本机和内部域名不走代理用竖线分隔 systemProp.http.nonProxyHostslocalhost|127.0.0.1|*.internal.example四行必须成对出现只写 http 不写 https结果就是一部分依赖能下、另一部分一直重试。nonProxyHosts用竖线分隔这一点跟命令行环境变量用逗号不一样混用会导致规则不生效而且不报错属于典型的“配了但没起作用”。放全局还是放工程里取舍在于全局配置简单但换网络时容易忘掉后面会变成 502 的来源放工程里跟随代码走但要注意别把带账号密码的行提交进仓库。我的习惯是全局放域名和端口账号密码这类敏感项一律走环境变量或者干脆依赖免认证的镜像。如果不想改文件也可以临时用环境变量顶一下# 仅当前终端有效适合临时验证 export http_proxyhttp://mirrors.example.edu.cn:80 export https_proxyhttp://mirrors.example.edu.cn:80 export no_proxylocalhost,127.0.0.1注意环境变量的值是带协议头的完整地址跟gradle.properties里拆成 host 和 port 两行的写法不同这两种格式互相粘贴会直接报错。验证完记得unset不然下次开会话还在。4.2 仓库镜像不等于 SDK 镜像这一条值得单独拎出来说。SDK Manager 里的代理指向的是 SDK 仓库镜像Gradle 依赖走的是 Maven 仓库两者是不同的服务地址也往往不同。配好前者不代表后者通了反过来也一样。工程里的仓库声明一般长这样把镜像地址加在最前面// settings.gradle.kts dependencyResolutionManagement { repositories { maven { // 镜像仓库地址换成你自己能访问的那个 url uri(https://maven.example-mirror.cn/repository/public/) isAllowInsecureProtocol false } // 原有的官方仓库声明保持不动作为兜底 } }逻辑是就近优先请求先打到镜像镜像没有的再回落到官方源。isAllowInsecureProtocol保持false只有镜像地址确实是 http 时才需要放开放开意味着这段流量不加密能不放开就不放开。这段配置生效之后./gradlew拉依赖的速度会有明显变化。判断有没有真的走镜像加--info看日志里的下载地址就行日志里出现的是镜像域名而不是官方域名说明配置吃到了。这一步比看进度条靠谱得多进度条只告诉你快慢日志告诉你走的是哪条路。4.3 SDK 目录写入权限与非 ASCII 路径最后一项是最不技术、但翻车率最高的一项SDK 装在哪。两个硬性要求。第一路径必须当前用户可写。装在C:\Program Files或者系统级目录下SDK Manager 解压时会因为没有写权限失败报错信息通常是解压异常而不是权限拒绝容易带偏方向。第二路径不要带中文和空格。部分构建工具在拼接路径时不做过多的转义处理带空格的路径被截断之后报错会指向一个根本不存在的文件。检查权限的命令很简单# 确认 SDK 目录归属当前用户 ls -ld $ANDROID_HOME # 归属不对就改回来谨慎使用确认路径无误再执行 sudo chown -R $(whoami) $ANDROID_HOME$ANDROID_HOME指向 SDK 根目录新版工具里也有用ANDROID_SDK_ROOT的两个都设上不冲突但没必要认准一个即可。chown -R会递归改掉目录下所有文件的归属执行前把路径 echo 出来核对一遍改错目录的后果比权限问题严重得多。目录定好之后把这个路径同时写进 IDE 的 SDK Location 和命令行环境变量两边指同一个位置。见过不止一次“IDE 里能看到 SDK命令行sdkmanager --list却是空的”就是因为两处指向了不同目录各自装各自的最后磁盘上躺着两份 SDK。5. 避坑与排查代理配完还是 0% 的五条血泪记录下面这五条都是实际撞过的按现象、原因、解决三段写。顺序大致按出现频率排前面几条覆盖了大部分情况。5.1 五个现象对照第一条现象是组件列表能刷出来但下载进度条纹丝不动。原因通常是列表请求走了代理实际下载走了另一条通道最常见的是 GUI 配了、命令行没配或者反过来。解决办法是回到第 3 章把 GUI 和命令行两条通道分别用sdkmanager --list和界面里勾一个小体积组件各测一次哪条不通补哪条别一起改。第二条现象是填了 443 端口之后报 SSL 握手失败。原因是这个镜像地址的 443 端口跑的不是 SDK 仓库服务协议对不上。解决办法是换回 80 重试仍然不通就换一个镜像地址不要在端口上反复试错试到第十次也不会通。第三条现象是 SDK 装完了新建工程 Sync 失败报Could not resolve一类。原因是 Gradle 完全不吃 IDE 的代理设置它只认gradle.properties或者环境变量。解决就是 4.1 那四行补齐 https 那一对同时确认nonProxyHosts用的是竖线分隔。第四条现象是换个网络环境之后所有请求报 502或者一直转圈。原因是旧的代理配置还留着而那个镜像地址在新网络下不可达。解决办法是把 IDE 里切回 No proxy同时把gradle.properties里那几行注释掉两边一起切只切一边会得到更奇怪的现象。第五条现象是代理认证一直返回 407。原因是账号或密码里带了特殊字符被 URL 解析吃掉了或者是把账号密码拼进了 Host 字段。解决办法是老老实实用Username和Password两个独立字段不要搞拼接密码里有、#、:这类字符时优先怀疑是它们。这五条里前三条占了绝大多数。排查顺序建议固定下来先确认命令行通道通不通再确认 Gradle 通道通不通最后才去看 IDE 界面因为命令行输出的错误信息最完整界面上的提示往往只有一句“下载失败”信息量约等于零。提示排查时把 IDE 的日志窗口打开日志里的实际请求地址会明确告诉你走的是哪条通道、打到哪个域名。这比盯着进度条猜效率高得多。5.2 换镜像之前先做回滚别把后悔药弄丢代理配置有个特点改动很小但散落在三四个地方改的时候记得住过两周就忘干净了。所以换镜像地址之前先把现状备份一份这是最便宜的一份后悔药。# 备份 Gradle 全局配置 cp ~/.gradle/gradle.properties ~/.gradle/gradle.properties.bak.$(date %Y%m%d) # 备份 IDE 的代理配置路径用 3.3 里 find 出来的结果 find ~/.config -name proxy.settings.xml -exec cp {} {}.bak \; # 顺手记一下当前环境变量方便对照 env | grep -i proxy ~/proxy-env-$(date %Y%m%d).txt备份完之后再动手改。回滚的动作就是把.bak文件覆盖回去、把环境变量unset、IDE 里切回 No proxy三步走完再重启 IDE。别小看重启这一步IDE 的代理设置有一部分是启动时读进内存的不重启的话界面显示已经改了实际请求还在用旧的。还有一个习惯值得养成把当前这套配置写进一个自己的 setup 记录里哪怕只是几行文本记清楚镜像地址、端口、有没有认证、对应的网络环境。换机器的时候照着抄一遍比凭记忆重配快得多也不容易漏掉 Gradle 那四行。6. 验证跑通从空工程到第一个 APK 的三个检查点配置写完不等于通了。我一般用三个检查点串起来验每一个都对应一条独立通道任意一个不过就说明那一层还有问题不用往下走。第一关是命令行通道。执行sdkmanager --list | head -n 20能在一两分钟内刷出组件列表说明 JDK、PATH、代理参数三样都对。如果刷不出来先看报错是连接超时还是认证失败前者查 Host 和 Port后者查账号字段。第二关是 Gradle 通道。随便新建一个空工程或者用现成工程跑./gradlew :app:dependencies --configuration debugRuntimeClasspath --info在输出里找下载地址确认域名是镜像而不是官方源。这一关的价值在于把“依赖能不能拉到”和“代码能不能编译”分开验证出了问题定位范围小很多。第三关是产物。跑./gradlew :app:assembleDebug然后看app/build/outputs/apk/debug/目录下有没有生成 apk。这一关过完说明 SDK、构建工具、依赖三样都齐了。检查点通过标准不通过先查命令行通道sdkmanager --list正常出列表JDK、PATH、--proxy_*参数Gradle 通道日志里的下载域名是镜像地址gradle.properties的四行与仓库声明构建产物生成 debug apk 文件Build-Tools 版本、SDK 目录权限三关里最容易出问题的是第二关因为它的配置和第一关完全独立很多人验完第一关就以为大功告成。实际经验是第一关过了第二关卡住的比例相当高而卡住之后的报错又特别像“网络问题”一不留神就往代理上找原因其实只是少写了systemProp.https.*那两行。最后提一个技巧把这三个检查点写成一个小脚本放在工程根目录换机器时一条命令跑完输出里哪一关红了就补哪一关。脚本内容不用复杂三段命令加几个 echo 就够。这东西看着粗糙但它能把你从“感觉配好了”拉到“确认配好了”。从那以后我每换一台机器都先做一次完整的备份再按这三关走一遍确认全部通过才动手写第一行业务代码。吃过一次 SDK 半装不装、工程报错指向莫名其妙文件的亏就再也不想靠猜了。希望帮到你。本文还有配套的精品资源点击获取
