做Android开发的人，十有八九都在Gradle上栽过跟头。刚装好Android Studio，新建一个项目，进度条就卡在Gradle构建那里一动不动，网络好的时候等几分钟，网络稍有波动半小时都走不完，甚至直接报Connection timed out。我刚开始接触Android那两年，被这套构建机制折磨得够呛——后来认真把Gradle的整个工作流程理了一遍，花了一下午把本地的Gradle配置好，之后不管开新项目还是接手老项目，构建都顺畅多了。这篇文章就把我在Android Studio里配置本地Gradle的完整经验写出来，覆盖版本匹配、环境变量、离线包使用、常见报错与排查，适合刚入门的Android新手，也适合被反复构建失败磨掉耐心的老手。

1. 为什么非要把Gradle配置到本地

1.1 Gradle在Android开发里到底干的是什么活

Gradle是一个自动化构建工具，Android项目的编译、资源合并、代码混淆、打包APK/AAB，这一整套流程全部由它接管。Android Studio本身并不直接编译你的代码，它只是把用户的点击操作翻译成Gradle任务，然后由Gradle去执行。你可以把它理解成一个工地上的总包工头，项目经理（Android Studio）只管提需求，真正干活的是Gradle带着一堆工人（各种Plugin和Task）去跑。

一个全新的Android项目，通常包含两个Gradle相关文件：项目根目录下的gradle/wrapper/gradle-wrapper.properties，以及build.gradle或者Kotlin DSL下的build.gradle.kts。前者规定了Gradle的版本和下载地址，后者规定了Android Gradle Plugin（后面简称AGP）的版本。可以说，Gradle就是Android项目的骨架，它的配置正确与否，直接决定你工程的生死。

1.2 被远程下载支配的恐惧

大部分新人都会遇到的场景是这样的：新建项目，Android Studio提示Downloading Gradle，然后就是漫长的等待。原因很简单——Android Studio在首次打开项目时，会依据gradle-wrapper.properties里写明的distributionUrl，从远程服务器把对应版本的Gradle发行包下载到本地。这个包通常有一百多兆，网速稍微不给力，等半小时是常事。

更让人崩溃的是，如果你接手了多个项目，不同的项目用的Gradle版本不一样，它就会分别下载对应版本，一个版本一个包，全堆在C:\Users\用户名\.gradle\wrapper\dists目录下。磁盘空间被吃掉不说，下载失败之后再次构建还会重新下载，没有任何断点续传的提示。我自己就遇到过一次，公司内网有代理限制，Android Studio反复报Could not download，那时候真想把电脑扔了。

1.3 本地化之后收益有哪些

把Gradle配置到本地，最直接的收益就是构建不再依赖网络，或者至少不再依赖那个一百多兆、慢得要命的首次下载。以后不管新建多少项目，只要Gradle版本在本地仓库里有，就不会再重复下载。

第二个好处是速度的提升。本地Gradle不用走网络请求，解压和加载都快很多；再配合离线模式禁用掉一堆远程依赖检查，整体构建时间能缩短一半，尤其对于刚打开项目的首次同步，体验差别极其明显。

第三个好处体现在团队协作上。公司或者学校里完全可以准备一台内网文件服务器，把常用的Gradle版本放上去，所有同事统一用本地的Gradle包。这样环境一致，构建问题大大减少，而且没有外网的机器也能正常开发。基于这些原因，我非常建议每个Android开发者都学会配置本地Gradle，后面做的事情会顺手很多。

2. 配置前的版本匹配工作

2.1 Gradle、AGP与JDK三者之间的约束关系

很多人配置Gradle失败的根源，不是步骤不对，而是版本没配对。Gradle本身是一个运行在JVM上的程序，它需要JDK才能启动；而Android项目里的AGP（Android Gradle Plugin）对Gradle版本有最低要求。这三者形成了一个链式依赖：AGP版本决定了Gradle的最低版本，Gradle版本又决定了它能运行在哪个版本的JDK上。

举几个常见的组合例子：AGP 7.4对应的最低Gradle版本是7.5，推荐用JDK 11或更高；AGP 8.0和8.1需要Gradle 8.0以上，JDK要求已经是17；到AGP 8.4之后，Gradle版本基本是8.6起步，JDK用17或21都没问题。如果AGP是7.x却配了Gradle 8.x，有可能因为Gradle版本太新导致AGP不兼容；反过来说AGP 8.x用了Gradle 7.4，对不起，直接报错，说Your current Gradle version is too low。

