声明存储库 - Gradle 中文

可以通过调用 RepositoryHandler API 上提供的相应方法，将具有自定义 URL 的存储库指定为 Maven 或 Ivy 存储库。Gradle 支持除 http 或 https 之外的其他协议作为自定义 URL 的一部分，例如 file、sftp 或 s3。有关完整覆盖范围，请参阅支持的存储库类型部分。

您还可以定义您自己的存储库布局，方法是使用 ivy { } 存储库，因为它们在模块在存储库中的组织方式方面非常灵活。

声明多个存储库

您可以定义多个存储库来解析依赖项。如果某些依赖项仅在一个存储库中可用而不在另一个存储库中可用，则声明多个存储库非常有用。您可以混合参考部分中描述的任何类型的存储库。

此示例演示如何为项目声明各种命名和自定义 URL 存储库

示例 3. 声明多个存储库

build.gradle.kts

repositories {
    mavenCentral()
    maven {
        url = uri("https://repo.spring.io/release")
    }
    maven {
        url = uri("https://repository.jboss.org/maven2")
    }
}

build.gradle

repositories {
    mavenCentral()
    maven {
        url "https://repo.spring.io/release"
    }
    maven {
        url "https://repository.jboss.org/maven2"
    }
}

声明的顺序决定了 Gradle 在运行时如何检查依赖项。如果 Gradle 在特定存储库中找到模块描述符，它将尝试从同一存储库下载该模块的所有工件。您可以详细了解依赖项下载的内部工作原理。

严格限制声明的存储库

Maven POM 元数据可以引用其他存储库。Gradle 将忽略这些存储库，它只使用构建本身中声明的存储库。

这是一个可重现的安全保障，也是一种安全保护。如果没有它，依赖项的更新版本可能会从任何地方将工件拉入您的构建中。

支持的存储库类型

Gradle 支持各种依赖项源，无论是格式还是连接性方面。您可以从以下内容解析依赖项

不同格式
- 一个与 Maven 兼容的工件存储库（例如：Maven Central）
- 一个与 Ivy 兼容的工件存储库（包括自定义布局）
- 本地（平面）目录
具有不同连接性的
- 经过身份验证的存储库
- 各种远程协议，例如 HTTPS、SFTP、AWS S3 和 Google Cloud Storage

平面目录存储库

一些项目可能更愿意将依赖项存储在共享驱动器上或作为项目源代码的一部分，而不是二进制存储库产品。如果您想使用（平面）文件系统目录作为存储库，只需键入

示例 4. 平面存储库解析器

build.gradle.kts

repositories {
    flatDir {
        dirs("lib")
    }
    flatDir {
        dirs("lib1", "lib2")
    }
}

build.gradle

repositories {
    flatDir {
        dirs 'lib'
    }
    flatDir {
        dirs 'lib1', 'lib2'
    }
}

这会添加一些存储库，它们会查找一个或多个目录以查找依赖项。

此类型的存储库不支持任何元数据格式，如 Ivy XML 或 Maven POM 文件。相反，Gradle 将根据工件的存在动态生成一个模块描述符（没有任何依赖项信息）。

由于 Gradle 更喜欢使用描述符是从真实元数据创建而不是生成的模块，因此平面目录存储库不能用于覆盖其他存储库中具有真实元数据的工件，这些存储库在构建中声明。

例如，如果 Gradle 仅在平面目录存储库中找到 jmxri-1.2.1.jar，但在支持元数据的另一个存储库中找到 jmxri-1.2.1.pom，它将使用第二个存储库来提供模块。

对于使用本地工件覆盖远程工件的用例，请考虑使用 Ivy 或 Maven 存储库，其 URL 指向本地目录。

如果您仅使用平面目录存储库，则无需设置依赖项的所有属性。

本地存储库

以下部分描述了存储库格式，Maven 或 Ivy。这些可以声明为本地存储库，使用本地文件系统路径来访问它们。

与平面目录存储库的不同之处在于，它们尊重格式并包含元数据。

配置此类存储库时，Gradle 会完全绕过其依赖项缓存，因为无法保证内容在执行之间不会更改。由于此限制，它们可能会对性能产生影响。

它们还使构建可重复性变得更加难以实现，并且其使用应仅限于修补或原型制作。

