Gradle 中 Maven 仓库配置

在 Java/Kotlin 项目的构建过程中，依赖管理 是核心环节之一，而 Maven 仓库 是最常见的依赖来源。无论是公共的 Maven Central，还是企业内部的私有仓库（如 Nexus、JFrog Artifactory），我们通常都需要在 Gradle 构建脚本中正确配置这些仓库，才能顺利拉取所需的依赖。

本文将带你深入理解 Gradle 中如何配置 Maven 仓库，包括：

• 基础配置：如何声明一个 Maven 仓库
• 常用配置项详解（url、credentials、content 等）
• content { } 块的完整配置方法一览（重点新增！）
• 高级技巧：依赖过滤、元数据控制、性能优化
• 常见问题与最佳实践

无论你是 Gradle 新手，还是有经验的构建工程师，相信本文都能帮你更好地掌控依赖来源，提升构建效率与安全性。

---

一、Gradle 仓库基础：什么是 repositories？

在 Gradle 中，repositories 是构建脚本 (build.gradle) 中的一个关键配置块，用于 声明项目依赖从哪些仓库获取。这些仓库可以是：

• 公共仓库：如 Maven Central、Google Maven 仓库
• 私有仓库：如公司搭建的 Nexus、JFrog Artifactory
• 本地仓库：如本地文件系统或 Maven 本地缓存 (~/.m2)

一个最基本的 Maven 仓库配置如下：

repositories {
    maven {
        url 'https://maven.example.com/repository/public/'
    }
}

上面配置告诉 Gradle："请从这个 URL 指定的 Maven 仓库查找依赖"。

---

二、Maven 仓库的常见配置项详解

在 repositories 块中，我们通常使用 maven { ... } 来声明一个 Maven 类型的仓库。它支持多个配置参数，下面是常用的配置项及其作用：

1. ✅ url（必需）

作用：指定 Maven 仓库的访问地址，可以是 HTTP 或 HTTPS。

maven {
    url 'https://maven.example.com/repo'
}

⚠️ 注意：Gradle 7 及以上版本 默认禁止使用不安全的 HTTP 协议 ，如果你的仓库是 http:// 开头，必须显式允许。

---

2. ✅ allowInsecureProtocol（如使用 HTTP 时必须）

作用 ：允许使用 http 等非加密协议访问仓库（不推荐，仅在必要时使用）。

maven {
    url 'http://maven.internal.com/repo'
    allowInsecureProtocol = true  // 必须显式允许
}

🔐 推荐始终使用 HTTPS，除非你明确信任该网络环境。

---

3. ✅ credentials（私有仓库认证）

作用：如果你的 Maven 仓库需要身份验证（比如公司私服），你需要提供用户名和密码（或 token）。

maven {
    url 'https://maven.example.com/private'
    credentials {
        username 'myUser'
        password 'myPassword'
    }
}

🔒 安全建议：不要将密码硬编码在脚本中！推荐使用：

• gradle.properties 文件（不提交到版本控制）
• 环境变量
• CI/CD 系统的 Secret 管理

---

4. ⚙️ metadataSources（控制元数据来源，高级用法）

作用 ：指定 Gradle 如何获取依赖的元数据（比如 pom 文件）。默认已经包含 mavenPom()，一般无需修改。

metadataSources {
    mavenPom()    // 从 pom.xml 获取元数据（默认包含）
    artifact()    // 从 artifact 推断（极少使用）
}

一般情况下你不需要动它，除非你有特殊仓库布局或元数据来源需求。

---

三、🔍 content { } 块：依赖模块过滤（重点！）

作用

content { } 是 maven 仓库配置中一个非常强大且实用的配置块，用于 声明该仓库中包含或排除哪些依赖模块，即：

告诉 Gradle：这个仓库中 只包含某些 groupId/module，或者要排除某些模块。

通过合理使用 content，你可以：

• ✅ 优化依赖解析性能，避免 Gradle 在多个仓库中查找同一个依赖
• ✅ 精准控制依赖来源，避免从错误的仓库拉取模块
• ✅ 避免依赖冲突，确保关键依赖来自你期望的仓库

---

✅ content { } 支持的配置方法一览

