（二）Gradle 依赖仓库及安全凭证配置

仓库（Repository） 是存储项目依赖（如 JAR、AAR、POM 文件等）的位置。构建项目时，Gradle 会通过仓库来查找和下载项目所需的依赖。因此，我们必须 显式声明 仓库地址，告诉

Gradle 去哪里查找和下载所需的依赖文件。如果没有正确配置仓库，Gradle 将无法解析依赖，导致构建失败或异常缓慢。

一、Gradle 仓库类型

Gradle 支持三种类型仓库：Maven 仓库 、Ivy 仓库 、Flat Directory 仓库（本地目录），差异主要体现在依赖的存储格式和访问方式。需根据项目场景（如公开 / 私有依赖、本地 / 远程依赖）选择合适的类型。

1.1 Maven 仓库（最常用）

Maven 仓库是一种基于 Maven 依赖格式 的存储系统，它不仅存放编译好的二进制文件（如 JAR、AAR），还包含 项目对象模型（POM）元数据文件 （pom.xml），并以 groupId/artifactId/version 目录结构组织。

因其生态丰富（如 Maven Central、Google 仓库）、工具链支持完善成为 Java/Android 项目的 主流选择。根据使用场景，支持远程（公开 / 私有）和本地两种部署方式。

1.1.1 私有 / 自定义远程仓库

在实际项目中，我们经常需要使用 私有 Maven 仓库 （如 Nexus、Artifactory）管理内部依赖，或配置 自定义远程仓库（如阿里云 Maven 镜像、腾讯云镜像）加速 Maven 中央仓库依赖下载。

Maven 仓库 的配置在 repositories { ... } 代码块中进行声明，标准写法是使用 maven { url = uri("...") } 配置，通过 url 指定远程 Maven 仓库的地址，如：

kotlin 复制代码

repositories {
    // 阿里镜像（同步 Maven Central、Google 等仓库，国内访问更快）
    maven {
        url = uri("https://maven.aliyun.com/repository/public")
    }
    
    // 私有远程仓库
    maven {
        url = uri("http://repo.company.com/maven2") 
        // 认证配置（用户名/密码或令牌）
        credentials {
            username = "your-username"
            password = "your-password"
            // 若用令牌：
            // authToken = "your-token"
        }
    }
}

在国内网络环境下，直接访问 Maven Central 或 Google Maven 仓库可能会很慢甚至失败。为了解决这个问题，可以配置 国内镜像仓库 （如阿里云、腾讯云、华为云）加速依赖下载的速度，国内常用镜像仓库地址如下：

提供方	仓库地址	说明
阿里云	`https://maven.aliyun.com/repository/public`	同步 Maven Central、Google、JCenter 等
腾讯云	`https://mirrors.cloud.tencent.com/nexus/repository/maven-public/`	国内云厂商镜像
华为云	`https://repo.huaweicloud.com/repository/maven/`	华为云公共仓库
网易	`https://mirrors.163.com/maven/repository/maven-public/`	网易开源镜像站

1.1.2 公共远程仓库

对于全球公开的主流仓库（如 Maven 中央仓库，Google 仓库），Gradle 提供了内置的速记符，配置时无需手动指定 URL，直接调用即可：

kotlin 复制代码

repositories {
    // 1. Maven 中央仓库（最常用，包含绝大多数开源依赖）
    mavenCentral()
    // 2. Google 仓库（Android 项目必备）
    google()
    // 3. 已弃用
    jcenter()
}

⚠️ 注意：JCenter 已停止更新，继续使用可能导致依赖下载失败或引入不安全的旧版本，建议旧项目逐步迁移至 Maven Central。

1.1.3 本地 Maven 仓库

本地 Maven 仓库是 Maven 在 本地磁盘上的缓存目录 （默认路径 ~/.m2/repository），用于存储项目依赖的 Jar 包、Maven 插件，以及本地项目打包后生成的构件（如 Jar/War 包），避免重复从远程仓库下载依赖。

Gradle 可以通过配置 mavenLocal() 启用本地 Maven 仓库，复用 Maven 本地仓库的依赖，适合本地开发测试：

kotlin 复制代码

repositories {
    // 1. 优先从本地 Maven 仓库（~/.m2/repository）查找依赖
    mavenLocal() 
    // 2. 若本地 Maven 仓库无对应依赖，从 Maven Central 远程仓库下载
    mavenCentral() 
}

Gradle 会按以下优先级顺序确定本地 Maven 仓库的路径（优先级从高到低）：

通过命令行参数指定 -Dmaven.repo.local=/path/to/custom/repo
~/.m2/settings.xml 中 <localRepository> 配置的路径
$M2_HOME/conf/settings.xml 中 <localRepository> 配置的路径（需配置 M2_HOME 环境变量）
默认路径 ~/.m2/repository

⚠️ 注意事项：

mavenLocal() 仅读取 Maven 本地缓存，若本地 .m2 无依赖，Gradle 将从远程仓库下载依赖存入自身缓存（~/.gradle/caches），而非写入 .m2 目录