Maven 存储库

许多组织将依赖项托管在公司网络内只能访问的内部 Maven 存储库中。Gradle 可以通过 URL 声明 Maven 存储库。

要添加自定义 Maven 存储库，您可以执行

示例 5. 添加自定义 Maven 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }
}

设置复合 Maven 存储库

有时，存储库会将 POM 发布到一个位置，并将 JAR 和其他工件发布到另一个位置。要定义这样的存储库，您可以执行

示例 6. 添加用于 JAR 文件的其他 Maven 存储库

build.gradle.kts

repositories {
    maven {
        // Look for POMs and artifacts, such as JARs, here
        url = uri("http://repo2.mycompany.com/maven2")
        // Look for artifacts here if not found at the above location
        artifactUrls("http://repo.mycompany.com/jars")
        artifactUrls("http://repo.mycompany.com/jars2")
    }
}

build.gradle

repositories {
    maven {
        // Look for POMs and artifacts, such as JARs, here
        url "http://repo2.mycompany.com/maven2"
        // Look for artifacts here if not found at the above location
        artifactUrls "http://repo.mycompany.com/jars"
        artifactUrls "http://repo.mycompany.com/jars2"
    }
}

Gradle 将查看 POM 和 JAR 的基本 url 位置。如果在那里找不到 JAR，则会使用额外的 artifactUrls 来查找 JAR。

访问经过身份验证的 Maven 存储库

您可以为受不同类型身份验证保护的 Maven 存储库指定凭据。

有关身份验证选项，请参阅支持的存储库传输协议。

本地 Maven 存储库

Gradle 可以使用本地 Maven 存储库中提供的依赖项。对于使用一个项目发布到本地 Maven 存储库，并使用另一个项目通过 Gradle 使用工件的团队来说，声明此存储库是有益的。

Gradle 将解析的依赖项存储在其自己的缓存中。即使您从基于 Maven 的远程存储库解析依赖项，构建也不需要声明本地 Maven 存储库。

在将 Maven 本地存储库添加为存储库之前，您应该确保确实需要。

要将本地 Maven 缓存声明为存储库，请将其添加到您的构建脚本中

示例 7. 将本地 Maven 缓存添加为存储库

build.gradle.kts

repositories {
    mavenLocal()
}

build.gradle

repositories {
    mavenLocal()
}

Gradle 使用与 Maven 相同的逻辑来识别本地 Maven 缓存的位置。如果在 settings.xml 中定义了本地存储库位置，则将使用此位置。<当前用户主目录>/.m2 中的 settings.xml 优先于 M2_HOME/conf 中的 settings.xml。如果没有可用的 settings.xml，Gradle 将使用默认位置 <当前用户主目录>/.m2/repository。

mavenLocal() 的情况

作为一般建议，您应该避免将 mavenLocal() 添加为存储库。使用 mavenLocal() 有不同的问题，您应该了解这些问题

Maven 将其用作缓存，而不是存储库，这意味着它可能包含部分模块。
- 例如，如果 Maven 从未下载给定模块的源代码或 javadoc 文件，Gradle 也找不到它们，因为它在找到模块后在单个存储库中搜索文件。
作为本地存储库，Gradle 不信任其内容，因为
- 工件的来源无法追踪，这是一个正确性和安全问题
- 工件可以被轻易覆盖，这是一个安全、正确和可复制的问题
为了减轻元数据和/或工件可以更改的事实，Gradle 不执行任何缓存，用于本地存储库
- 因此，您的构建速度较慢
- 鉴于存储库的顺序很重要，添加 mavenLocal() 首先意味着您的所有构建都会变慢

在少数情况下，您可能需要使用 mavenLocal()

用于与 Maven 的互操作性
- 例如，项目 A 是使用 Maven 构建的，项目 B 是使用 Gradle 构建的，并且您需要在开发期间共享工件
- 始终优先使用内部全功能存储库
- 如果无法使用，则应仅限于本地构建
为了与 Gradle 本身实现互操作性
- 在多存储库环境中，您需要检查项目 A 的更改是否适用于项目 B
- 对于此用例，优先使用复合构建
- 如果由于某种原因无法使用复合构建或全功能存储库，则 mavenLocal() 是最后的手段

