第四章 依赖声明与仓库配置
依赖声明与仓库配置是 Gradle 构建体系的核心环节，决定了项目如何定位、下载并集成第三方库。本章将深入解析 repositories 块的配置机制、依赖声明的作用域（implementation、api、compileOnly 等）以及 classpath 隔离原理，并通过完整示例和调试手段帮助你掌握生产级依赖管理实践。
4.1 仓库配置原理
Gradle 通过 仓库（Repository）存储和检索依赖。每个仓库是一个模块化的资源索引，通常指向一个远程 Maven/Ivy 仓库或本地的文件目录。构建脚本通过 repositories 块声明仓库列表，Gradle 按声明顺序依次尝试从这些仓库中获取依赖。
| 仓库类型 | 配置示例 | 适用场景 |
|---|---|---|
| Maven Central | mavenCentral() | 公开托管绝大多数 Java/Kotlin 库 |
| JCenter（已停止服务） | jcenter() | 历史遗留项目，新项目应迁移 |
| Google Maven | google() | Android 官方库、Jetpack 组件 |
| 自定义 Maven 仓库 | maven { url = uri(...) } | 公司内部私有库、镜像或自建仓库 |
| 本地文件仓库 | flatDir { dirs("libs") } | 离线开发、本地 jar 包集成 |
注意：JCenter 已于 2021 年 4 月停止新包提交，2022 年 2 月永久只读。所有新项目应优先使用
mavenCentral()，并尽快将依赖从 JCenter 迁移至其他仓库。
4.2 依赖声明与作用域隔离
Gradle 提供了多种依赖配置（Configuration），用于控制依赖的可见性、传递性和编译期/运行期范围。正确使用这些配置可以避免类路径污染、减少构建时间并提升运行时效率。
| 配置 | 作用范围 | 是否可传递 | 典型用途 |
|---|---|---|---|
implementation | 编译期当前模块可用，运行期对所有模块可见 | 否 | 内部依赖，对外隐藏实现细节 |
api | 编译期当前模块及消费者都可见 | 是 | 需要暴露给使用者的公共接口 |
compileOnly | 仅编译期可用，运行期不存在 | 否 | 注解处理器、编译期代码生成 |
runtimeOnly | 仅运行期可用，编译期不可见 | 否 | JDBC 驱动等运行时必备但编译期不使用的库 |
testImplementation | 测试编译期和运行期 | 否 | 测试框架，如 JUnit、Mockito |
classpath | 仅作用于构建脚本自身，不影响项目依赖 | — | 插件、构建工具库（如 Kotlin Gradle Plugin） |
最佳实践：优先使用
implementation 而非 api，可显著减少编译重触发的范围，提升增量构建速度。仅当模块的消费者确实需要访问该依赖的类型时才使用 api。
4.3 实现流程：完整配置示例
以下是一个 Kotlin DSL 构建脚本示例，展示了仓库配置与依赖声明的典型结构：
// build.gradle.kts 完整的依赖管理示例
plugins {
kotlin("jvm") version "1.9.22"
id("java-library") // 启用 api 配置
}
repositories {
// 按查找优先级顺序声明
mavenCentral() // 1. 首选 Maven Central
maven { url = uri("https://maven.google.com") } // 2. Google Maven（Android 库）
maven { url = uri("https://repo.mycompany.com/releases") } // 3. 公司私有仓库
flatDir { dirs("libs") } // 4. 本地 libs 目录
}
dependencies {
// 构建脚本自身依赖（插件 classpath 在此，但通常放在单独的 buildSrc 或复合构建中）
// classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22")
// 项目依赖
implementation("com.google.guava:guava:32.1.3-jre")
api("com.squareup.okhttp3:okhttp:4.12.0") // 暴露给调用者
compileOnly("org.jetbrains:annotations:24.1.0") // 编译期注解，不打包
runtimeOnly("org.postgresql:postgresql:42.7.1") // 仅运行期需要
testImplementation("org.junit.jupiter:junit-jupiter:5.10.1")
}
4.4 调试依赖：查看依赖树
使用 Gradle 内置的 dependencies 任务可以输出完整的依赖树，帮助排查版本冲突、缺少依赖或作用域错误。
# 查看所有配置的依赖树
gradle dependencies
# 查看特定配置（如 implementation）的依赖树
gradle dependencies --configuration implementation
# 输出结果示例片段：
# ------------------------------------------------------------
# Root project
# ------------------------------------------------------------
# implementation - Implementation only dependencies for source set 'main'.
# \--- com.google.guava:guava:32.1.3-jre
# +--- com.google.guava:failureaccess:1.0.2
# \--- com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-google... (c)
调试技巧：使用
--refresh-dependencies 强制 Gradle 清除缓存并重新解析所有依赖；使用 --offline 在无网络环境快速检查本地缓存中的依赖是否完整。
4.5 classpath 隔离：构建脚本与项目依赖的边界
Gradle 将构建脚本自身（Gradle API、插件）与项目代码的依赖严格隔离。通过 classpath 配置声明的依赖仅用于构建过程，不会泄漏到项目类路径中。这种隔离机制保证了构建工具和项目代码的并行演进，避免版本冲突。
// 在 build.gradle.kts 中声明构建脚本依赖（通常通过 buildscript 块或 plugins 块）
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22")
}
}
现代 Gradle 推荐使用 plugins 块管理插件，自动处理 classpath，无需手动声明 classpath 依赖。
4.6 常见错误与解决办法
- 仓库找不到依赖：检查仓库 URL 是否可访问，依赖坐标是否完整（group:artifact:version）。使用
mavenCentral()时注意版本号格式，不要遗漏分隔符。 - 版本冲突：Gradle 默认采用“最新版本”策略。如需强制指定版本，使用
force = true或strictly版本约束。 - 依赖泄露：误用
api导致传递依赖暴露，可通过compileOnly或runtimeOnly替代。 - classpath 与 implementation 混淆：将插件依赖放在
dependencies块而非buildscript中会导致构建失败。
4.7 性能与稳定性优化
- 启用依赖缓存：Gradle 自动缓存下载的依赖。定期执行
gradle cleanBuildCache可清除缓存，避免陈旧版本。 - 避免动态版本：慎用
1.+或latest.release，每次构建都会远程检查，降低构建速度且可能导致非确定性构建。 - 使用版本目录（Version Catalog）：集中管理所有依赖版本，避免散落在各模块的
dependencies中。 - 仓库排序优化：将访问速度最快、命中率最高的仓库放在
repositories块最前面，减少网络请求次数。