除非需要复用 Maven 本地构建的依赖，否则无需启用（Gradle 自有缓存效率更高）。

1.2 Ivy 仓库

Ivy 仓库是基于 Apache Ivy 依赖格式（包含 ivy.xml 元数据文件）的仓库，通过 ivy {url = uri("...")} 配置：

kotlin 复制代码

repositories {
    ivy {
        url 'https://ivy.example.com/repo'
    }
}

还可以自定义 Ivy 仓库的目录布局（如兼容 Maven 布局）：

groovy 复制代码

repositories {
    // 示例 1：使用 Maven 布局（符合 groupId/artifactId/version 结构）
    ivy {
        url = uri("http://your-ivy-server/repo/")
        layout = "maven"  // 启用 Maven 兼容布局
    }
    
    // 示例 2：自定义路径模式
    ivy {
        url = uri("https://ivy.example.com/repo")
        layout("pattern") {
            artifact("[module]/[revision]/[artifact]-[revision].[ext]")  // 构件路径模式
            ivy("[module]/[revision]/ivy-[revision].xml")  // 元数据文件路径模式
        }
    }
}

⚠️ 注意：布局配置需与仓库实际目录结构严格匹配，否则会导致依赖找不到。

1.3 Flat Directory 仓库

Flat Directory 仓库是最简单的本地仓库形式，本质是本地文件系统的目录，依赖直接以文件形式存放（没有元数据文件，如 pom.xml 或 ivy.xml），适合临时存放本地 Jar 包。

Gradle 通过 repositories 块中的 flatDir { dirs(...) } 配置本地目录，支持同时指定多个路径（相对路径或绝对路径）：

kotlin 复制代码

repositories {
    // 1. 项目根目录下的 libs 文件夹
    flatDir {
        dirs("libs")
    }

    // 2. 指定多个目录（相对路径 + 绝对路径）
    flatDir {
        dirs(
            "libs",
            "app/libs",
            "/Users/xxx/local-jars"
        )
    }
}

💡 路径说明：

相对路径 ：相对于当前 build.gradle.kts 文件所在模块的目录

绝对路径：直接指向磁盘上的具体位置

由于 Flat Directory 仓库无元数据文件，Gradle 无法自动识别依赖信息，因此需 显式指定 Jar 包完整路径（不含 .jar 后缀）：

groovy 复制代码

dependencies {
    // 引入 libs 目录下的 my-sdk-1.0.jar
    implementation(files("libs/my-sdk-1.0.jar"))

    // 引入 libs 目录下的 utils.jar（无版本号）
    implementation(files("libs/utils.jar"))
}

二、仓库优先级规则

Gradle 允许在 repositories 中声明多个仓库，可根据依赖来源（本地 / 私有 / 公共）灵活组合配置：

kotlin 复制代码

repositories {
    mavenLocal() // 1. 本地 Maven 库
    flatDir { dirs("libs") } // 2. 项目内 Jar 库
    maven { url = uri("https://repo.mycompany.com/internal") } // 3. 私有库
    mavenCentral() // 4. 公共库
}

在多仓库配置中，声明顺序 = 依赖搜索顺序 ，Gradle 解析依赖时，会 按仓库的声明顺序遍历仓库 ，一旦在某仓库找到第一个匹配的依赖后，Gradle 会强制从该仓库下载 所有构件（如 jar、sources.jar） ，即使后续仓库有更完整的资源（如包含缺失的源码包），也不会切换仓库；若遍历所有仓库后，仍未找到匹配的依赖，Gradle 会抛出 Could not find xxx 异常，终止构建。

因此建议：

按「依赖命中率从高到低」排序
公共仓库在前，私有仓库在后（避免私有仓库缓存影响公共依赖获取）

⚠️ 注意：这和 Maven 不同，Maven 会并行查找所有仓库并选择 "最近" 的版本，而 Gradle 是 串行顺序查找。

三、私有仓库安全认证

在使用 Gradle 配置私有仓库时，为确保依赖拉取的安全性和权限控制，需要在 credentials 块中定义访问私有仓库所需的身份凭证，基础配置结构如下：

kotlin 复制代码

repositories {
    maven {
        // 私有仓库地址，必须使用HTTPS协议以确保传输安全
        url = uri("https://repo.company.com/maven-private")
        
        // 配置认证信息，用于向私有仓库证明身份的凭证配置块
        credentials(Class<? extends Credentials> credentialsType) {
            // 具体认证参数（根据仓库要求填写，如用户名、密码、Token等）
        }
    }
}

credentials（凭证配置块）是用于存储和提供「认证信息」的核心组件，它的作用是告诉 Gradle："用这些信息向仓库证明我的身份"。

Gradle 提供了多种 credentials 实现，对应不同的认证场景：