在所有这些警告之后，如果您最终使用 mavenLocal()，请考虑将其与存储库过滤器结合使用。这将确保它仅提供预期内容，而不会提供其他内容。

Ivy 存储库

组织可能会决定在内部 Ivy 存储库中托管依赖项。Gradle 可以通过 URL 声明 Ivy 存储库。

定义具有标准布局的 Ivy 存储库

要使用标准布局声明 Ivy 存储库，无需其他自定义。您只需声明 URL 即可。

示例 8. Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
    }
}

为 Ivy 存储库定义命名布局

您可以通过使用命名布局指定您的存储库符合 Ivy 或 Maven 默认布局。

示例 9. 具有命名布局的 Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        layout("maven")
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "maven"
    }
}

有效的命名布局值为 'gradle'（默认值）、'maven' 和 'ivy'。有关这些命名布局的详细信息，请参阅 API 文档中的IvyArtifactRepository.layout(java.lang.String)。

为 Ivy 存储库定义自定义模式布局

要定义具有非标准布局的 Ivy 存储库，您可以为存储库定义模式布局

示例 10. 具有模式布局的 Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        patternLayout {
            artifact("[module]/[revision]/[type]/[artifact].[ext]")
        }
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        patternLayout {
            artifact "[module]/[revision]/[type]/[artifact].[ext]"
        }
    }
}

要定义从不同位置获取 Ivy 文件和工件的 Ivy 存储库，您可以定义用于查找 Ivy 文件和工件的单独模式

为存储库指定的每个 artifact 或 ivy 都会添加一个用于的其他模式。模式按定义的顺序使用。

示例 11. 具有多个自定义模式的 Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        patternLayout {
            artifact("3rd-party-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]")
            artifact("company-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]")
            ivy("ivy-files/[organisation]/[module]/[revision]/ivy.xml")
        }
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        patternLayout {
            artifact "3rd-party-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            artifact "company-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            ivy "ivy-files/[organisation]/[module]/[revision]/ivy.xml"
        }
    }
}

可选地，模式布局的存储库可以采用 Maven 样式来布局其'organisation'部分，用正斜杠替换句点作为分隔符。例如，组织my.company将表示为my/company。

示例 12. 具有 Maven 兼容布局的 Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        patternLayout {
            artifact("[organisation]/[module]/[revision]/[artifact]-[revision].[ext]")
            setM2compatible(true)
        }
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        patternLayout {
            artifact "[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            m2compatible = true
        }
    }
}

访问经过身份验证的 Ivy 存储库

您可以为受基本身份验证保护的 Ivy 存储库指定凭据。

示例 13. 具有身份验证的 Ivy 存储库

build.gradle.kts

repositories {
    ivy {
        url = uri("http://repo.mycompany.com")
        credentials {
            username = "user"
            password = "password"
        }
    }
}

build.gradle

repositories {
    ivy {
        url "http://repo.mycompany.com"
        credentials {
            username "user"
            password "password"
        }
    }
}

有关身份验证选项，请参阅支持的存储库传输协议。

存储库内容过滤

Gradle 公开了一个 API 来声明存储库可能包含或不包含的内容。它有不同的用例

性能，当您知道在特定存储库中永远找不到依赖项时
安全性，通过避免泄露私有项目中使用的依赖项
可靠性，当某些存储库包含损坏的元数据或工件时

在考虑声明的存储库顺序很重要时，这一点就更为重要。

声明存储库过滤器

示例 14. 声明存储库内容

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        content {
            // this repository *only* contains artifacts with group "my.company"
            includeGroup("my.company")
        }
    }
    mavenCentral {
        content {
            // this repository contains everything BUT artifacts with group starting with "my.company"
            excludeGroupByRegex("my\\.company.*")
        }
    }
}

build.gradle

repositories {
    maven {
        url "https://repo.mycompany.com/maven2"
        content {
            // this repository *only* contains artifacts with group "my.company"
            includeGroup "my.company"
        }
    }
    mavenCentral {
        content {
            // this repository contains everything BUT artifacts with group starting with "my.company"
            excludeGroupByRegex "my\\.company.*"
        }
    }
}

默认情况下，存储库包含所有内容，不排除任何内容

