第2章 仓库管理与镜像配置

2.1 仓库机制与镜像加速原理

Gradle 依赖解析的核心是 仓库（Repository）。当一个模块声明了依赖坐标（如 com.google.guava:guava:31.1-jre ），Gradle 会按照 repositories 块中声明的顺序依次查询每个仓库，直到找到目标产物（POM + jar）。

• 远程仓库：HTTP(S) 协议访问的 Maven/Ivy 仓库，可以是公共仓库或企业内部私有仓库。
• 镜像（Mirror）：将一个仓库的请求全部或部分重定向到另一个更快/更稳定的地址，主要用于加速国内网络的依赖下载。
• 认证：私有仓库通常要求提供凭证（用户名/密码或令牌）才能读取或发布。

以下表格对比了最常见的仓库类型及推荐场景：

2.2 repositories 配置语法与 API

在构建脚本中通过 repositories { ... } 块配置所有依赖仓库。支持的声明方式：

repositories {
    // 内建快捷方式
    mavenCentral()
    // 或显式 URL
    maven { url "https://repo1.maven.org/maven2" }
    // Google Android 仓库
    google()
    // 自定义 Maven 仓库
    maven { url "https://nexus.example.com/repository/maven-public" }
    // 本地文件仓库
    maven { url uri("${project.rootDir}/local-repo") }
    // Ivy 仓库
    ivy { url "https://repo.example.com/ivy" }
}

2.3 阿里云镜像配置

针对国内网络环境，推荐使用阿里云镜像替代 mavenCentral、google 等仓库。有两种配置方式：

2.3.1 全局镜像（settings.gradle）

在 settings.gradle 中通过 dependencyResolutionManagement 全局替换所有仓库：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        mavenCentral()
    }
}

2.3.2 项目级镜像（build.gradle）

在根项目或子项目的 repositories 块中直接声明镜像仓库，并移除 mavenCentral 等原始仓库：

repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    maven { url 'https://maven.aliyun.com/repository/google' }
    // 如果还需要其他仓库，按需添加
    mavenCentral()
}

2.4 私有仓库与认证配置

企业内部的 Nexus、Artifactory、GitLab Package Registry 等私有仓库通常需要认证。Gradle 支持多种认证方式：

repositories {
    maven {
        url "https://nexus.example.com/repository/maven-private"
        credentials {
            username = "admin"
            password = "secret"
        }
        // 也可以使用文件或环境变量避免硬编码
        // credentials(PasswordCredentials) {
        //     username = findProperty("nexusUsername") ?: System.getenv("NEXUS_USERNAME")
        //     password = findProperty("nexusPassword") ?: System.getenv("NEXUS_PASSWORD")
        // }
    }
}

推荐将凭证存储在 ~/.gradle/gradle.properties 或 CI 环境变量中：

# gradle.properties
nexusUsername=admin
nexusPassword=secret

2.5 调试仓库解析

在构建时添加 --info 或 --debug 参数可以查看 Gradle 从哪些仓库尝试下载：

gradle dependencies --info
# 输出示例（过滤后）：
# [INFO] [org.gradle.internal.resource.transport.http.HttpResourceAccessor] Resource resolved: https://repo1.maven.org/maven2/com/google/guava/guava/31.1-jre/guava-31.1-jre.pom
# [INFO] [org.gradle.internal.resource.transport.http.HttpResourceAccessor] Resource resolved: https://maven.aliyun.com/repository/public/com/google/guava/guava/31.1-jre/guava-31.1-jre.pom

如果仓库配置了认证但失败，Gradle 会输出 401 Unauthorized 或 403 Forbidden 及详细响应体。

2.6 常见错误与解决方案

2.7 性能优化：仓库顺序与缓存

• 仓库顺序：将最快的仓库（如阿里云镜像）放在最前面，减少查询延迟。
• 本地缓存：Gradle 默认使用 ~/.gradle/caches 缓存已下载的依赖，无需重复下载。
• 离线模式：开发环境网络不稳定时，使用 gradle build --offline 强制仅使用本地缓存。
• 清理缓存：当缓存损坏时，执行 gradle cleanBuildCache 或手动删除 ~/.gradle/caches 目录。

2.8 仓库解析与镜像配置核心流程

2.9 本章小结

仓库配置是 Gradle 依赖管理的起点。合理选择仓库、配置镜像加速、安全存储认证信息，可以大幅提升构建速度和稳定性。建议每个项目至少包含一个快速镜像（如阿里云）和一个可靠的 fallback 仓库（如 mavenCentral）。私有仓库务必使用加密凭证，避免在构建脚本中明文书写密码。