如果你是刚接触 Android 开发的新手大概率会遇到一个神奇的场景千辛万苦装好了 Android Studio满怀期待地新建工程结果界面下方一个gradle-wrapper.properties下载任务直接给你卡死半天进度条不动日志里疯狂报连接超时。这时候热心网友会告诉你“去配下 Maven 镜像”然后你看着build.gradle里的repositories一脸迷茫Gradle 是啥、Maven 是啥这俩到底啥关系这个坑我从大二踩到现在中间还给团队搭过完整的构建缓存体系。借这篇机会我把这两兄弟怎么配、为什么这么配、出了错怎么查一次性讲清楚。先说结论Gradle 负责“干活”Maven 仓库负责“提供材料和工具”。一个 Android 工程能不能又快又稳地跑起来90% 的功夫都花在这套配置上。这篇内容不挑基础零基础能照着配通老手也能在里面找到一些排查构建问题的思路。1. 先搞清楚 Gradle 和 Maven 到底分别干了什么活好多教程把 Gradle 和 Maven 混着讲搞得人晕头转向。用一句大实话区分Gradle 是你雇的施工队Maven 仓库是建材市场。施工队手里拿的图纸叫build.gradle需要什么材料就去建材市场Maven 仓库买买回来的材料统一放在本地仓库~/.m2或~/.gradle/caches里备用。1.1 Gradle真正的构建执行引擎Gradle 是 Android Studio 官方的构建工具负责整个编译过程的调度把 Java/Kotlin 代码编译成字节码、处理资源文件、打包成 APK/AAB、执行测试、生成多渠道包。它本身是用 JVM 语言写的所以运行 Gradle 必须先有 JDK后面会细说。Gradle 最核心的特征是基于任务的增量构建。它在执行时会先读一遍构建脚本Groovy 或 Kotlin DSL构建出一个任务依赖图然后只执行“需要执行”的任务。这就是为什么你第一次跑构建很慢、后面就快了——只有改动过的模块会重新编译。1.2 Maven一套依赖坐标与仓库标准Maven 本身也是一个构建工具但在 Android 开发语境下它更重要的身份是“依赖仓库的规范”和“仓库服务器”的代名词。每个第三方库在仓库里都有唯一的坐标比如经典写法com.squareup.okhttp3:okhttp:4.12.0拆开看是三层组ID:工件ID:版本号。Gradle 通过这个坐标去 Maven 仓库拉取对应的 jar/aar 文件。仓库地址常见的就这么几个Maven Central全球主仓库、Google 的 Maven 仓库专门放 AndroidX、AGP 插件、以及阿里云等国内镜像仓库。1.3 两者的配合关系仓库地址写在 Gradle 脚本里一般人以为“Gradle 和 Maven 是两种并列的技术”其实在 Android 工程里它们是协作关系。Gradle 构建时会在repositories代码块里去访问你配置的 Maven 仓库地址下载依赖下载完成后再由 Gradle 自己计算依赖树、执行编译和打包。类比一下施工队Gradle打开了建材市场Maven Central的地址按采购清单依赖坐标进货之后全程自己施工再用不上建材市场了。2. 环境准备JDK、Gradle、Maven这三样怎么选版本最省事很多人配置失败根源在于版本不对位。JDK 太老撑不起新版 GradleGradle 版本和 Android Gradle PluginAGP版本必须一一对应Maven 本身虽然没那么敏感但拿错版本也容易出幺蛾子。2.1 JDK优先用 Android Studio 自带的 JBR从 Android Studio 3.0 开始官方就内置了 JBRJetBrains Runtime本质上是一个定制版 JDK。如果你只在 Android Studio 里干活不搞命令行编译那你根本不需要单独安装 JDK——直接在File Project Structure SDK Location里能看到 Gradle JVM 位置。但如果你要在终端里执行./gradlew命令建议安装独立 JDK 17对应 AGP 8.x并配置好JAVA_HOME环境变量。JDK 17 是当前最稳妥的选择太新的 JDK 21 虽然能用但部分 Gradle 插件兼容性还差那么点意思JDK 8 太老新版 AGP 根本不认。2.2 Gradle版本与AGP版本对照关系AGP 升级是 Android 开发里最痛的操作之一因为 Gradle 和 AGP 之间有严格的兼容矩阵。经验值如下AGP版本最低Gradle版本推荐JDK7.47.5JDK 118.08.0JDK 178.58.7JDK 178.68.7JDK 178.78.9JDK 17查看项目当前用的 AGP 版本看根目录build.gradle里的com.android.application插件版本号。不要轻易跨大版本升级 Gradle宁可保持别人验证过的组合图个稳定。2.3 Maven版本其实不用特意装看到这里你得松口气如果你只是用 Gradle 构建 Android 项目根本不需要单独安装 Maven。Gradle 内置了对 Maven 仓库的访问能力所谓“Maven 配置”只是把仓库地址写进 Gradle 脚本而已。那什么时候需要单独装 Maven只有一种情况你要维护古老的工程用的是 Maven 构建而不是 Gradle 构建。这种工程在新版 Android Studio 里已经很难遇到了。不过既然很多人搜 maven 配置我在后面 4.2 节给出一条不踩坑的独立 Maven 安装路径。3. Gradle 核心配置下载慢、卡初始化怎么根治国内开发最常见的痛点就是新机器第一次打开工程GradleWrapper 要下载那一百多 MB 的 Gradle 发行包从 Google 的 CDN 拉速度和蜗牛没区别甚至直接超时失败。下面这套组合拳打完基本能做到“秒开旧工程”。3.1 先把 Gradle 发行包下载问题解决了Gradle Wrapper那个gradlew命令读取的是项目中gradle/wrapper/gradle-wrapper.properties文件里面distributionUrl指向 Gradle 压缩包的下载地址。默认指向services.gradle.org在国内极不稳定。推荐方案手动下载压缩包放进本地目录再用file:///协议指向它。操作步骤去腾讯云或其他国内镜像源找到对应版本的 gradle-8.7-bin.zip。手速快的可以直接改distributionUrl指向腾讯云镜像地址distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip把它下载好的 zip 文件解压到本地指定目录比如D:\gradle\gradle-8.7然后配置环境变量GRADLE_HOMED:\gradle\gradle-8.7再设置 Path 里加上%GRADLE_HOME%\bin。如果团队人多强烈建议内网共享一个 Gradle 压缩包地址用file:///协议直接引用这样每个人首次拉取构建环境的时间能控制在分钟级。3.2 指定 Gradle 用户目录与本地缓存Gradle 下载下来的依赖和发行包默认放在~/.gradle下这个路径占用极大动辄几十 GB。团队协作时最好统一定义GRADLE_USER_HOME指到公共目录比如D:\gradle\caches避免每个人的 C 盘都被塞满。同时在init.gradle或构建脚本里配置镜像仓库后面细说。3.3 看懂 gradle-wrapper.properties 的作用域这里划个重点gradle-wrapper.properties只决定“用哪个版本的 Gradle 去构建”和依赖仓库地址没有关系。依赖仓库是在build.gradle的repositories代码块里声明的。新手经常搞混改了 distributionUrl 以为能加速依赖下载结果发现没效果那是因为依赖下载走的是仓库地址那条逻辑。所以完整的加速链路是双层的第一层Gradle 发行包自身 —— 靠 distributionUrl/手动放本地解决。第二层依赖库 —— 靠后面的 Maven 镜像仓库解决。这两层不区分清楚你永远在错误的地方找毛病。4. Maven 仓库配置把依赖下载速度拉到满Gradle 构建脚本里依赖仓库地址写在哪、怎么写直接决定了你构建时要和哪个服务器“亲密接触”。我见过太多工程默认只有google()和mavenCentral()在国内那个下载速度真是一言难尽。4.1 在 build.gradle 里配置阿里云/腾讯云镜像全局搜索repositories代码块在settings.gradle中的pluginManagement、dependencyResolutionManagement以及根目录build.gradle的buildscript里统统加上镜像。这是我在实战项目里最顺手的一套配置pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() gradlePluginPortal() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }这里注意一点镜像地址要放在 Google 官方仓库之前。因为 Gradle 是按顺序依次查找仓库的找到后就不往下请求了。按这套顺序90% 以上的依赖请求都先打到阿里云只有阿里云没有的异常冷门库才会回源到官方。4.2 全局配置 init.gradle一次配置终身受用如果你不想在每个项目里都写一堆仓库地址可以走全局配置路线在GRADLE_USER_HOME目录默认是~/.gradle/下新建一个init.gradle文件把仓库镜像写进去。这样你本机所有 Gradle 项目都会默认走这个配置不用改项目里的任何文件。allprojects { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } } }这个文件最适合团队统一分发。Chef/Ansible 批量下发到开发者机器上大家构建体验都一样也不怕有人改错仓库地址导致构建行为不一致。它的优先级非常高几乎能“压制”项目内的 repository 声明所以使用前要确认团队的依赖都能从阿里云命中有些私有仓库需要额外补充。4.3 真要用独立Maven怎么装才对虽然是少数需求但此处给一条干净利落的独立 Maven 安装路径。下载 Maven 3.8.x 的apache-maven-3.8.8-bin.tar.gz解压后配置环境变量新建MAVEN_HOME指向解压目录Path 增加%MAVEN_HOME%\bin然后在MAVEN_HOME\conf\settings.xml里找到mirrors节点配置阿里云镜像mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror验证命令是mvn -v mvn help:system能看到版本信息、依赖能拉下来就算成了。如果你压根不用 Maven 构建项目这段看看就过别在自己机器上折腾多余的东西。5. 实操记录从零配通一个 Android 工程的全流程前面全是理论这里给一套我上个月给组里新人演示的标准流程应该能覆盖 95% 的场景。照着做下来新机器从拿到手到跑起工程应该不超过 15 分钟。第 1 步安装 JDK 17 并配置环境变量去 Adoptium 官网下载 OpenJDK 17安装完设置JAVA_HOMEC:\Program Files\Eclipse Adoptium\jdk-17.0.10.7 PATH%JAVA_HOME%\bin命令行里跑java -version能输出 17 开头第一步就过了。第 2 步安装 Android Studio 并解决首次引导Android Studio 装好后首次启动会引导下载 SDK 组件这些从 Google 拉也很容易失败。打开 Android Studio 的设置在Appearance Behavior System Settings HTTP Proxy里配置镜像代理或者直接用本地已经下好的 SDK。这一步和 Gradle 层面的加速是两回事别混在一起。第 3 步配置 Gradle 发行包加速把项目里的gradle-wrapper.properties的 distributionUrl 改成腾讯云镜像。执行一次./gradlew --version看到 Gradle 版本信息跑出来说明发行包问题解决。第 4 步配置 Maven 镜像仓库在根目录build.gradle或settings.gradle里加上阿里云镜像把androidx等常用依赖路径指到镜像地址。修改后执行./gradlew :app:assembleDebug第一次构建会拉 SDK 缺失组件和依赖观察日志里没有再出现Could not download或者长时间卡死速度处于能接受的范围就说明通了。第 5 步清理缓存并打包验证修改过仓库配置后最容易遇到“为什么仓库都改了还是下载失败”的问题原因往往是本地缓存里躺着旧的失败记录。执行./gradlew clean然后进~/.gradle/caches看是否有残留的半截文件删掉再重新构建。构建出 Debug APK 文件以后环境和配置就彻底通了。6. 构建配置进阶让项目打包速度和稳定性再上一个台阶配通只是入门能稳定高速地出包才是进阶。这套进阶配置是真正能帮你省下每一天“构建点杯咖啡”时间的核心。6.1 开启配置缓存与构建缓存在项目根目录的gradle.properties里加上这几行编译速度会直观提升不少org.gradle.cachingtrue org.gradle.configureondemandtrue org.gradle.paralleltrue org.gradle.jvmargs-Xmx4096m -Dfile.encodingUTF-8parallel让多个模块并行构建caching让构建结果可以跨项目缓存复用。特别是有多个依赖项目的工程这里调优前后体感差异很明显。但注意configureondemand有时会导致动态变化的任务图不生效你自己二分法试一下再定。6.2 使用离线模式调试依赖问题在命令行里加一个--offline参数可以强制 Gradle 只使用本地缓存的依赖。这个对排查“新引入的库到底有没有下下来”特别好用如果离线模式能编译过说明依赖都在本地如果提示缺件则说明有的依赖没下载成功需要切到在线模式单独拉取。6.3 手动管理 Gradle 离线分发包如果你所在的公司有外网隔离要求对应的离线环境里只靠下载一个 Gradle 压缩包还远远不够。你还要提前把~/.gradle/caches里的依赖目录完整拷贝出来在离线机器上放到相同位置再配合--offline构建。这里不存在“配一下地址就能解决”的魔法必须是“依赖也在本地”两全才能通。7. 常见问题排查这几类错误我几乎天天见结合我带新人的经验和社区里的高频提问整理了几类出现频率极高的错误直接给结论和解决方向。7.1 Could not install Gradle distribution from ...日志里这一长串英文翻译成人话是“从网上下载 Gradle 失败了”。先检查 distributionUrl 是否指向可达地址再确认网络策略是否封了 services.gradle.org。解决路径两条换成腾讯云镜像地址或者本地解压好 Gradle 后用file:///协议指向到本地。注意官网给的 bin 包和 all 包体积不一样配置 wrapper 时必须对应 bin 包的 URL否则 Gradle 会拒绝使用报 hash 校验错误。7.2 Could not find com.android.application:...构建时报错找不到 AGP 插件大部分是仓库里没配 gradle-plugin 镜像。AGP 插件其实发布在 Google Maven 和 Gradle Plugin Portal 里但国内直接访问不稳定。settings.gradle中pluginManagement里的maven { url https://maven.aliyun.com/repository/gradle-plugin }一定要有并且放在最前面。7.3 报错提示需要更高版本的 Gradle但我不想升AGP 版本和 Gradle 版本的对应表是硬约束没有商量余地。要么升级 Gradle要么降级 AGP 版本。推荐做法看当前 AGP 要求的 Gradle 最低版本升级到刚好满足且不超过 AGP 验证范围的值。比如 AGP 8.3 要求 Gradle 8.4你往上装到 8.7 一般问题不大别一上来就升到 8.10。7.4 仓库配置了镜像依赖还是下载失败第一反应是确认你改的构建脚本文件对不对。settings.gradle里的dependencyResolutionManagement会全局接管仓库配置你在模块级build.gradle里写仓库是没用的。而且如果repositoriesMode设置为FAIL_ON_PROJECT_REPOS模块内自己声明仓库会直接报错。组件缓存如果之前已经在官方仓库那边请求过失败了切镜像后也要删掉~/.gradle/caches/modules-2/files-2.1里对应坐标的目录再重试否则本地残留的.part文件会让下载逻辑直接跳过搞得你怎么切地址都没反应。7.5 Android Studio 中文设置和工程能否正常配置无关很多新手搜“Android Studio 怎么设置中文”以为界面中文化会影响 Gradle 构建。完全不影响。插件市场装个中文语言包或直接改 64 位虚拟机参数都行。构建配置是纯构建层面的东西和 IDE 显示语言无关。7.6 Kotlin DSL 和 Groovy DSL 的差异现在的工程有两种构建脚本风格老的.gradleGroovy和新的.gradle.ktsKotlin。网上搜到的配置代码大多是 Groovy 的直接复制到.kts文件里会报错。比如.gradle.kts里仓库配置长这样repositories { maven { url uri(https://maven.aliyun.com/repository/public) } google() mavenCentral() }眼睛放亮点先确认你的脚本后缀再决定代码怎么写。8. 团队建设大坑仓库地址别每人一套最后说点团队协作层面的东西。好多人图省事自己在本地配一套阿里云镜像项目代码里保持官方地址以为各搞各的不影响。实际后果就是你本地构建飞快CI 服务器上瞬间被打回原形换台新电脑重新拉工程又是慢吞吞从官方仓库下依赖。正确的做法是把仓库镜像方案直接提交进项目配置文件里也就是settings.gradle里写死镜像地址。这样团队所有人、CI 机器默认就是加速配置不存在“某人特有的配置漂移”。如果你的项目引用了不少私有库集中在公司内网搭建一个私服管理内部依赖和对外镜像缓存效果会更好。Gradle 配置私服仓库的方式和配置阿里云镜像一样只是地址不同maven { url http://repo.example.com/repository/maven-public/ allowInsecureProtocol true }注意allowInsecureProtocol只有在内网 http 协议时才需要加正式环境务必用 https。打包配置这套东西看起来无聊真出问题的时候才是节约生命的大杀器。我个人从最早在国内下 Gradle 发行包下到想砸电脑到现在几分钟配好环境、新同事入职当天就能跑不起工程再到夸我一顿中间攒下来最多的经验就是一句话仓库镜像锁进仓库里Gradle 发行包用国内源JDK 版本不要标新立异。照着这条路走你至少能避开我当年踩过的一大半坑。