如果您声明包含，则它将排除所有内容但包含的内容。
如果您声明排除，则它将包含所有内容但排除的内容。
如果您声明包含和排除，则它仅包含明确包含且未排除的内容。

可以通过明确的组、模块或版本过滤，也可以严格过滤或使用正则表达式过滤。使用严格版本时，可以使用版本范围，使用 Gradle 支持的格式。此外，还有按解析上下文过滤的选项：配置名称甚至配置属性。有关详细信息，请参阅 RepositoryContentDescriptor。

声明仅在一个存储库中找到的内容

使用存储库级内容过滤器声明的过滤器不是排他的。这意味着声明一个存储库包含一个构件并不意味着其他存储库也不能拥有它：您必须在扩展中声明每个存储库包含的内容。

或者，Gradle 提供了一个 API，允许您声明一个存储库专门包含一个构件。如果您这样做

在存储库中声明的构件不能在任何其他存储库中找到
独占存储库内容必须在扩展中声明（就像存储库级内容一样）

示例 15. 声明独占存储库内容

build.gradle.kts

repositories {
    // This repository will _not_ be searched for artifacts in my.company
    // despite being declared first
    mavenCentral()
    exclusiveContent {
        forRepository {
            maven {
                url = uri("https://repo.mycompany.com/maven2")
            }
        }
        filter {
            // this repository *only* contains artifacts with group "my.company"
            includeGroup("my.company")
        }
    }
}

build.gradle

repositories {
    // This repository will _not_ be searched for artifacts in my.company
    // despite being declared first
    mavenCentral()
    exclusiveContent {
        forRepository {
            maven {
                url "https://repo.mycompany.com/maven2"
            }
        }
        filter {
            // this repository *only* contains artifacts with group "my.company"
            includeGroup "my.company"
        }
    }
}

可以按显式组、模块或版本进行过滤，也可以严格过滤或使用正则表达式。有关详细信息，请参阅 InclusiveRepositoryContentDescriptor。

如果您在 settings.gradle(.kts) 的 pluginManagement 部分中利用独占内容过滤，则通过项目 buildscript.repositories 添加更多存储库将是非法的。在这种情况下，构建配置将失败。

您的选择是：在设置中声明所有存储库或使用非独占内容过滤。

Maven 存储库过滤

对于 Maven 存储库，通常情况下，一个存储库要么包含发行版，要么包含快照。Gradle 允许您使用此 DSL 声明在存储库中找到哪种类型的构件

示例 16. 拆分快照和发行版

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.mycompany.com/releases")
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        url = uri("https://repo.mycompany.com/snapshots")
        mavenContent {
            snapshotsOnly()
        }
    }
}

build.gradle

repositories {
    maven {
        url "https://repo.mycompany.com/releases"
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        url "https://repo.mycompany.com/snapshots"
        mavenContent {
            snapshotsOnly()
        }
    }
}

支持的元数据源

在存储库中搜索模块时，Gradle 默认情况下会检查该存储库中受支持的元数据文件格式。在 Maven 存储库中，Gradle 会查找 .pom 文件，在 ivy 存储库中，它会查找 ivy.xml 文件，在平面目录存储库中，它会直接查找 .jar 文件，因为它不期望任何元数据。从 5.0 版开始，Gradle 还会查找 .module（Gradle 模块元数据）文件。

但是，如果你定义了一个自定义存储库，你可能需要配置此行为。例如，你可以定义一个没有 .pom 文件但只有 jar 的 Maven 存储库。为此，你可以为任何存储库配置元数据源。

示例 17. 支持无元数据工件的 Maven 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}

你可以指定多个源，以告诉 Gradle 在未找到文件时继续查找。在这种情况下，检查源的顺序是预定义的。

支持以下元数据源

表 1. 受支持的元数据源
元数据源	说明	顺序	Maven	Ivy/平面目录
`gradleMetadata()`	查找 Gradle `.module` 文件	第 1 位	是	是
`mavenPom()`	查找 Maven `.pom` 文件	第 2 位	是	是
`ivyDescriptor()`	查找 `ivy.xml` 文件	第 2 位	否	是
`artifact()`	直接查找工件	第 3 位	是	是

Ivy 和 Maven 存储库的默认设置在 Gradle 6.0 中发生更改。在 6.0 之前，artifact() 包含在默认设置中。当模块完全缺失时，会导致一些低效率。

