第3章：公司内部 Maven 仓库与代理仓库选型

在 AGP 版本升级及离线依赖缓存管理中，引入公司内部 Maven 仓库（或代理仓库）是减少外网依赖、统一版本管控、加速构建的核心手段。本章将围绕 Nexus、Artifactory、JitPack 三款主流方案进行离线缓存配置对比，并详解仓库优先级配置、认证与令牌注入的实战细节。

3.1 主流仓库对比总览

3.2 仓库优先级配置

Gradle 解析依赖时按照 repositories 块中声明的顺序依次查找。在离线环境下，必须保证 本地缓存 > 内部代理仓库 > 远程仓库 的查找顺序，否则会导致大量网络请求。

// build.gradle (项目级)
repositories {
    // 1. 本地 Maven 缓存（离线场景必备）
    mavenLocal()

    // 2. 内部代理仓库（Nexus 或 Artifactory）
    maven {
        url = uri("https://nexus.company.com/repository/maven-public/")
        // 认证注入见 3.3 节
        credentials {
            username = project.findProperty("nexusUser") ?: ""
            password = project.findProperty("nexusPass") ?: ""
        }
    }

    // 3. 远程 Maven Central（被代理仓库已缓存时不会触发）
    mavenCentral()
    // 可选：如果 JitPack 也被内部仓库代理，则无需单独声明
}

3.3 认证与令牌注入

内部仓库常要求基本认证或 。推荐使用 Gradle 属性 + 环境变量 注入，避免敏感信息硬编码到版本控制。

方式一：gradle.properties + 本地文件

# ~/.gradle/gradle.properties
nexusUser=android-builder
nexusPass=YOUR_PASSWORD_OR_

方式二：环境变量 + 系统属性

export NEXUS_USER=android-builder
export NEXUS_PASS=_xxx123
# 在 build.gradle 中读取：
nexusUser = System.getenv("NEXUS_USER") ?: ""
nexusPass = System.getenv("NEXUS_PASS") ?: ""

方式三：Bearer （Nexus / Artifactory 均支持）

maven {
    url = uri("https://nexus.company.com/repository/maven-public/")
    authentication {
        create<BasicAuthentication>("basic")
    }
    credentials {
        username = ""          // Nexus 固定用户名 ""
        password = "your-api-" // 实际  值
    }
}

3.4 离线缓存工作流（SVG 拓扑）

上图展示了标准解析路径：开发构建机首先命中 本地 Gradle 缓存（~/.gradle/caches/），若未命中则请求 内部代理仓库，内部仓库缓存未命中则回源到 远程 Maven Central / JitPack。认证令牌仅在内部代理仓库处注入，远程仓库通常为公开只读。

3.5 调试命令与常见错误排查

调试命令

# 查看 Gradle 依赖解析日志（详细输出）
./gradlew build --info | grep "Repository" | grep "from"

# Nexus 中查看缓存是否命中（REST API）
curl -u username:password -X GET "https://nexus.company.com/service/rest/v1/search?repository=maven-public&name=com.android.tools.build:gradle"

# Artifactory 缓存状态
curl -u username:password -X GET "https://artifactory.company.com/api/storage/libs-releases/com/android/tools/build/gradle/7.4.2/gradle-7.4.2.pom"

常见错误及修复

3.6 性能与稳定性优化

• Nexus 配置建议： 开启“智能搜索”索引，设置合理的过期策略（如 7 天未访问仍保留，避免频繁回源）。
• 多仓库镜像： 将 google()、mavenCentral()、jcenter()（已下线）等全部映射到同一个内部仓库组，减少 Gradle 多仓库串行查询时间。
• 预缓存（预热）： 在新环境（如 CI 节点）构建前，运行 ./gradlew dependencies --offline 强制下载所有依赖；若内部代理已缓存，速度可提升 10~50 倍。
• 证书问题： 内部仓库使用自签名证书时，需将证书导入 Gradle 的信任库或 Java cacerts，否则 SSLHandshakeException 会导致构建中断。