这里最关键的一点是，不要只盯着Gradle版本，要先确认项目的AGP版本，然后去查官方兼容表，再把Gradle和JDK对上。下面是我在实际项目里验证过的组合，你可以做一个参考。

2.2 从现有项目反推需要哪个Gradle版本

如果你要配置的是已有的老项目，操作非常简单。先用文本编辑器打开项目根目录下的gradle-wrapper.properties，看两行关键内容。第一行是distributionUrl，它决定了项目当前指定的Gradle版本；第二行是distributionSha256Sum，这个是可选的，用来校验下载的压缩包安全性，但有时候会因为配置失误造成校验失败。

然后打开根目录的build.gradle，搜索com.android.application或者com.android.tools.build:gradle，后面的版本号就是AGP版本。对照上面的表格，你马上就能知道该项目需要哪个版本的Gradle。如果发现项目里Gradle版本低于AGP要求，不要直接在Android Studio里盲目升级，而是先改distributionUrl指向一个合适的Gradle版本，然后再同步项目。

2.3 从零开始的项目怎么选版本

新项目的版本选择，取决于你的Android Studio版本。简单粗暴的方法：新建一个项目后，不要做任何修改，先看Android Studio自动生成的gradle-wrapper.properties里用的哪个Gradle版本，再看build.gradle里指定的AGP版本，这两个组合就是官方帮你配对好的，直接采用。然后把文件名中的版本号记下来，去下载对应的Gradle本地包就行。

如果你的项目是非Android的纯Java或Kotlin项目，用IDEA而非Android Studio，那只需要关注Gradle和JDK的对应关系。Gradle 7.x通常支持JDK 8到JDK 17，Gradle 8.x建议JDK 17以上。这种情况下，选择一个稳定的Gradle版本，再配合你本机装好的JDK即可，没有AGP这条限制链。

3. 本地Gradle配置实操全流程

3.1 准备一个固定目录并下载Gradle包

我先说结论：本地Gradle包需要一个专门目录，不要随手扔在下载文件夹里，否则后续管理和多版本切换会很痛苦。

我自己的习惯是在非系统盘建一个Gradle目录，比如D:\Gradle，然后在下面按版本号放压缩包和解压目录，例如D:\Gradle\gradle-8.7-bin.zip以及解压后的D:\Gradle\gradle-8.7。把压缩包和解压目录放在一起，不只是为了整洁，关键在于gradle-wrapper.properties改成本地路径时，可以直接指向这个zip包，让Gradle按需解压，无需手动解压。

下载Gradle的方式有两种。第一种是去services.gradle.org/distributions/下载对应版本的bin包，一般选-bin.zip，别下-all.zip，后者包含了源码和文档，体积大得多，实际开发用不上，白白浪费存储和构建时间。第二种是走国内镜像站下载，比如很多大厂的Gradle镜像都是同步官方仓库的，下载速度更快，适合网络不好的环境。下载完成后注意核对文件大小，zip包一般是一百MB上下，如果只有几MB，大概率是被劫持或者下载不完整，解压后一定报错。

3.2 修改gradle-wrapper.properties指向本地包

找到项目根目录下的gradle-wrapper.properties，文件内容类似这样：

distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists

要把Gradle指向本地，关键就是改distributionUrl。Windows下推荐写成file:///协议加上zip包的绝对路径：

distributionUrl=file\:///D\:/Gradle/gradle-8.7-bin.zip

注意这里有个坑：distributionUrl里的:和/在properties文件里需要转义，尤其是冒号前面的斜杠。如果不确定转义规则，建议像我一样把https://改成file:///之后，把冒号紧接着的路径部分也仔细检查一遍。还有一种写法是不带转义直接用file:///D:/Gradle/gradle-8.7-bin.zip，实测大部分情况下也能识别，但为了稳定我还是推荐带转义。

改完保存，回到Android Studio点击Sync Project。这时候Gradle会去解析distributionUrl，发现是file:///协议就直接从本地读取并解压，完成之后项目顶部不再显示Gradle下载进度，说明本地配置的第一步已经成功。

3.3 在Android Studio里指定本地Gradle分发