例如，要恢复此行为，对于 Maven 中央，你可以使用

mavenCentral { metadataSources { mavenPom(); artifact() } }

以类似的方式，你可以在较旧的 Gradle 版本中使用以下内容选择新行为

mavenCentral { metadataSources { mavenPom() } }

从 Gradle 5.3 开始，在解析元数据文件（无论是 Ivy 还是 Maven）时，Gradle 会查找一个标记，指示存在匹配的 Gradle 模块元数据文件。如果找到，它将被用作 Ivy 或 Maven 文件。

从 Gradle 5.6 开始，你可以通过将 ignoreGradleMetadataRedirection() 添加到 metadataSources 声明中来禁用此行为。

示例 18. 不使用 gradle 元数据重定向的 Maven 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}

插件存储库与构建存储库

Gradle 会在构建期间的两个不同阶段使用存储库。

第一个阶段是配置构建和加载应用的插件时。

第二个阶段是在依赖项解析期间。此时，Gradle 会使用项目中声明的存储库，如前几部分所示。

插件存储库

默认情况下，Gradle 会使用 Gradle 插件门户来查找插件。

但是，出于不同的原因，其他公开或非公开存储库中也提供插件。当构建需要其中一个插件时，需要指定其他存储库，以便 Gradle 知道在哪里搜索。

由于声明存储库的方式和预期存储库包含的内容取决于应用插件的方式，因此最好参考自定义插件存储库。

集中存储库声明

Gradle 提供了一种方式，可以将存储库集中在一个位置声明给所有项目，而不是在构建的每个子项目中或通过 allprojects 块声明存储库。

集中声明存储库是一项孵化功能。

每个子项目中按惯例使用的存储库可以在 settings.gradle(.kts) 文件中声明

示例 19. 在设置中声明 Maven 存储库

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

dependencyResolutionManagement 存储库块接受与项目中相同的符号。其中包括 Maven 或 Ivy 存储库，无论是否使用凭据等。

默认情况下，项目在 build.gradle(.kts) 中声明的存储库将覆盖在 settings.gradle(.kts) 中声明的任何内容

示例 20. 优先使用项目存储库

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_PROJECT
}

settings.gradle

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_PROJECT
}

依赖项解析管理有三种模式

模式说明默认值？用例

模式	说明	默认值？	用例
`PREFER_PROJECT`	项目中声明的任何存储库都会导致项目使用项目声明的存储库，而忽略在设置中声明的存储库。	是	当团队需要使用子项目之间不常见的不同存储库时很有用。
`PREFER_SETTINGS`	直接或通过插件在项目中直接声明的任何存储库都将被忽略。	否	可用于强制大型团队仅使用已批准的存储库，但当项目或插件声明存储库时，不会导致构建失败。
`FAIL_ON_PROJECT_REPOS`	直接在项目中声明的任何存储库（直接或通过插件）都会触发构建错误。	否	可用于强制大型团队仅使用已批准的存储库。

PREFER_PROJECT

项目中声明的任何存储库都会导致项目使用项目声明的存储库，而忽略在设置中声明的存储库。

是

当团队需要使用子项目之间不常见的不同存储库时很有用。

PREFER_SETTINGS

直接或通过插件在项目中直接声明的任何存储库都将被忽略。

否

可用于强制大型团队仅使用已批准的存储库，但当项目或插件声明存储库时，不会导致构建失败。

FAIL_ON_PROJECT_REPOS

直接在项目中声明的任何存储库（直接或通过插件）都会触发构建错误。

否

可用于强制大型团队仅使用已批准的存储库。

您可以使用 repositoriesMode 更改行为，以优先使用 settings.gradle(.kts) 文件中的存储库

示例 21. 优先使用设置存储库

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_SETTINGS
}

settings.gradle

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_SETTINGS
}

如果项目或插件在项目中声明存储库，Gradle 会向您发出警告。

如果您想强制执行仅使用设置存储库，则可以强制 Gradle 使构建失败

示例 22. 强制使用设置存储库

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
}

settings.gradle

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
}

支持的存储库传输协议

Maven 和 Ivy 存储库支持使用各种传输协议。目前支持以下协议

