企业官网建设流程全解析

简介：围绕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 打底，别自己造版本组合

我一般按下面这张表取，不做花活：

表里最容易被忽略的是 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决定绝大多数构建工具用哪个 JDK，PATH只是让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或者工程里的仓库声明。

三份配置落在不同位置，这是很多人配完“看起来生效了但又没完全生效”的根源。大致对应关系如下：

先确认命令行工具到底能不能用，后面所有验证都依赖它：

# 确认 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 Proxy：Host、Port 与镜像地址的六个字段

真正落到填写的环节，先说结论：绝大多数卡住的人，需要的都是 Manual proxy configuration，而不是 Auto-detect。自动检测读的是系统级代理设置，只在机器上确实配了系统代理、并且那个代理支持 PAC 规则时才有意义。如果你的网络是直连但跨境出口很慢，自动检测的结果就是“什么都没检测到”，然后你会在原地等一个永远不会变快的进度条。

3.1 Auto-detect 什么时候管用，什么时候纯属浪费时间

判断方法很朴素：去看操作系统的网络设置里有没有配代理。配了，且那个代理允许被应用读取，Auto-detect 就能用；没配，或者配的是只对浏览器生效的那类设置，自动检测基本等于没开。

我踩过一次坑：某台办公机系统代理是开着的，Auto-detect 也确实读到了，组件列表刷得飞快，但下载到一半断掉。原因是那个系统代理对长连接有时限，SDK 的大包一断就得重来。后来改成 Manual，指向园区自建的镜像站，同一条网线，速度立刻不一样。所以自动检测“能用”和“好用”是两件事，凡是下载大包，我一般直接上 Manual。

Manual 模式下的字段一共就那几个，但每个都有讲究。下面这张表是我自己的填法：

表里的域名是文档占位写法，实际要换成你能访问到的那个镜像地址。这一点必须说清楚：镜像站的可用性跟网络位置强相关，同一个地址在办公网能通，回家可能就不通，所以配置属于“随环境走”的东西，不是一次配好永久有效。

3.2 字段逐个填，以及命令行通道的等效写法

图形界面按这个顺序走：Tools → SDK Manager → SDK Tools 标签页 → 右上角齿轮 → SDK Manager Settings → 选 Manual proxy configuration → 填 Host 和 Port → Apply。这一步没什么技术含量，重点在于填完之后 GUI 只解决了一半问题。

命令行通道要单独配一遍，否则你在终端里敲sdkmanager依然是直连。等效写法是这样：

# 命令行方式拉取组件列表，代理参数直接跟在命令后面 sdkmanager --list \ --proxy=http \ --proxy_host=mirrors.example.edu.cn \ --proxy_port=80 # 需要认证的镜像站再加两个参数 sdkmanager --list \ --proxy=http \ --proxy_host=mirrors.example.edu.cn \ --proxy_port=80 \ --proxy_user=your_account \ --proxy_pass=your_password

--proxy=http表示走 HTTP 代理协议，不是 HTTPS，这一项写错会直接连不上。--proxy_host只要域名，不要协议头也不要路径。--proxy_port跟图形界面填的保持一致，两边不一致时会出现“IDE 能下、命令行不能下”的诡异局面。后面两个认证参数，只在镜像站明确要求账号时才加，多数园区镜像站是免认证的。

顺带提一句端口的选择逻辑。镜像站的 SDK 仓库大多挂在 80 端口走 HTTP，443 一般是给网页或者另一套服务用的。所以先试 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.proxyHost=mirrors.example.edu.cn systemProp.http.proxyPort=80 systemProp.https.proxyHost=mirrors.example.edu.cn systemProp.https.proxyPort=80 # 本机和内部域名不走代理，用竖线分隔 systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.example

四行必须成对出现，只写 http 不写 https，结果就是一部分依赖能下、另一部分一直重试。nonProxyHosts用竖线分隔，这一点跟命令行环境变量用逗号不一样，混用会导致规则不生效而且不报错，属于典型的“配了但没起作用”。

放全局还是放工程里，取舍在于：全局配置简单，但换网络时容易忘掉，后面会变成 502 的来源；放工程里跟随代码走，但要注意别把带账号密码的行提交进仓库。我的习惯是全局放域名和端口，账号密码这类敏感项一律走环境变量，或者干脆依赖免认证的镜像。

如果不想改文件，也可以临时用环境变量顶一下：

# 仅当前终端有效，适合临时验证 export http_proxy=http://mirrors.example.edu.cn:80 export https_proxy=http://mirrors.example.edu.cn:80 export no_proxy=localhost,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、构建工具、依赖三样都齐了。

三关里最容易出问题的是第二关，因为它的配置和第一关完全独立，很多人验完第一关就以为大功告成。实际经验是，第一关过了第二关卡住的比例相当高，而卡住之后的报错又特别像“网络问题”，一不留神就往代理上找原因，其实只是少写了systemProp.https.*那两行。

最后提一个技巧：把这三个检查点写成一个小脚本放在工程根目录，换机器时一条命令跑完，输出里哪一关红了就补哪一关。脚本内容不用复杂，三段命令加几个 echo 就够。这东西看着粗糙，但它能把你从“感觉配好了”拉到“确认配好了”。

从那以后我每换一台机器，都先做一次完整的备份，再按这三关走一遍，确认全部通过才动手写第一行业务代码。吃过一次 SDK 半装不装、工程报错指向莫名其妙文件的亏，就再也不想靠猜了。希望帮到你。

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