修改distributionUrl只是让项目能找到Gradle发行包，但我更推荐同时在Android Studio的设置里也把本地Gradle指定好。这样做的好处是，即使某个项目没有标出本地路径，Android Studio也会优先用你指定的那个Gradle，减少很多同步问题。

操作路径是：Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，右侧有个Gradle user home和Use Gradle from选项。默认情况下Use Gradle from选择的是Wrapper，也就是读取项目里的gradle-wrapper.properties。想统一走本地Gradle，可以选择Specified location，然后填上你解压出来的本地路径，比如D:\Gradle\gradle-8.7。注意这里填的是解压后的目录，不是zip文件。我把Android Studio的全局Gradle指定为本地之后，新建项目时它自动就会用本地Gradle，体验非常顺畅。

另外，Android Studio这里还可以设置Gradle JDK，下拉框里会让你选择JBR、JDK 17或者其他本机安装的JDK。这个要跟Gradle版本匹配，Gradle 8.x系列选JDK 17，Gradle 7.x系列可以选JDK 11，别选错。

3.4 配置GRADLE_HOME环境变量，让命令行也能用

Android Studio自带的Gradle配置解决了IDE内的构建，但命令行方式仍然需要环境变量。很多人在终端里执行gradle命令，总是提示gradle不是内部或外部命令，原因就是没有配置。

右键我的电脑 -> 属性 -> 高级系统设置 -> 环境变量，新建一个系统变量，变量名填GRADLE_HOME，变量值填Gradle解压目录，如D:\Gradle\gradle-8.7。然后在Path变量里追加一行%GRADLE_HOME%\bin。配好后重新打开一个终端，输入gradle -v，能打出版本信息就说明环境变量没问题。

配置环境变量的价值在于，某些场景下你必须用命令行构建，比如CI流水线、写脚本批量构建多个项目、排查Gradle缓存问题时，终端都是绕不开的。有了GRADLE_HOME，你在任何目录下执行gradle build或gradle assembleDebug都不会报找不到命令。

3.5 验证配置是否生效

配置完成之后，怎么确定真的生效了？两个信号。第一，打开一个项目，点击Sync之后，底部的构建日志里如果出现Using local Gradle distribution from D:\Gradle\gradle-8.7，就说明Android Studio确实读到了本地Gradle。第二，直接断网再同步一次，如果项目不依赖远程库，同步照常进行；如果还有远程依赖，至少Gradle本体的获取与解压不会再发起网络请求。

我自己的验证方法更暴力一点：项目同步成功后，去看C:\Users\用户名\.gradle\wrapper\dists目录，确认没有再新增大的zip文件；然后命令行进入项目目录执行gradle assembleDebug，观察构建过程不再有长时间的网络等待。两步都通过，这个本地Gradle配置就算彻底落地了。

4. 离线模式与团队内网场景

4.1 Gradle离线包的几种来源

很多读者问“Gradle离线包应该怎么搞”，其实离线包就是Gradle发行包的zip。最稳妥的来源是你本地已经下载好的缓存目录，路径在C:\Users\用户名\.gradle\wrapper\dists\gradle-8.7-bin\xxxx下面，里面有个gradle-8.7-bin.zip，这就是货真价实的离线包。你把它复制出来放到自己的公共目录里，以后每次配置本地Gradle都能直接用。

还有一种场景是公司或学校有一台内网服务器，所有同事统一从服务器拉取Gradle包。操作方式和本地配置一样，只是distributionUrl从file:///D:/Gradle/gradle-8.7-bin.zip改成http://内网服务器IP:端口/gradle/gradle-8.7-bin.zip。这种方式的好处是同事之间不需要拷贝大文件，而且Gradle发行包集中管理，升级版本时只需要替换服务器上的文件。这里需要注意的是，如果服务器带宽不够，多人同时同步时速度会变慢，最好提前把流量管控做大一点。

4.2 开启离线模式，构建速度再升一档

本地Gradle配好之后，Android Studio还会在每次构建时去检查远程仓库中的依赖版本，比如AndroidX库、第三方SDK等。如果网络不好或处于纯内网环境，这种检查不但没意义，还会拖慢构建。此时可以在Android Studio的设置里打开Offline work开关，位置在Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，勾选Offline work即可。命令行下则可以在构建命令后面加上--offline参数。