表 2. 存储库传输协议
类型	凭据类型	链接
`file`	无
`http`	用户名/密码	文档
`https`	用户名/密码	文档
`sftp`	用户名/密码	文档
`s3`	访问密钥/秘密密钥/会话令牌或环境变量	文档
`gcs`	默认应用程序凭据，源自众所周知的文件、环境变量等。	文档

用户名和密码绝不应作为构建文件的一部分以纯文本形式检入版本控制中。您可以将凭据存储在本地 gradle.properties 文件中，并使用开源 Gradle 插件之一对凭据进行加密和使用，例如 credentials 插件。

传输协议是存储库 URL 定义的一部分。以下构建脚本演示如何创建基于 HTTP 的 Maven 和 Ivy 存储库

示例 23. 声明 Maven 和 Ivy 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
    }

    ivy {
        url = uri("http://repo.mycompany.com/repo")
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }

    ivy {
        url "http://repo.mycompany.com/repo"
    }
}

以下示例演示如何声明 SFTP 存储库

示例 24. 对存储库使用 SFTP 协议

build.gradle.kts

repositories {
    maven {
        url = uri("sftp://repo.mycompany.com:22/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }

    ivy {
        url = uri("sftp://repo.mycompany.com:22/repo")
        credentials {
            username = "user"
            password = "password"
        }
    }
}

build.gradle

repositories {
    maven {
        url "sftp://repo.mycompany.com:22/maven2"
        credentials {
            username "user"
            password "password"
        }
    }

    ivy {
        url "sftp://repo.mycompany.com:22/repo"
        credentials {
            username "user"
            password "password"
        }
    }
}

有关 HTTP 相关身份验证的详细信息，请参阅部分 HTTP(S) 身份验证方案配置。

使用 AWS S3 支持的存储库时，您需要使用 AwsCredentials 进行身份验证，提供访问密钥和私钥。以下示例展示了如何声明 S3 支持的存储库并提供 AWS 凭证

示例 25. 声明 S3 支持的 Maven 和 Ivy 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("s3://myCompanyBucket/maven2")
        credentials(AwsCredentials::class) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }

    ivy {
        url = uri("s3://myCompanyBucket/ivyrepo")
        credentials(AwsCredentials::class) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }
}

build.gradle

repositories {
    maven {
        url "s3://myCompanyBucket/maven2"
        credentials(AwsCredentials) {
            accessKey "someKey"
            secretKey "someSecret"
            // optional
            sessionToken "someSTSToken"
        }
    }

    ivy {
        url "s3://myCompanyBucket/ivyrepo"
        credentials(AwsCredentials) {
            accessKey "someKey"
            secretKey "someSecret"
            // optional
            sessionToken "someSTSToken"
        }
    }
}

您还可以使用 AwsImAuthentication 将所有凭证委托给 AWS SDK。以下示例展示了如何进行

示例 26. 使用 IAM 声明 S3 支持的 Maven 和 Ivy 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("s3://myCompanyBucket/maven2")
        authentication {
            create<AwsImAuthentication>("awsIm") // load from EC2 role or env var
        }
    }

    ivy {
        url = uri("s3://myCompanyBucket/ivyrepo")
        authentication {
            create<AwsImAuthentication>("awsIm")
        }
    }
}

build.gradle

repositories {
    maven {
        url "s3://myCompanyBucket/maven2"
        authentication {
           awsIm(AwsImAuthentication) // load from EC2 role or env var
        }
    }

    ivy {
        url "s3://myCompanyBucket/ivyrepo"
        authentication {
           awsIm(AwsImAuthentication)
        }
    }
}

有关 AWS S3 相关身份验证的详细信息，请参见部分 AWS S3 存储库配置。

使用 Google Cloud Storage 支持的存储库时，将使用默认应用程序凭证，无需进一步配置

示例 27. 使用默认应用程序凭证声明 Google Cloud Storage 支持的 Maven 和 Ivy 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("gcs://myCompanyBucket/maven2")
    }

    ivy {
        url = uri("gcs://myCompanyBucket/ivyrepo")
    }
}

build.gradle

repositories {
    maven {
        url "gcs://myCompanyBucket/maven2"
    }

    ivy {
        url "gcs://myCompanyBucket/ivyrepo"
    }
}

