用 Android Studio 做开发最消磨耐心的事情不是编译报错而是新建项目后那根卡住的进度条。明明代码还一行没写Gradle 同步就已经卡了十几分钟最后弹出一句 Could not install Gradle distribution from...。我帮同事排查这类问题不下二十次核心就一句话Android Studio 默认从 Google 的官方服务器拉取 Gradle 发行包和依赖仓库这条链路在国内网络环境下速度极其不稳定。这篇笔记把我常用的“非手工下载安装包”的替换配置方案完整写出来不涉及任何额外工具只改几个配置文件照着操作就能把下载速度拉回正常水平。1. 先搞明白Gradle 下载慢到底慢在哪1.1 第一次同步时的“两条下载链路”新建一个 Android 项目或打开一个旧项目时Android Studio 并不是直接把项目跑起来那么简单它背后要完成两件大事。第一件事是下载 Gradle 发行包也就是那个gradle-8.x-bin.zip压缩包它由项目的gradle/wrapper/gradle-wrapper.properties文件里的distributionUrl决定下载完成后解压到本地 Gradle 用户目录中。第二件事是下载项目依赖也就是 Android Gradle Plugin、AndroidX 库、第三方库等这些来自仓库配置中的google()、mavenCentral()或者自建私服。这两条链路如果都走海外官方地址在本地网络下就会出现“慢”和“失败”两种典型表现。慢的时候那个下载进度条一个小时走不完失败的时候直接报Could not install Gradle distribution from https://services.gradle.org/...或者依赖解析阶段出现Could not resolve all dependencies。很多人误以为是电脑性能问题或者项目太大其实根子都在网络链路上。1.2 为什么手动下载安装包不是最优解网上很多教程会让你手动去浏览器下载gradle-8.x-bin.zip然后解压到本地目录再配置环境变量。这种方式确实能用但我个人很不推荐原因有三。第一浏览器下载同样走的是海外地址速度并不比 Gradle 内置下载快只是换了个进度条第二手动安装后还要处理 Android Studio 里 Gradle 路径的指向问题配置错了反而容易让 AS 找不到 Gradle第三项目使用 Gradle Wrapper 时AS 默认还是会去读distributionUrl你手动装的 Gradle 可能根本不参与构建。替换配置的方案就清爽很多只把下载地址里的域名从海外官方地址换成国内镜像地址Gradle 自己下载、自己解压、自己缓存路径和版本都由 Wrapper 控制完全不需要人工介入。这也是我认为这个方法值得写一篇完整博文的原因——它治的是根本而不是绕开问题。2. 方案选型改配置解决下载问题的三种思路2.1 核心思路对比围绕“替换配置”这个主题行业内常用的做法其实有三种。第一种是替换 Gradle Wrapper 的发行包下载地址解决gradle-X-bin.zip下载慢的问题第二种是替换项目依赖仓库地址解决依赖库下载慢的问题第三种是使用 Gradle 初始化脚本init.gradle做全局配置让本机所有项目自动生效。三种思路的侧重点不一样。Wrapper 替换只影响 Gradle 本体安装依赖仓库替换只管依赖拉取而init.gradle是更高维度的全局兜底。实际项目中新项目经常卡在发行包下载老项目则更容易在依赖解析阶段超时所以只改某一个往往不够。我见过有些人只改了 Wrapper 地址Gradle 本体下载飞快结果依赖解析又卡在dl.google.com上这就是没理解两条链路都要管。2.2 我的推荐组合wrapper 换源 仓库换源如果让我给一个最小可用方案那就是“wrapper 换源 仓库换源”组合。这两个配置改动量很小分别只涉及一到两处文本替换但覆盖了前面说的两条下载链路解决九成以上的下载慢问题。修改完项目能正常同步构建之后再考虑要不要用init.gradle做全局统一那是锦上添花的事情。顺序上也有讲究先修 Wrapper 地址再修仓库地址。因为 Wrapper 决定了 Gradle 能不能跑起来Gradle 都装不上的话依赖仓库配置得再漂亮也没有执行的环境。后面第三、四章我会分别给出这两个配置的完整实操步骤第五章再补上init.gradle的全局玩法。3. 实操步骤替换 Gradle 发行包下载地址3.1 定位 gradle-wrapper.properties 并确认版本在 Android Studio 中展开项目根目录找到gradle/wrapper/gradle-wrapper.properties这个文件双击打开。文件不长核心是几行键值对其中最关键的就是distributionUrl。典型内容长这样distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.13-bin.zip zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists注意看distributionUrl里的版本号比如上面是gradle-8.13-bin.zip。这个版本号必须和你项目实际需要的版本一致怎么确认打开 Android Studio 的File - Project Structure - Project可以看 Gradle version 这一项或者直接看这个文件本身通常它写的就是当前 Wrapper 锁定的版本。版本信息非常重要后面替换镜像地址的时候URL 里的版本号一个字符都不能差。3.2 替换为国内镜像地址阿里云 / 腾讯云 / 华为云把distributionUrl里的services.gradle.org域名替换成镜像域名即可。路径结构完全一致只是换了个 host。目前国内可用的镜像地址主要有三套我分别列出来。阿里云镜像稳定性和更新频率都不错distributionUrlhttps\://mirrors.aliyun.com/gradle/gradle-8.13-bin.zip腾讯云镜像同样是官方结构同步distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.13-bin.zip华为云镜像适合已经在用华为云生态的团队distributionUrlhttps\://repo.huaweicloud.com/gradle/gradle-8.13-bin.zip这里有个细节要提醒gradle-wrapper.properties是 Java Properties 格式官方模板里https后面的冒号带了一个反斜杠\:比如https\://services.gradle.org。改镜像地址时建议保留这个转义写法保持格式统一避免某些解析环境出问题。实际上不带反斜杠大多数情况下也能识别但没必要冒险直接复制上面我给的完整行最省事。3.3 改完配置后如何正确触发重新下载改完distributionUrl后很多人直接在 Android Studio 里点击 Sync结果发现还是一直转圈怀疑配置没生效。其实是因为 Gradle 第一次下载失败后会在本地缓存目录留下残留文件重新同步时它检测到已有部分文件可能直接跳过重试或者继续用坏文件。所以正确的操作顺序是先清缓存再触发同步。Windows 用户打开C:\Users\你的用户名\.gradle\wrapper\distsMac/Linux 用户打开~/.gradle/wrapper/dists找到目标版本对应的目录比如gradle-8.13-bin把这个目录下的内容删掉。然后在项目根目录打开终端执行一次命令./gradlew helpWindows 下如果使用系统自带的 CMD 或者 PowerShell执行的是gradlew.bat help这个命令会强制触发 Gradle Wrapper 按新的distributionUrl去下载发行包。终端里能看到下载进度、速度和落盘内容比 Android Studio 那个模糊的进度条直观得多。等命令执行完成不报错再回 Android Studio 正常同步速度会快到你怀疑之前网络有毛病。4. 实操步骤替换 Maven 仓库地址4.1 修改项目级 build.gradle / settings.gradle 的仓库配置Gradle 发行包装好后构建时依赖库还得拉得动。仓库配置的位置和项目创建时间有关这里两种结构我都会讲你根据自己项目情况对号入座。早期创建的 Android 项目Android Studio 4.x 及以前仓库写在根目录的build.gradle中分为buildscript.repositories和allprojects.repositories两块。在原有仓库列表最前面加上阿里云镜像顺序很重要镜像在前官方源兜底在后buildscript { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } } allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }新版项目Android Studio Arctic Fox 之后创建废弃了buildscript里的仓库配置改成在settings.gradle中用pluginManagement和dependencyResolutionManagement声明仓库。替换方式类似pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() gradlePluginPortal() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }为什么要保持镜像在前、官方源在后因为 Gradle 解析依赖时会按仓库声明顺序逐个查找“镜像优先”意味着绝大多数依赖都能从国内快速命中只有极个别镜像还没同步的构件才会回退到官方仓库这样既快又稳。反过来的话每次解析都先去官方源碰一遍壁再回头走镜像速度自然快不起来。4.2 常见镜像仓库对照与注意事项阿里云 Maven 镜像有几个常用仓库我整理了一个对照表方便你按需选择。镜像仓代理内容地址publicMaven Central JCenter 聚合https://maven.aliyun.com/repository/publicgoogleGoogle MavenAndroidX 等https://maven.aliyun.com/repository/googlegradle-pluginGradle 插件仓库https://maven.aliyun.com/repository/gradle-plugincentralMaven Central 纯净版https://maven.aliyun.com/repository/central腾讯云和华为云也有对应的 Maven 镜像腾讯云是https://mirrors.cloud.tencent.com/nexus/repository/maven-public/华为云是https://repo.huaweicloud.com/repository/maven/。我个人用得最多的是阿里云因为它的 google 仓库和 gradle-plugin 仓库拆分清晰踩坑少。一个容易忽略的点不要在仓库列表里堆太多镜像地址。有人图保险把阿里云、腾讯云、华为云全部加上结果 Gradle 每个依赖都要轮流请求三四个仓库解析速度反而被拖慢。选一个稳定的镜像作为主仓库就够了最多再留一个官方源兜底没必要贪多。5. 一劳永逸的全局方案init.gradle 脚本5.1 init.gradle 能解决什么问题如果你是个人开发者前两章的配置已经够用。但如果你在公司或者团队里经常要克隆各种项目每次新建项目都要重新改仓库配置时间久了就会觉得烦。更麻烦的是有些同事改了项目里某个仓库地址提交代码后把配置一起带上去其他成员拉下来构建时就会一脸懵。Gradle 提供了一个全局初始化脚本机制每次构建启动时Gradle 会自动执行用户目录~/.gradle/init.d/下所有以.gradle结尾的脚本。利用这个机制我们可以把镜像仓库配置写在一个全局脚本里对本机的所有项目生效。这样即便新拉下来的项目里写的是官方源构建时镜像仓库也会被自动追加进去可以很大程度避免“项目刚拉下来就卡在依赖下载”的问题。有一点需要先说清楚init.gradle管不了 Wrapper 发行包下载那一层是distributionUrl控制的。所以全局脚本替代不了第三章的 Wrapper 修改两个配置是配合关系而不是替代关系。5.2 完整配置与放置位置在用户目录下创建init.d文件夹然后在里面新建init.gradle文件。Windows 路径是C:\Users\你的用户名\.gradle\init.d\init.gradleMac/Linux 路径是~/.gradle/init.d/init.gradle。注意~/.gradle就是 Gradle 用户目录默认情况下 Android Studio 的 Gradle 也使用这个目录。文件内容如下allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } } }保存后重启 Android Studio 或者重新执行构建命令新的全局仓库配置就会生效。这个方案我用了很久确实省心但也要提醒一句全局脚本是追加在项目仓库列表之后的所以项目的google()和mavenCentral()仍然会参与依赖查找。不过因为有镜像优先兜着绝大多数依赖会在镜像仓库命中官方源基本不会产生实际请求流量所以速度影响可以忽略。6. 常见问题与排查经验实录6.1 高频报错速查表配置过程中最容易遇到下面几类问题我整理成了一张速查表你可以直接对照处理。报错信息原因解决方案Could not install Gradle distribution from ...Gradle 发行包下载失败检查distributionUrl是否已替换为镜像清空wrapper/dists缓存后重试Could not GET / Could not resolve all dependencies依赖仓库不可达或构件缺失仓库列表加入阿里云 google / public 镜像保持官方源兜底Minimum supported Gradle version is XAGP 要求的 Gradle 版本与 wrapper 不一致确认distributionUrl版本号与 AGP 要求匹配Gradle DSL method not found: minsdkversion()方法名大小写错误改为minSdkVersionDSL 方法名严格区分大小写Failed to notify dependency resolution listener仓库配置语法错误检查镜像 URL 是否拼写正确maven {}块是否闭合Deprecated Gradle features were used构建配置使用了旧特性属于警告不影响构建可忽略其中minsdkversion()这个报错虽然不是下载问题但出现频率极高。很多人在配置完仓库后顺手改build.gradle里的minSdkVersion结果手一抖打成全小写然后就看到了这行 DSL method not found。记住 Gradle DSL 是严格区分大小写的minSdkVersion、targetSdkVersion、compileSdkVersion这几个名字一个字母都不能改。6.2 排查思路配置正确但依旧下载慢如果配置看起来没问题速度还是上不去按照下面几步排查。第一步确认当前构建到底用的是哪个 Gradle。在项目根目录执行./gradlew --version看输出里的 Gradle 版本号再回到gradle-wrapper.properties里看distributionUrl的版本号。如果两者对不上说明本地可能装了独立 Gradle 而项目走的是 Wrapper版本信息错位会导致下载行为不符合预期。第二步看请求日志。执行./gradlew help --infoGradle 会输出每个仓库的访问记录仔细看日志里实际请求的域名是镜像还是官方源。如果日志里出现一堆对境外域名的请求说明镜像配置没生效检查是不是改错了文件或者全局init.gradle把仓库顺序覆盖了。第三步做一次干净验证。备份~/.gradle/caches和~/.gradle/wrapper/dists后清空再重试构建。有时候第一次下载失败产生的残留文件会影响后续重试干净环境下强制重新走一遍完整流程能把很多“玄学问题”一次性排除。6.3 我踩过的坑与个人习惯版本号必须完全匹配。我自己就干过一件蠢事项目要求的 Gradle 版本是 8.13我图省事把distributionUrl里的版本号改成了 8.10想着镜像上刚好有。结果 Gradle 下载完发现 Wrapper 锁定的版本对不上直接报版本校验错误。后来想明白distributionUrl里的版本号不是你想用什么就能填什么它必须和项目里 AGP 要求的 Gradle 版本严格一致。不要只改 Wrapper 不改仓库。早期我给一个老项目只改了 Wrapper 地址Gradle 本体飞快装好了结果同步依赖时又卡在一个第三方库上进度条半小时不动。后来把仓库镜像也加上一次性通过。经历过这次之后我每次都会同时检查这两个配置缺一不可。改完配置先跑命令行再开 AS。这是我个人的操作习惯修改配置之后不急着打开 Android Studio 点 Sync而是先到项目地址执行一次./gradlew help。终端里能看到下载速度、失败原因、仓库访问记录这些最真实的信息比 AS 的图形进度条可靠得多。命令行没问题了再回 Android Studio 正常操作。我自己从 Android Studio 3.x 时代就用这套方式处理 Gradle 下载问题前后帮十几个项目改过配置最深的感觉是这套方案解决问题的比例在九成以上而且不需要什么高深技巧就是找到配置文件、替换地址、重新同步。如果你也被 Gradle 下载卡到怀疑人生按这个顺序把 Wrapper 和仓库镜像都配一遍大概率一次到位。剩下少数疑难问题基本都能从命令行日志里找到答案。