类型	核心作用	使用场景
`PasswordCredentials`	支持用户名 + 密码的凭证类，对应「Basic Auth」认证方式。	传统私有仓库（如 Nexus 基础版、Artifactory 旧版）。
`HttpHeaderCredentials`	支持自定义 HTTP 头的凭证类，用于传递 Token（如 `Bearer Token`）等认证信息。	现代仓库（如 GitHub Packages、GitLab Packages）、需要 Token 认证的场景。
`AwsCredentials`	专门为 AWS 服务（如 AWS CodeArtifact 私有仓库）设计的凭证类。	与 AWS 云原生仓库交互，自动适配 AWS 凭证链（环境变量、IAM 角色等）。

3.1 用户名 / 密码认证

PasswordCredentials 是 Gradle 默认的凭证类型，适用于支持 Basic Auth 的私有仓库。配置时直接在 credentials 块中声明用户名（username）和密码（ password）即可，但需注意 禁止明文存储（后文详解）。

groovy 复制代码

repositories {
    maven {
        // 私有仓库地址（强制使用 HTTPS）
        url = uri("https://repo.company.com/maven-private")
        
        // 配置认证信息
        // 等效于 credentials(PasswordCredentials)，PasswordCredentials 为默认类型，无需显式声明
        credentials {
            username = "repo.username"
            password = "repo.password"
        }
    }
}

3.2 Token/Bearer 认证

HttpHeaderCredentials 适用于支持「HTTP 头认证」的现代仓库（如 GitLab Packages、Artifactory 新版），配合 Authentication API，通过自定义 HTTP 头（如 Authorization: Bearer <Token>）传递认证信息。相比密码，Token 可设置过期时间和权限范围，安全性优于密码。

kotlin 复制代码

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/your-org/your-repo") // 示例：GitHub Packages
        
        // 配置 HTTP 头凭证（Bearer Token）
        credentials(HttpHeaderCredentials::class) {
            name = "Authorization" // 固定头名称
            value = "Bearer ${System.getenv("REPO_TOKEN")}" // 从环境变量加载 Token
        }
        
        // 必须声明认证方式（与 HttpHeaderCredentials 配对）
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}

✅ Token 建议设置为「只读权限」，并定期轮换（如每 30 天），降低泄露风险。

四、敏感信息存储方案

配置私有仓库时，明文存储用户名/密码、Token 等敏感信息是高危操作 （如直接写在 build.gradle.kts 中），可能导致信息泄露。所有认证信息必须通过「间接引用」方式加载，需根据环境（本地开发 / CI / 生产）选择安全的存储方式，核心原则：「凭证与代码分离」。

本地开发环境：通过 gradle.properties 存储（非版本控制文件）
CI/CD 环境：通过环境变量注入
生产环境：结合 Gradle 加密机制或第三方凭据管理工具

4.1 使用 gradle.properties（本地开发）

本地开发时，将凭证存储在项目根目录的 gradle.properties 中（该文件需加入 .gitignore，避免提交）：

在项目根目录创建 / 编辑 gradle.properties，在文件中定义认证信息：

properties 复制代码

# gradle.properties（仅本地可见，不提交到 Git）
repo.username=dev_user_01
repo.password=xxxx-xxxx-xxxx（建议使用复杂密码）
repo.token=your_personal_access_token

在 .gitignore 中添加规则，确保 gradle.properties 不被提交到 Git 仓库：

txt 复制代码

# .gitignore
# 排除项目级 gradle.properties（保留全局配置）
gradle.properties
!gradle/wrapper/gradle-wrapper.properties

在 Kotlin 脚本中读取通过 project.findProperty() 读取配置：

kotlin 复制代码

repositories {
    maven {
        url = uri("https://repo.company.com/maven-private")
        credentials {
            username = project.findProperty("repo.username") as String?
            password = project.findProperty("repo.password") as String?
        }
    }
}

4.2 使用环境变量（CI/CD 环境）

在 Jenkins、GitHub Actions 等 CI 环境中，通过环境变量存储敏感信息（平台通常提供「加密存储」功能，仅在运行时注入）。

在 CI 平台中配置环境变量：
- 键：REPO_USERNAME、REPO_PASSWORD
- 值：对应私有仓库的用户名和密码

在 build.gradle 中读取环境变量：

groovy 复制代码

repositories {
    maven {
        url = uri("https://repo.company.com/maven-internal")
        credentials {
            username = System.getenv("REPO_USERNAME")
            password = System.getenv("REPO_TOKEN")
        }
    }
}

五、强制使用 HTTPS 协议

依赖传输过程中，使用 isAllowInsecureProtocol 强制使用 HTTPS 协议，防止中间人攻击（MITM）导致凭证泄露或依赖被篡改。即使是内部仓库，也不应使用 HTTP（内部网络仍可能存在嗅探风险）：

kotlin 复制代码

repositories {
    maven {
        url = uri("https://repo.company.com/maven-private")  // 强制 HTTPS
        isAllowInsecureProtocol = false  // 显式禁止 HTTP（默认值为 false，建议声明）
    }
}

⚠️ 注意：若需临时使用 HTTP（如内部老旧仓库），必须限制在隔离网络，并通过 isAllowInsecureProtocol = true 临时开启（同时标注过期时间，尽快迁移至 HTTPS）。