但要提醒一点：离线模式只对Gradle的依赖解析生效，如果你项目里有依赖需要下载而本地缓存里恰好没有，构建会直接失败并提示找不到某个库。因此离线模式更适合缓存完整、依赖变化不频繁的项目。正常开发时我一般开着离线模式，需要拉新依赖的时候再临时关掉，这样构建速度最快，也不会频繁报网络超时。

4.3 团队统一配置是避免环境差异的最好方式

每个人机器上Gradle版本不一致，是团队开发中最烦人的事情之一。项目A在张三电脑上构建正常，到了李四电脑上就报错，大概率就是Gradle或JDK版本差了一截。解决办法是在团队内部约定一套标准环境：统一Gradle版本、统一JDK版本、统一AGP版本，全部写入项目的文档或脚本里。

更进一步的做法是，把所有项目都用同一套本地Gradle配置。团队可以准备一个构建脚本，自动去固定的网络位置下载Gradle包，并设置好GRADLE_HOME和Android Studio的本地方向。这样一来，新人入职第一天跑一下脚本，构建环境就跟老同事们完全一致了，比手动折腾大半天再踩一堆坑要高效得多。我自己带过几次新人，这个方案帮他们省了不少力气。

5. 常见问题与排查技巧实录

5.1 卡在Running Gradle task 'assembleDebug'怎么办

这应该是Android开发中问得最多的问题之一。每次点击Run，底部就是一行Running Gradle task 'assembleDebug'...，然后转圈圈，半天没反应。

首先要搞清楚这句话的含义，它并不代表任务执行卡死，而是Gradle正在编译项目、打包资源、处理增量编译。首次构建出了奇的慢，因为要执行全量编译；后续构建如果没改动大部分代码，应该走增量缓存，时间是几十秒到一两分钟。如果你每次都特别慢，先检查是不是没开离线模式，是不是依赖重新下载了。我的排查顺序是：先看Build窗口有没有实际日志输出，再看网络监控有没有大量请求，最后看CPU和磁盘占用。如果一直没有任何日志，大概率是Gradle进程还在等待下载，这时候先用本地配置和离线模式把基础环境搞定，问题就解决了一大半。

另外，assembleDebug卡住还可能和Android Studio的缓存损坏有关系。可以执行File -> Invalidate Caches / Restart，清一遍缓存再同步。还不行，就删除项目的.gradle目录和app/build目录，全量重建一次。

5.2 Android Studio打不开，多半和Gradle缓存有关

Android Studio启动就闪退，或者一直停在进度条转圈，很多时候不是IDE本身坏了，而是Gradle的缓存或配置异常。最常见的情况是，昨天还能打开的项目，今天一打就崩，检查任务管理器里有没有多个Gradle Daemon进程还在跑。

我遇到这种情况的解决方法是：先杀干净Java和Gradle相关进程，然后用命令行进入C:\Users\用户名\.gradle目录，把wrapper\dists下面的目录清理掉，特别是那些压缩包和解压了一半的文件夹。最后再打开Android Studio，如果它还提示Gradle错误，就按第3.2节的方法重新配置distributionUrl指向本地。有几次我的Android Studio连新建项目都要崩溃，最后发现是之前下载的Gradle包损坏了，解压到一半就失败，清掉之后一切恢复正常。

5.3 运行App不显示，构建日志却显示成功

这个问题的现象是：构建结束没有报错，模拟器或真机上却没有弹出App。先确认设备上的App图标是否存在，如果存在但打不开，多半是Gradle打包的APK有问题，比如签名不对或者包名冲突，需要检查一下build.gradle里的applicationId。如果图标都没有，说明APK根本没有装上去，去命令行执行adb install app-debug.apk，看安装器报什么错。

另外，如果你的项目用的是Flutter，有时候App不显示和Gradle同名任务相关，比如热重载之后Gradle重新构建了Debug包但安装链路出了问题。这种情况下，可以手动执行一遍flutter clean，再执行flutter run，让它重新编译安装，很多临时问题都会自动消失。

5.4 提示Select the JDK you want Gradle to use

这句提示通常出现在打开一个新Gradle项目时，Android Studio让你选择Gradle构建用的JDK。原因是项目里配置的org.gradle.java.home找不到对应JDK，或者本机没有安装匹配Gradle版本的JDK。

