简介：面向Android开发者及项目构建维护者，这是一份以Gradle依赖统一管理为核心的资源包，解决多模块工程中依赖版本分散、升级困难与构建命令繁杂的问题。包内通过config.gradle等配置文件集中管理依赖版本，配合Gradle Wrapper保证构建环境一致，帮助团队规范依赖声明与任务执行流程。资源共34个文件，压缩包约100KB，以gradle配置、bat脚本、xml文件为主，另含png截图与markdown说明，兼顾配置参考与操作指引。内容涵盖gradlew常用命令（如assembleDebug、assembleRelease、clean、check等）及依赖统一管理示例，适合需要整合构建逻辑或刚接触Gradle的开发者对照练习。已有3654人学习下载，小巧实用，可快速获取构建配置要点，减少重复踩坑。 看到“Gradle依赖管理”这个词，很多Android开发者的第一反应可能是“这不就是往build.gradle里塞一行implementation吗”。但当你真正维护过几个多Module的大型项目，经历过依赖版本冲突、构建环境不一致、新同事入职光配环境就花半天这些事后，就会明白“统一管理”这四个字的分量。
这篇文章不讲那种“学习一下”的科普，而是直接把这几年在Android和Java后端项目里梳理Gradle依赖的实战经验摊开。你会发现，所谓统一管理，本质上是把“依赖”从零散的脚本里捞出来，变成一份可控、可查、可复现的项目资产。文章会围绕版本目录、仓库镜像、依赖锁定、AGP升级这几个最折磨人的点展开，适合已经被项目里的依赖问题烦到的开发者，也适合刚想建立规范的新人参考。
1. 依赖管理失控，通常是这三个阶段的开端
1.1 从“只有一个Module”到“依赖乱成一锅粥”
很多项目一开始都很清爽，一个app模块，一个build.gradle，十几个依赖。这时候谈统一管理，确实有点杀鸡用牛刀的意思。但项目不会永远停在单Module阶段，一旦拆出network模块、common模块、router模块，问题就开始冒头了。
最常见的情景是：app模块里用OkHttp 3.14，network模块里用了OkHttp 4.9，两个版本共存。编译倒是能过，但运行时某条代码路径上用了新版的API，另一个模块用的老版本实现，就会出现一堆诡异的ClassNotFoundException或者NoSuchMethodError。更烦的是，当你想升级某个三方库，得一个模块一个模块找过去，哪怕用全局搜索，也得反复确认哪里漏改了。
这就是依赖管理失控的典型信号：依赖版本散落各处，你根本说不清某个库在项目里到底用的是哪个版本。
1.2 版本冲突只是表象，真正的坑是“升级后遗症”
版本冲突还不是最难受的，毕竟Gradle会报Conflict，提示也算明确。真正让人头疼的是“升级后遗症”。
比如你把Android Gradle Plugin从4.2.0往上升级，编译直接给你来一句“you are applying flutter's main gradle plugin imperatively”，或者“deprecated gradle features were used in this build, making it incompatible with”，很多人看到这种报错直接懵了。这些问题的根子往往不在AGP本身，而是老工程里的build.gradle写法、插件应用方式、依赖仓库源，都停留在旧时代的习惯里。Gradle版本一升级，老写法自然不兼容。
所以统一管理依赖，本质上不是解决“版本号写在哪”的问题，而是解决“项目配置层面有没有一套跟得上生态演进的规范化体系”的问题。不做统一管理，每次版本升级都是一次野路子排雷。
2. 版本目录：把依赖的“版本号”和“坐标”彻底拆开
2.1 libs.versions.toml的基本玩法
Gradle从7.0开始正式支持Version Catalog，也就是版本目录。这个机制的核心思路特别朴素：把依赖的group、artifact、version拆开，全部集中到一个TOML文件里管理。项目里的build.gradle不再直接写版本号，而是引用目录里的键。
这个文件统一放在gradle/libs.versions.toml，结构长这样：
[versions] agp = "8.1.4" kotlin = "1.9.20" okhttp = "4.12.0" retrofit = "2.9.0" [libraries] androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version = "1.12.0" } okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" } retrofit-core = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" } [bundles] network = ["okhttp", "retrofit-core"]注意到两个细节。第一，版本号可以在[versions]里定义一次，然后通过version.ref来引用，这样OkHttp的版本只存在一处。第二，[bundles]这个段可以把一组经常一起引入的依赖打包成一个bundle，模块里一行就能引入整个网络库全家桶。
2.2 多Module场景下，版本目录才是最省心的方案
在模块里引用就非常清爽了，以build.gradle.kts为例：
dependencies { implementation(libs.androidx.core.ktx) implementation(libs.bundles.network) }版本目录会用自动生成的访问器帮你生成libs这个对象，用的时候有代码提示。相比之前那种直接写字符串坐标的方式，手滑写错版本号、漏更新某个模块这类低级问题基本被消灭了。
版本目录还带来一个几乎没人提的好处：因为版本是集中管理的，你可以在TOML文件里用注释写清楚每个依赖是干嘛的、升级到新版本会有什么风险点。这等于把“依赖升级注意事项”直接沉淀到了版本管理里，而不是散落在团队Wiki或者某个人的脑子里。
2.3 老项目迁移到版本目录，代价其实很小
很多人担心老项目切版本目录成本高，其实不需要一次性全改。build.gradle里已有的依赖声明可以零成本保留，新写的依赖或者要升级的依赖再往TOML里挪。整个迁移过程是渐进式的，完全不存在“不改造完就编不过”的窗口期。
个人建议迁移时可以顺便把重复依赖理一遍。比如很多项目里app模块和common模块各写一份glide，统一挪到版本目录后你会发现，这种重复引用特别容易暴露出来。
3. 仓库源统一：镜像配置与全局init脚本
3.1 别再让新同事第一天就卡在仓库源上
仓库源是另一个隐藏痛点。新手Android开发者遇到的第一个挫折，往往不是看不懂代码，而是新建项目后Gradle在那边慢慢吞吞地下载，一等等半天。很多人第一反应是网络问题，实际上90%的情况是仓库源用的是默认的google()和mavenCentral()，在国内网络环境下速度感人。
更麻烦的是，某些老项目为了干特殊事情，会在build.gradle里写一堆maven { url "..." }指向乱七八糟的私有仓库。时间一长，这个项目到底依赖了哪些仓库、哪些仓库已经没人维护了，完全说不清。
统一管理依赖，仓库源必须是第一道关。
以目前的主流配置来说，在settings.gradle.kts里这样写比较稳妥：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { // 阿里云镜像，兼顾速度和稳定性 maven("https://maven.aliyun.com/repository/public") maven("https://maven.aliyun.com/repository/google") maven("https://maven.aliyun.com/repository/gradle-plugin") google() mavenCentral() } }3.2 用init脚本做全局统一，而不是每个项目改一次
上面那种写法针对单个项目有效，但对那种经常要开新项目、或者公司内部有多个项目的团队来说，更省心的方案是用Gradle init脚本做全局配置。
Gradle在用户目录下有个~/.gradle/init.d目录，放到这里的.gradle文件会在每个Gradle构建启动时自动执行。你可以在这写一个全局仓库配置：
// ~/.gradle/init.d/mirror.gradle.kts allprojects { repositories { maven("https://maven.aliyun.com/repository/public") maven("https://maven.aliyun.com/repository/google") maven("https://maven.aliyun.com/repository/gradle-plugin") } }这里的逻辑不复杂：init脚本对所有项目生效，你不再需要在新项目里反复配置仓库源，也不会出现项目A能下载依赖、项目B因为少配一个仓库就构建失败的情况。团队内部如果用的是私服，也可以在这里统一导入。
3.3 依赖仓库有时也会“缺包”，得知道去哪里找
镜像和私服解决了下载速度问题，但偶尔会碰到另一种情况：某个依赖在阿里云镜像上没有，或者版本很老找不到。
这个时候别急着换仓库，先判断一下这个问题是“这个包真的不存在”还是“仓库里没有”。比如有些库只发布在JitPack上，你镜像配置再全也下不到。这种就单独加一个仓库：
maven("https://jitpack.io")如果项目里Google和AndroidX的库，阿里云google那个节点基本都有，速度也比直接连google()稳定。总之一句话：仓库源统一管理的目标是让你遇到问题时，能迅速定位到“包在哪个仓库”，而不是漫无目的地试。
4. 构建可复现：锁定依赖与离线构建逻辑
4.1 依赖锁定：让“昨天还能编”这句话成为历史
依赖版本管理的另一个核心问题是“版本漂移”。你没写死版本号的依赖，可能某天拉下来一个新版本，然后编译方式、运行时行为就变了，这比显式升级还要坑。
Gradle本身支持依赖锁定（Dependency Locking），开启后在构建时生成一份lockfile，将项目实际使用的依赖版本全部固定下来。以后无论何时重建，都会按照lockfile里的版本执行，除非你主动更新。
开启方式很简单，在根项目的build.gradle.kts里加上：
dependencyLocking { lockAllConfigurations() }然后执行一次依赖解析：
gradle dependencies --write-locks执行后会生成gradle.lockfile。这份文件建议直接提交到Git里，团队其他人拉下来构建时，用的依赖版本会和你的完全一致。这相当于给你的构建环境上了保险，尤其适合那种有多个开发并行、依赖更新频繁的团队。
4.2 离线构建与离线包：别让“下载”拖慢发布节奏
离线构建的需求，通常出现在两个场景：一是CI环境不允许访问外网，二是网络波动导致反复下载失败。
Gradle的命令行参数里有一个--offline，加上后Gradle不会访问任何远程仓库，只用本地缓存里的依赖。如果你的机器已经把项目完整构建过一遍，缓存基本是齐的，直接：
gradle assembleDebug --offline完全可行。有时候因为某个模块的依赖之前没拉全，离线构建会报错，这时候就得先在线构建一次补齐缓存。
还有一个很常见的问题是“gradle离线包”这个词，很多人搜这个其实是分不清Gradle发行版和依赖包的区别。Gradle发行版指的是gradle-8.5-bin.zip这种，它负责执行构建；而依赖包是项目通过坐标下载的三方库。前者长期不动，后者才是依赖管理的重点。如果你每次新建项目都要下载Gradle发行版，那大概率是Gradle Wrapper的distributionUrl指向了一个没缓存过的版本：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip这边建议如果网络条件一般，可以把distributionUrl换成公司内网或者镜像地址，避免每次初始化都卡在这一步。
4.3 统一Gradle版本，比统一依赖版本更优先
依赖锁定锁住了三方库，但构建工具本身的版本你锁定了吗？Gradle Wrapper就是干这件事的，它会把Gradle版本号写进gradle-wrapper.properties，团队所有人构建时都会用同一个Gradle版本。
很多时候“模块A能编、模块B编不了”的问题，最后查来查去竟然是两个人Gradle版本不一样。与其花时间排查这种环境差异，不如在项目一开始就通过Wrapper统一版本。升级Gradle版本时，也建议只在单独的提交里更新distributionUrl，跟代码变更分开，出问题好回滚。
5. AGP升级与Gradle版本对齐：绕不开的几个大坑
5.1 “deprecated gradle features”这类警告，不是可以无视的小事
国内开发者搜索“deprecated gradle features were used in this build, making it incompatible w”的次数很多，说明大家都遇到过这类警告。不少人的处理方式是“警告而已，能编译就行”，这其实是给后续升级埋雷。
这条警告通常意味着当前Gradle版本里某个API已经被标记废弃，而你的构建脚本或插件还在使用。Gradle官方策略一直是“废弃功能会在下个大版本移除”，所以你今天无视它，某次升级Gradle后可能直接构建失败，而且报错信息往往不直接指向你的代码，排查成本特别高。
建议的做法是升级完Gradle版本后，先跑一次构建把这类警告完整输出到日志文件，然后逐项排查，确认是哪个插件、哪个脚本触发的。如果项目里有老旧的第三方插件，警告基本都来自它们。能换新插件就换，不能换就先在脚本里用不触发废弃路径的写法规避。
5.2 从AGP 4.2到现代AGP：namespace与API迁移是硬门槛
把AGP从4.2升级到8.x，是很多老项目的噩梦。除了编译SDK版本要求提高，最直接的变更就是namespace。
AGP 8.0之后，build.gradle里的package属性被移除，必须声明namespace。这个声明虽然简单，但如果你项目里有AndroidManifest.xml里写包名，还有资源文件引用老包名的地方，迁移就要仔细处理：
android { namespace = "com.example.app" }另一个容易踩的是configurations或者依赖API的变化。比如compile和implementation混用、provided和compileOnly不区分，这些老写法在AGP升级后几乎都会报错。我见过不少项目卡在这一步，最后只能把AGP版本降回去。
升级AGP的同时，Gradle版本也要同步升。AGP 8.1对应的最低Gradle版本是8.0，AGP 8.4要求Gradle 8.6。版本没对齐，构建时大概率直接给出一句“AGP requires Gradle x.y”，不给你商量的余地。
5.3 插件应用方式迁移：从apply script到pluginManagement
Gradle社区现在推荐通过pluginManagement统一管理插件版本，而不是像老工程那样在每个模块里单独apply false或者用老式的buildscript块。老式写法不是不能用，但在新Gradle版本里越发别扭。
在settings.gradle.kts里用pluginManagement：
pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }在根项目的build.gradle.kts里声明插件版本：
plugins { id("com.android.application") version "8.1.4" apply false id("org.jetbrains.kotlin.android") version "1.9.20" apply false }然后在模块里就不带版本号直接应用：
plugins { id("com.android.application") id("org.jetbrains.kotlin.android") }这样做的好处是全项目的插件版本只出现在根项目一处，升级插件版本时只改一个地方，和依赖版本目录的思路如出一辙。如果你是在新项目里从零搭建，建议直接按这个模式来，别走老路。
6. 一些折腾过才懂的心得
6.1 依赖统一管理的“统一”，不只是版本号统一
版本号统一只是最表层的东西。真正的统一，是管理思路的统一。团队成员拉下代码就能构建，CI环境不会因为缺了一个仓库源而失败，升级依赖时影响面能快速评估出来。这些才是统一管理带来的实际价值。
如果你现在被项目里的版本冲突、仓库源混乱、老插件升级不动的问题缠上了，我的建议是小步快跑：先把仓库源统一了，再引入版本目录管理存量依赖，最后再决定要不要上依赖锁定。三步走完，项目在构建层面的状态会有脱胎换骨的变化。
6.2 最后再说一个细节
Gradle缓存目录里的东西，绝大多数情况下不要手动去删，因为删了之后重新构建反而更慢。遇到“下载失败”这种问题，更靠谱的办法是先去仓库页面确认这个依赖是否真的存在，再检查仓库源配置是否正确。版本升级这种事，慢就是快，多花几分钟在构建脚本的规范上，远好过上线前一天火急火燎排雷。
本文还有配套的精品资源，点击获取