有关 Google GCS 相关身份验证的详细信息，请参见部分 Google Cloud Storage 存储库配置。

HTTP(S) 身份验证方案配置

使用 HTTP 或 HTTPS 传输协议配置存储库时，可以使用多种身份验证方案。默认情况下，Gradle 将尝试使用 Apache HttpClient 库支持的所有方案，在此处记录。在某些情况下，最好明确指定在与远程服务器交换凭证时应使用哪些身份验证方案。明确声明后，仅在对远程存储库进行身份验证时使用这些方案。

您可以使用 PasswordCredentials 为受基本身份验证保护的 Maven 存储库指定凭证。

示例 28. 访问受密码保护的 Maven 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
        credentials {
            username "user"
            password "password"
        }
    }
}

以下示例展示了如何配置存储库以仅使用 DigestAuthentication

示例 29. 配置存储库以仅使用摘要身份验证

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<DigestAuthentication>("digest")
        }
    }
}

build.gradle

repositories {
    maven {
        url 'https://repo.mycompany.com/maven2'
        credentials {
            username "user"
            password "password"
        }
        authentication {
            digest(DigestAuthentication)
        }
    }
}

当前支持的认证模式为

BasicAuthentication: HTTP 上的基本访问认证。使用此模式时，凭据会预先发送。
DigestAuthentication: HTTP 上的摘要访问认证。
HttpHeaderAuthentication: 基于任何自定义 HTTP 标头的认证，例如私有令牌、OAuth 令牌等。

使用抢先认证

Gradle 的默认行为是仅在服务器以 HTTP 401 响应的形式响应认证质询时才提交凭据。在某些情况下，服务器将响应不同的代码（例如，对于托管在 GitHub 上的存储库，将返回 404），导致依赖项解析失败。为了解决此行为，可以预先将凭据发送到服务器。要启用抢先认证，只需将存储库配置为显式使用 BasicAuthentication 模式

示例 30. 配置存储库以使用抢先认证

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<BasicAuthentication>("basic")
        }
    }
}

build.gradle

