声明存储库_Gradle中文网

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

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

声明多个存储库

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

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

Example 3. Declaring multiple repositories

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

平面目录存储库

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

Example 4. Flat repository resolver

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 存储库，您可以执行以下操作：

Example 5. Adding custom Maven repository

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 和其他工件发布到另一位置。要定义这样的存储库，您可以执行以下操作：

Example 6. Adding additional Maven repositories for JAR files

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 将查看urlPOM 和 JAR 的基本位置。如果在那里找不到 JAR，则artifactUrls使用额外的 JAR 来查找 JAR。

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

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

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

本地 Maven 存储库

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

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

在将 Maven local 添加为存储库之前，您应该确保这确实是必需的。

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

Example 7. Adding the local Maven cache as a repository

build.gradle.kts

repositories {
    mavenLocal()
}

build.gradle

repositories {
    mavenLocal()
}

Gradle 使用与 Maven 相同的逻辑来识别本地 Maven 缓存的位置。如果在 a 中定义了本地存储库位置settings.xml，则将使用该位置。 in优先于settings.xmlin 。如果没有可用的位置，Gradle 将使用默认位置。<home directory of the current user>/.m2settings.xmlM2_HOME/confsettings.xml<home directory of the current user>/.m2/repository

mavenLocal() 的情况

作为一般建议，您应该避免添加mavenLocal()为存储库。mavenLocal()您应该注意使用中的不同问题：

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

在某些情况下您可能需要使用mavenLocal()：

为了与 Maven 互操作
- 例如，项目A使用Maven构建，项目B使用Gradle构建，开发过程中需要共享工件
- 最好使用内部全功能存储库
- 如果这是不可能的，您应该仅限于本地构建
与 Gradle 本身的互操作性
- 在多存储库世界中，您想要检查项目 A 的更改是否适用于项目 B
- 对于此用例，最好使用复合构建
- 如果由于某种原因，复合构建和全功能存储库都不可能，那么这mavenLocal()是最后的选择

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

常春藤存储库

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

使用标准布局定义 Ivy 存储库

要使用标准布局声明 Ivy 存储库，不需要额外的自定义。您只需声明 URL 即可。

Example 8. Ivy repository

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 默认布局。

Example 9. Ivy repository with named layout

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 存储库，您可以为存储库定义模式布局：

Example 10. Ivy repository with pattern layout

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

Example 11. Ivy repository with multiple custom patterns

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"
        }
    }
}

或者，具有模式布局的存储库可以将其'organisation'部分以 Maven 风格布局，并用正斜杠替换点作为分隔符。例如，该组织my.company将表示为my/company。

Example 12. Ivy repository with Maven compatible layout

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 存储库的凭据。

Example 13. Ivy repository with authentication

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 来声明存储库可能包含或不包含的内容。它有不同的用例：

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

当考虑到存储库的声明顺序很重要时，这一点甚至更为重要。

声明存储库过滤器

Example 14. Declaring repository contents

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.*"
        }
    }
}

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

如果您声明包含，那么它会排除除包含内容之外的所有内容。
如果您声明排除，则它包括除排除之外的所有内容。
如果您同时声明包含和排除，则它仅包含显式包含但不排除的内容。

可以通过显式的group、module或version进行过滤，无论是严格的还是使用正则表达式。当使用严格版本时，可以使用版本范围，使用Gradle支持的格式。此外，还有按解析上下文的过滤选项：配置名称甚至配置属性。有关详细信息，请参阅RepositoryContentDescriptor。

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

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

或者，Gradle 提供了一个 API，可让您声明存储库专门包含一个工件。如果您这样做：

在存储库中声明的工件无法在任何其他存储库中找到
专有存储库内容必须在扩展中声明（就像存储库级别内容一样）

Example 15. Declaring exclusive repository contents

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"
        }
    }
}

可以通过显式的group、module或version进行过滤，无论是严格的还是使用正则表达式。有关详细信息，请参阅InclusiveRepositoryContentDescriptor。

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

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

Maven 存储库过滤

对于Maven 存储库，通常情况下存储库将包含版本或快照。 Gradle 允许您使用以下 DSL 声明在存储库中找到了哪种工件：

Example 16. Splitting snapshots and releases

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 存储库。为此，您可以为任何存储库配置元数据源。

Example 17. Maven repository that supports artifacts without metadata

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. 支持的元数据源
元数据源	描述	命令	梅文	常春藤/平面目录
`gradleMetadata()`	查找 Gradle`.module`文件	第一名	是的	是的
`mavenPom()`	查找 Maven`.pom`文件	第二名	是的	是的
`ivyDescriptor()`	寻找`ivy.xml`文件	第二名	不	是的
`artifact()`	直接寻找神器	第三名	是的	是的

Gradle 6.0 中 Ivy 和 Maven 存储库的默认设置发生了变化。在 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 声明来禁用此行为。

Example 18. Maven repository that does not use gradle metadata redirection

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 知道在哪里搜索。

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

集中存储库声明

allprojectsGradle 提供了一种在所有项目的中心位置声明存储库的方法，而不是在构建的每个子项目中或通过块声明存储库。

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

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

Example 19. Declaring a Maven repository in settings

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

存储dependencyResolutionManagement库块接受与项目中相同的符号。这包括 Maven 或 Ivy 存储库，有或没有凭证等。

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

Example 20. Preferring project repositories

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

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

不

对于强制大型团队仅使用批准的存储库很有用。

settings.gradle(.kts)您可以使用以下命令更改行为以首选文件中的存储库repositoriesMode：

Example 21. Preferring settings repositories

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_SETTINGS
}

settings.gradle

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.PREFER_SETTINGS
}

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

如果您想强制只使用设置存储库，您可以强制 Gradle 使构建失败：

Example 22. Enforcing settings repositories

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 插件之一来加密和使用凭证，例如凭证插件。

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

Example 23. Declaring a Maven and Ivy repository

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 存储库：

Example 24. Using the SFTP protocol for a repository

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"
        }
    }
}

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

Example 25. Declaring an S3 backed Maven and Ivy repository

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。以下示例显示了如何操作：

Example 26. Declaring an S3 backed Maven and Ivy repository using IAM

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)
        }
    }
}

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

Example 27. Declaring a Google Cloud Storage backed Maven and Ivy repository using default application credentials

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"
    }
}

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

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

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

Example 28. Accessing password-protected Maven repository

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：

Example 29. Configure repository to use only digest authentication

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)
        }
    }
}

目前支持的认证方案有：

基本身份验证: 通过 HTTP 的基本访问身份验证。使用此方案时，会抢先发送凭证。
摘要验证: 通过 HTTP 进行摘要式访问身份验证。
HttpHeader认证: 基于任何自定义 HTTP 标头的身份验证，例如私有令牌、OAuth 令牌等。

使用抢占式身份验证

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

Example 30. Configure repository to use preemptive authentication

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 标头身份验证

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

Example 31. Accessing header-protected Maven repository

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 签名的存储桶指定特定于区域的端点意味着：

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

AWS S3 跨账户访问

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

Google 云存储存储库配置

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 属性中查找凭证值。

例如，给定存储库配置：

Example 32. Externalized repository credentials

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`	`Username`	必需的
`PasswordCredentials`	`password`	`Password`	必需的
`AwsCredentials`	`accessKey`	`AccessKey`	必需的
	`secretKey`	`SecretKey`	必需的
	`sessionToken`	`SessionToken`	选修的
`HttpHeaderCredentials`	`name`	`AuthHeaderName`	必需的
`HttpHeaderCredentials`	`value`	`AuthHeaderValue`	必需的

此页面是否有帮助？