最简单的处理方法是，在Android Studio的Settings -> Build, Execution, Deployment -> Build Tools -> Gradle里，把Gradle JDK手动设置为一个你已安装的JDK版本。如果你用的是Android Studio自带的JBR，直接选择jbr-17或jbr-21。如果你是命令行构建时报这个错，那就是JAVA_HOME环境变量没有设置或设置的路径无效。先确认java -version能打出正确版本，再确认Gradle版本能跑在这个JDK上，重开终端再执行构建。

5.5 IDEA里配置Gradle的通用套路

IntelliJ IDEA配置Gradle，和Android Studio几乎是一个流程，因为Android Studio本来就是在IDEA基础上改造出来的。打开一个Gradle项目后，IDEA会自动识别并尝试下载Gradle，同样可以用本地路径来跳过远程下载。位置在Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，把Use Gradle from改成Specified location，然后选择你本地的Gradle目录即可。

如果你在IDEA里开发纯Java或Kotlin项目，没有AGP那条约束链，版本选择就宽松得多。我平时用IDEA开发服务端项目时，都是直接指定一个本地的Gradle 8.x版本，配合JDK 17，速度和稳定性都很好。这里还要注意一点，IDEA和Android Studio的Gradle全局配置是分离的，即使你在Android Studio里配好了，IDEA那边还是要单独设置一次。

5.6 Flutter项目中Gradle插件相关警告的处置

现在用Flutter做跨平台开发的人越来越多，Flutter项目底层还是Android工程，自然也会遇到Gradle配置问题。有一种很常见的警告：构建时控制台提示You are applying Flutter's main Gradle plugin imperatively using the apply method，这是Flutter的构建脚本还在用旧式的apply plugin: 'com.android.application'写法，新版推荐改用plugins {}声明式写法。

这个警告一般不影响构建成功，但为了干净和未来兼容，可以在android/build.gradle里把相关配置改成新式写法。具体操作是，把根目录的build.gradle中allprojects和subprojects部分整理一下，并把apply plugin改成plugins块引入。不过如果你对Gradle还不熟，改之前一定要备份，因为Flutter每次升级可能还会重新生成配置，改错了反而会让构建失败。我个人的策略是，如果项目能正常构建，就先不动它；只有构建报错时才去调整。

6. 我的一些实际体会

最后聊几个我踩过坑之后留下的操作习惯，未必都是教科书标准答案，但确实管用。

第一，本地的Gradle包不嫌多。很多人以为配好一个版本的Gradle就一劳永逸了，但实际上项目换来换去，版本差异始终存在。我现在的D:\Gradle目录下面存了6个版本的Gradle，从6.7到8.7都有，占用空间总共也没多大，但每个项目打开都能秒配好。

第二，优先维护gradle-wrapper.properties，而不是全局的Gradle设置。原因很简单，项目的distributionUrl是跟着代码走的，团队成员一拉代码就能用同一套配置；而全局设置只对你自己这台机器有效。我见过有人只顾着Android Studio全局配置，项目里还是远程下载地址，换台机器就露馅。

第三，遇到构建问题先看日志而不是瞎猜。Android Studio的Build窗口右上角有一个Toggle view模式，能切到纯文本日志，里面每一行的报错原因都写得很清楚。很多人不点开看，直接到网上去搜问题描述，反而越来越乱，因为同样的提示背后可能对应完全不同的原因。先看日志，找到第一个报错的地方，从根上解决。

第四，关注distributionSha256Sum这个字段。如果gradle-wrapper.properties里写了这一行，而你把distributionUrl改成了本地文件，Gradle依然会校验hash值。如果你的本地压缩包和该hash对应不上，就会校验失败报错。解决办法是把distributionSha256Sum这一行删掉，或者重新计算本地包的sha256。这个坑我踩过一次，排查了整整半天，弄明白之后才发现只是校验问题。

Gradle的本地配置本身不复杂，但它牵扯到版本匹配、路径配置、缓存清理和离线模式多个环节，任何一个遗漏都可能让结果偏离预期。只要按照这篇文章的顺序走一遍，把每一步的验证点都过了，你的Android Studio环境应该不会再被“Downloading Gradle”卡得焦头烂额。后面的开发中如果再遇到问题，记得回到构建日志本身，从根上去定位，处理起来会轻松很多。