repositories {
    maven {
        url 'https://repo.mycompany.com/maven2'
        credentials {
            username "user"
            password "password"
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

使用 HTTP 标头认证

对于需要令牌、OAuth2 或基于其他 HTTP 标头的认证的安全 Maven 存储库，可以使用 HttpHeaderCredentials 和 HttpHeaderAuthentication 指定任何 HTTP 标头。

示例 31. 访问标头保护的 Maven 存储库

build.gradle.kts

repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}

build.gradle

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
        credentials(HttpHeaderCredentials) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

AWS S3 存储库配置

S3 配置属性

以下系统属性可用于配置与 s3 存储库的交互

org.gradle.s3.endpoint: 当使用非 AWS、S3 API 兼容的存储服务时，用于覆盖 AWS S3 端点。
org.gradle.s3.maxErrorRetry: 指定在 S3 服务器响应 HTTP 5xx 状态代码时重试请求的最大次数。未指定时，将使用默认值 3。

S3 URL 格式

S3 URL 为“虚拟主机样式”，必须采用以下格式

s3://<bucketName>[.<regionSpecificEndpoint>]/<s3Key>

例如：s3://myBucket.s3.eu-central-1.amazonaws.com/maven/release

myBucket 是 AWS S3 存储桶名称。
s3.eu-central-1.amazonaws.com 是可选区域特定端点。
/maven/release 是 AWS S3 密钥（存储桶内对象的唯一标识符）

S3 代理设置

可以使用以下系统属性为 S3 配置代理

https.proxyHost
https.proxyPort
https.proxyUser
https.proxyPassword
http.nonProxyHosts（注意：这不是错别字。）

如果 org.gradle.s3.endpoint 属性已使用 HTTP（而非 HTTPS）URI 指定，则可以使用以下系统代理设置

http.proxyHost
http.proxyPort
http.proxyUser
http.proxyPassword
http.nonProxyHosts

AWS S3 V4 签名 (AWS4-HMAC-SHA256)

某些 AWS S3 区域（eu-central-1 - 法兰克福）要求所有 HTTP 请求都按照 AWS 的签名版本 4 进行签名。建议在使用需要 V4 签名的存储桶时指定包含区域特定端点的 S3 URL。例如：

s3://somebucket.s3.eu-central-1.amazonaws.com/maven/release

如果未为需要 V4 签名的存储桶指定区域特定端点，则 Gradle 将使用默认 AWS 区域 (us-east-1)，并且控制台上会出现以下警告

Attempting to re-send the request to .... with AWS V4 authentication. To avoid this warning in the future, use region-specific endpoint to access buckets located in regions that require V4 signing.

未为需要 V4 签名的存储桶指定区域特定端点意味着

对于每次文件上传和下载，需要往返 AWS 三次，而不是一次。
根据位置 - 增加网络延迟和构建速度变慢。
传输失败的可能性增加。

AWS S3 跨账户访问

某些组织可能有多个 AWS 帐号，例如每个团队一个帐号。存储桶所有者的 AWS 帐号通常与构件发布者和使用者不同。存储桶所有者需要能够授予使用者访问权限，否则构件将只能由发布者的帐号使用。这可以通过向上传对象添加 bucket-owner-full-control 预设 ACL 来实现。Gradle 将在每次上传时执行此操作。确保发布者具有所需的 IAM 权限，PutObjectAcl（如果启用了存储桶版本控制，则为 PutObjectVersionAcl），直接或通过假定的 IAM 角色（取决于您的情况）。您可以在 AWS S3 访问权限中阅读更多信息。

Google Cloud Storage 存储库配置

GCS 配置属性

以下系统属性可用于配置与 Google Cloud Storage 存储库的交互

org.gradle.gcs.endpoint: 在使用非 Google Cloud Platform、与 Google Cloud Storage API 兼容的存储服务时，用于覆盖 Google Cloud Storage 端点。
org.gradle.gcs.servicePath: 用于覆盖 Google Cloud Storage 客户端构建请求的 Google Cloud Storage 根服务路径，默认为 /。

GCS URL 格式

Google Cloud Storage URL 为“虚拟托管样式”，必须采用以下格式 gcs://<bucketName>/<objectKey>

例如 gcs://myBucket/maven/release

myBucket 是 Google Cloud Storage 存储桶名称。
/maven/release 是 Google Cloud Storage 密钥（存储桶中对象的唯一标识符）

处理凭据

存储库凭据不应成为构建脚本的一部分，而应保留在外部。Gradle 提供构件存储库中的 API，允许您仅声明所需凭据的类型。凭据值在构建需要它们时从 Gradle 属性中查找。

例如，给定存储库配置

示例 32. 外部存储库凭据

build.gradle.kts

repositories {
    maven {
        name = "mySecureRepository"
        credentials(PasswordCredentials::class)
        // url = uri(<<some repository url>>)
    }
}

build.gradle

repositories {
    maven {
        name = 'mySecureRepository'
        credentials(PasswordCredentials)
        // url = uri(<<some repository url>>)
    }
}

用户名和密码将从 mySecureRepositoryUsername 和 mySecureRepositoryPassword 属性中查找。

请注意，配置属性前缀（标识）由存储库名称确定。然后，可以通过 Gradle 属性支持的任何方式提供凭据，包括 gradle.properties 文件、命令行参数、环境变量或这些选项的组合。

此外，请注意，仅当调用的构建需要凭据时才需要凭据。例如，如果某个项目配置为将工件发布到安全存储库，但构建未调用发布任务，Gradle 不会要求存在发布凭据。另一方面，如果构建需要执行在某个时间点需要凭据的任务，Gradle 将首先检查凭据是否存在，并且如果它知道构建将在稍后由于缺少凭据而失败，则不会开始运行任何任务。

这是一个可下载示例，更详细地演示了该概念。

仅支持对表 3 中列出的凭据进行查找。

表 3. 支持值查找的凭据及其对应的属性
类型	参数	基本属性名称	是否必需？
`PasswordCredentials`	`username`	`用户名`	必需
`PasswordCredentials`	`password`	`密码`	必需
`AwsCredentials`	`accessKey`	`访问密钥`	必需
	`secretKey`	`秘密密钥`	必需
	`sessionToken`	`会话令牌`	可选
`HttpHeaderCredentials`	`name`	`AuthHeaderName`	必需
`HttpHeaderCredentials`	`value`	`AuthHeaderValue`	必需

此页面有帮助吗？