（二）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 仓库的地址，如：

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，直接调用即可：

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 本地仓库的依赖，适合本地开发测试：

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

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

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

⚠️ 注意事项：

• mavenLocal() 仅读取 Maven 本地缓存，若本地 .m2 无依赖，Gradle 将从远程仓库下载依赖存入自身缓存（~/.gradle/caches），而非写入 .m2 目录
• 除非需要复用 Maven 本地构建的依赖，否则无需启用（Gradle 自有缓存效率更高）。

1.2 Ivy 仓库

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

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

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

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(...) } 配置本地目录，支持同时指定多个路径（相对路径或绝对路径）：

repositories {// 1. 项目根目录下的 libs 文件夹flatDir {dirs("libs")}// 2. 指定多个目录（相对路径 + 绝对路径）flatDir {dirs("libs","app/libs","/Users/xxx/local-jars")}
}

💡 路径说明：

• 相对路径：相对于当前 build.gradle.kts 文件所在模块的目录
• 绝对路径：直接指向磁盘上的具体位置

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

dependencies {// 引入 libs 目录下的 my-sdk-1.0.jarimplementation(files("libs/my-sdk-1.0.jar"))// 引入 libs 目录下的 utils.jar（无版本号）implementation(files("libs/utils.jar"))
}

二、仓库优先级规则

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

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 块中定义访问私有仓库所需的身份凭证，基础配置结构如下：

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）即可，但需注意 禁止明文存储（后文详解）。

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 可设置过期时间和权限范围，安全性优于密码。

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，避免提交）：

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

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

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

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

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

   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 环境中，通过环境变量存储敏感信息（平台通常提供「加密存储」功能，仅在运行时注入）。

1. 在 CI 平台中配置环境变量：

   • 键：REPO_USERNAME、REPO_PASSWORD
   • 值：对应私有仓库的用户名和密码

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

   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（内部网络仍可能存在嗅探风险）：

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

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