Android多模块Gradle依赖统一管理：Version Catalog与BOM实践

简介面向 Android 开发者的 Gradle 依赖统一管理示例工程主要解决多模块项目中版本号分散、依赖重复声明、构建脚本难以维护等问题适合已具备一定 Gradle 基础、希望规范工程配置的中级开发者参考。包内共 34 个文件以 8 个 xml、8 个 bat、4 个 gradle 脚本和 2 个 properties 配置为主另含 png 示意图、java 与 jar 示例、proguard 规则及 README 说明压缩包约 100KB体量轻便便于直接导入 Android Studio 对照查看。工程通过 config.gradle 集中声明依赖版本配合 settings.gradle、build.gradle 与 gradle wrapper 展示统一管理的目录组织方式bat 脚本则对应常用 Gradle 命令的批处理调用可帮助读者理解依赖抽取、版本收敛与构建流程之间的关系。目前已有 3661 人学习下载适合作为多模块 Android 项目依赖治理的入门模板与配置速查样本。1. 多模块 Android 项目依赖版本为什么会悄悄失控多模块 Android 工程最怕的不是编译报错而是这次能过、换台机器就过不了。A 同学把版本号散落在十几个 build.gradle 里升级一个网络库首页模块和播放模块各拉一个版本运行时才炸。Gradle 依赖统一管理要解决的就是这件事把版本、坐标、插件和约束收口到可审查的几份文件里让 android gradle management 从人肉对齐变成构建期校验。这套方案适合模块数超过三个、已经开始被传递依赖折腾的团队也适合刚接手老项目的同学。2. 选型先落地Version Catalog、BOM 与 buildSrc 的边界依赖统一管理最容易犯的错是一上来就把所有东西塞进 buildSrc。buildSrc 能写逻辑但它每次改动都会让主构建缓存失效Version Catalog 适合管版本和坐标却不适合写复杂条件BOM 适合对齐一组库的版本但前提是这组库有统一的平台声明。先把边界分清后面才不会被“统一”反噬。2.1 三种统一管理方案的适用面我一般按“版本、逻辑、平台”三个维度拆方案解决什么不适合什么Version Catalog集中声明版本、坐标、bundle、plugin aliasIDE 有补全不适合写动态条件、跨项目发布逻辑buildSrc / convention plugin复用插件应用、android 配置、公共依赖注入不适合频繁改版本号容易触发全量重编BOM / platform对齐同一生态下一组库的版本减少逐条写版本不适合没有 BOM 的零散库也不等于强制锁定常见做法是版本目录负责“有哪些版本”buildSrc 负责“怎么统一应用”BOM 负责“同一家族怎么对齐”。三者不是替代关系混用时要明确谁说了算。比如网络库家族走 BOM业务模块只写坐标插件版本走 Catalog公共 android 配置走 convention plugin。2.2 用 libs.versions.toml 建一份可复用的版本清单Gradle 默认会读取gradle/libs.versions.toml生成libs访问器。下面这份 TOML 里坐标用占位符实际项目替换成自己的 group 和 module 即可# gradle/libs.versions.toml [versions] agp 8.1.0 kotlin 1.9.0 coreKtx 1.0.0 appcompat 1.0.0 httpClient 1.0.0 jsonConverter 1.0.0 unitTest 1.0.0 [libraries] androidx-core-ktx { module com.example.androidx:core-ktx, version.ref coreKtx } androidx-appcompat { module com.example.androidx:appcompat, version.ref appcompat } network-http-client { module com.example.network:http-client, version.ref httpClient } network-json-converter { module com.example.network:json-converter, version.ref jsonConverter } unit-test { module com.example.test:unit-test, version.ref unitTest } [bundles] network [network-http-client, network-json-converter] [plugins] android-application { id com.android.application, version.ref agp } android-library { id com.android.library, version.ref agp } kotlin-android { id org.example.kotlin.android, version.ref kotlin }[versions]里的 key 是版本别名version.ref指向它[libraries]里的 key 会变成访问器比如network-http-client在 Kotlin DSL 里写成libs.network.http.client不是libs.network-http-client。[bundles]用来把多个库打成一个集合适合“网络层一次引三件套”的场景。[plugins]只放插件模块里用alias(libs.plugins.android.application)不要和普通依赖混用。注意别名里带连字符会映射成点号访问器别名不要以数字开头也不要用 Kotlin 关键字。改完 TOML 后先同步一次 IDE否则补全可能还是旧的。2.3 在 settings 与模块脚本里接入 Catalog在settings.gradle.kts里显式声明版本目录同时把仓库收口避免每个模块自己加仓库导致解析结果不一致// settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/gradle-plugins) } maven { url uri(https://repo.example.com/public) } } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/android) } maven { url uri(https://repo.example.com/public) } } versionCatalogs { create(libs) { from(files(gradle/libs.versions.toml)) } } } rootProject.name SimulatedProject include(:app, :feature-home, :feature-profile, :core-network)repositoriesMode设成FAIL_ON_PROJECT_REPOS后模块里再写repositories {}会直接失败这能在 CI 里拦住“某个模块偷偷换了仓库”的问题。versionCatalogs里显式create(libs)是为了在大型工程里固定文件路径小项目也可以依赖默认扫描但显式写更利于排查。include的模块名只是模拟项目按实际结构替换。模块脚本里只引用访问器// app/build.gradle.kts plugins { alias(libs.plugins.android.application) alias(libs.plugins.kotlin.android) } android { namespace com.example.simulated compileSdk 34 defaultConfig { applicationId com.example.simulated minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 } } dependencies { implementation(libs.androidx.core.ktx) implementation(libs.androidx.appcompat) implementation(libs.bundles.network) testImplementation(libs.unit.test) }alias(libs.plugins...)只用于plugins {}块libs.bundles.network会展开成两个依赖libs.unit.test对应 TOML 里的unit-test。参数上最容易被忽略的是compileSdk和targetSdk的版本要与 AGP 支持范围匹配但这不是 Catalog 的职责Catalog 只保证依赖坐标一致不保证编译工具链兼容。2.4 什么时候该用 BOM/platform 而不是逐条写版本同一家族库版本必须联动时用platform()比逐条写版本稳。比如网络层有客户端、转换器、日志三个库版本必须同源就可以在模块里这样写// core-network/build.gradle.kts dependencies { implementation(platform(com.example.platform:network-bom:1.0.0)) implementation(com.example.network:http-client) implementation(com.example.network:json-converter) }platform()表示“用这个 BOM 里的版本建议来对齐”但它不是强制锁如果某个直接依赖或传递依赖声明了更高版本解析结果可能仍然往上走。需要强约束时用enforcedPlatform()或者在constraints里写strictly。我一般优先platform()只有在发布包必须锁死、且团队确认不会再被传递依赖顶掉时才用enforcedPlatform()否则后期排查会多一层“为什么版本被强制了”的成本。3. 把公共依赖配置收进 buildSrc预编译脚本插件实战buildSrc 的价值不是“存版本号”而是把重复的插件应用、android 配置和公共依赖注入做成可复用逻辑。它会在主构建之前编译所以适合放稳定代码版本号还是放 Catalog避免改一行版本就触发大面积重编。下面这套结构可以直接照着搭。3.1 buildSrc 的目录结构与构建入口先建目录buildSrc/ build.gradle.kts settings.gradle.kts src/main/kotlin/com/example/gradle/AndroidLibraryConventionPlugin.ktbuildSrc/settings.gradle.kts用来固定 buildSrc 自己的仓库避免它和主工程解析到不同插件版本// buildSrc/settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/gradle-plugins) } maven { url uri(https://repo.example.com/public) } } } dependencyResolutionManagement { repositories { maven { url uri(https://repo.example.com/android) } maven { url uri(https://repo.example.com/public) } } }buildSrc/build.gradle.kts里应用kotlin-dsl声明 AGP 和 Kotlin 插件依赖并注册 convention plugin 的 ID// buildSrc/build.gradle.kts plugins { kotlin-dsl } repositories { maven { url uri(https://repo.example.com/android) } maven { url uri(https://repo.example.com/public) } } dependencies { // 版本要与根工程实际使用的插件版本保持一致避免 classpath 冲突 implementation(com.android.tools.build:gradle:8.1.0) implementation(org.example.kotlin:kotlin-gradle-plugin:1.9.0) } gradlePlugin { plugins { create(androidLibraryConvention) { id com.example.android.library.convention implementationClass com.example.gradle.AndroidLibraryConventionPlugin } } }这里的关键参数是implementation的插件依赖版本。buildSrc 会先编译如果它里面的 AGP 版本和主工程不一致可能出现“插件类能找到但 API 对不上”的玄学错误。我的血泪经验是把 buildSrc 的插件版本和根工程plugins {}里的版本放在同一个升级清单里升就一起升不要只升一边。3.2 写一个 Android 公共依赖 convention plugin下面这个插件做三件事应用 android library 插件、应用 Kotlin 插件、注入公共依赖。公共依赖里能用 BOM 的走 BOM避免在 buildSrc 里散落版本号// buildSrc/src/main/kotlin/com/example/gradle/AndroidLibraryConventionPlugin.kt package com.example.gradle import org.gradle.api.Plugin import org.gradle.api.Project import org.gradle.kotlin.dsl.dependencies class AndroidLibraryConventionPlugin : PluginProject { override fun apply(target: Project) { with(target) { pluginManager.apply(com.android.library) pluginManager.apply(org.example.kotlin.android) dependencies { // 公共依赖尽量走 platform业务模块只声明差异依赖 add(implementation, platform(com.example.platform:base-bom:1.0.0)) add(implementation, com.example.androidx:core-ktx) add(testImplementation, com.example.test:unit-test:1.0.0) } } } }pluginManager.apply的顺序会影响部分插件的初始化一般先应用 android 插件再应用 Kotlin 插件。add(implementation, platform(...))里的platform是 Gradle 的依赖约束入口不是普通字符串add的第二个参数可以接受MinimalExternalModuleDependency也可以接受字符串坐标。这里没有直接用libs访问器是因为 buildSrc 默认拿不到根工程的版本目录访问器常见做法是把版本交给 BOM或者用常量对象集中管理不要在 buildSrc 里手写一堆版本号。3.3 在模块里应用插件并保留可覆盖参数模块只需要应用 convention plugin再写自己的差异部分// feature-home/build.gradle.kts plugins { id(com.example.android.library.convention) } android { namespace com.example.feature.home } dependencies { implementation(project(:core-network)) // 公共依赖已由 convention plugin 注入这里只写模块差异 implementation(com.example.feature:home-ui:1.0.0) }id(com.example.android.library.convention)必须和 buildSrc 里注册的 ID 完全一致大小写、连字符都算。implementation(project(:core-network))是模块间依赖不走版本目录implementation(com.example.feature:home-ui:1.0.0)是模块私有依赖。convention plugin 不应该把模块所有依赖都写死否则模块失去选择权最后又会变成“想加一个库还得改 buildSrc”的新耦合。提示convention plugin 里适合放“所有模块都必须有”的依赖比如核心 KTX、测试基础库、BOM。业务库、UI 库、实验性库不要塞进去否则每个模块的依赖图都会变胖编译期和运行期都受影响。3.4 用 Gradle 批量脚本检查依赖漂移模块多了以后靠人眼看dependencies输出不现实。我一般会放一个 GradleBatchfile 风格的批量脚本在tools/下CI 和本地都能跑#!/usr/bin/env bash set -euo pipefail # 输出 app 模块 release 运行时依赖供批量比对 ./gradlew :app:dependencies --configuration releaseRuntimeClasspath build/deps-app.txt # 抓取出现多次的坐标行做一次粗筛 grep -E ^[\\-]--- build/deps-app.txt \ | sed -E s/^[\\-]--- // \ | sort \ | uniq -d build/duplicate-deps.txt if [ -s build/duplicate-deps.txt ]; then echo 发现重复坐标请检查版本对齐 cat build/duplicate-deps.txt exit 1 fi--configuration要按变体换调试包用debugRuntimeClasspath发布包用 releaseRuntime本文还有配套的精品资源点击获取