方法	作用	示例
includeGroup(String...)	包含某些 groupId 的依赖，只有这些 group 的依赖会从此仓库查找	includeGroup 'com.example'
includeGroupByRegex(String...)	使用正则表达式匹配一组 groupId，支持模糊匹配	includeGroupByRegex 'com\\.example\\..*'
includeModule(String group, String module)	包含某个具体的依赖模块（即 groupId + artifactId）	includeModule 'com.example', 'my-lib'
includeModules(String group, String... modules)	包含某个 groupId 下的多个 artifact 模块	includeModules 'com.example', 'lib1', 'lib2'
excludeGroup(String...)	排除某些 groupId，这些 group 的依赖不会从此仓库查找	excludeGroup 'com.internal'
excludeGroupByRegex(String...)	使用正则表达式排除一组 groupId	excludeGroupByRegex 'com\\.test\\..*'
excludeModule(String group, String module)	排除某个具体的依赖模块（groupId + artifactId）	excludeModule 'com.example', 'old-lib'

---

✅ 使用示例

示例 1：只包含某个 group 的依赖

content {
    includeGroup 'com.example'
}

👉 只有 com.example 开头的依赖会从此仓库查找。

示例 2：包含某个具体的模块

content {
    includeModule 'com.example', 'core-lib'
}

👉 只有 com.example:core-lib 会从此仓库解析。

示例 3：包含多个模块

content {
    includeModules 'com.example', 'core-lib', 'utils-lib', 'data-lib'
}

👉 只有这三个模块会从此仓库拉取。

示例 4：排除某个模块

content {
    includeGroup 'com.example'
    excludeModule 'com.example', 'deprecated-lib'
}

👉 com.example 的其他模块仍会从此仓库拉取，但 deprecated-lib 不会。

示例 5：使用正则表达式（高级）

content {
    includeGroupByRegex 'com\\.example\\..*'
    excludeGroupByRegex 'com\\.example\\.internal\\..*'
}

👉 匹配 com.example.xxx，但排除 com.example.internal.xxx。

---

四、完整的 Maven 仓库配置示例

下面是一个结合了常用配置（包括 content 过滤）的完整示例：

repositories {
    // Maven Central（默认仓库，通常无需配置）
    mavenCentral()

    // 公司私服 - Release 仓库
    maven {
        url 'https://maven.example.com/repository/maven-releases/'
        name 'CompanyReleases'
        credentials {
            username = project.findProperty('repoUser') ?: System.getenv('REPO_USER')
            password = project.findProperty('repoPassword') ?: System.getenv('REPO_PASSWORD')
        }
        content {
            includeGroup 'com.example'
            includeGroup 'org.shared'
            excludeModule 'com.example', 'old-lib'
        }
    }

    // 公司私服 - Snapshot 仓库
    maven {
        url 'https://maven.example.com/repository/maven-snapshots/'
        credentials {
            username = 'snapUser'
            password = 'snapPass123'
        }
        content {
            includeGroup 'com.example'
        }
    }

    // 某个使用 HTTP 的内部仓库（仅测试，允许不安全协议）
    maven {
        url 'http://maven.test.com/repo'
        allowInsecureProtocol = true
        content {
            includeGroup 'com.test'
        }
    }
}

---

五、常见问题与最佳实践

场景	推荐方案
使用私有仓库	一定要配置credentials，推荐从gradle.properties或环境变量读取
多仓库配置	使用content { includeGroup }明确每个仓库负责哪些依赖，提升解析效率与准确性
强制使用 HTTPS	避免使用http，如必须使用则设置allowInsecureProtocol = true
优化构建速度	不要将所有依赖都放在一个仓库中，按团队/模块合理划分，并用content过滤
避免依赖冲突	确保每个依赖来自预期仓库，避免多个仓库中存在同名不同版本

❌ 不推荐做法：

• 硬编码账号密码
• 使用 http 且不设置 allowInsecureProtocol
• 配置很多仓库但不使用 content 过滤
• 误用已废弃配置如 artifactUrls 或 mavenContent

---

六、总结

在 Gradle 项目中，正确配置 Maven 仓库是保证依赖能够被正确解析和下载的基础。本文重点介绍了：

• 如何声明一个 Maven 仓库（maven { url '...' }）

• 常用配置项：url、credentials、allowInsecureProtocol、content、metadataSources

• content { } 块的完整配置方法，包括：

  • includeGroup(String...)
  • includeGroupByRegex(String...)
  • includeModule(String group, String module)
  • includeModules(String group, String... modules)
  • excludeGroup(String...)
  • excludeGroupByRegex(String...)
  • excludeModule(String group, String module)

• 常见问题与最佳实践，助你提升构建效率与安全性

---

📌 相关阅读：

• Gradle 官方文档 - 声明仓库
• Maven 依赖管理机制