Gradle可以基于Maven,Ivy或平面目录格式解析来自一个或多个存储库的依赖项. 有关所有信息 ,请查看所有类型存储库完整参考 .

Declaring a publicly-available repository

构建软件的组织可能希望利用公共二进制存储库来下载和使用开源依赖项. 流行的公共存储库包括Maven CentralBintray JCenterGoogle Android存储库. Gradle为这些广泛使用的存储库提供了内置的速记符号.

dependency management shortcut repositories
图1.借助简写方式声明存储库

在幕后,Gradle解析了由速记符号定义的公共存储库的相应URL中的依赖性. 所有速记符号均可通过RepositoryHandler API获得. 或者,您可以拼出存储库的URL以进行更细粒度的控制.

Maven Central repository

Maven Central是一个流行的存储库,托管开放源代码库供Java项目使用.

要为您的构建声明Maven Central存储库 ,请将其添加到脚本中:

示例1.添加中央Maven存储库
build.gradle
repositories {
    mavenCentral()
}
build.gradle.kts
repositories {
    mavenCentral()
}

JCenter Maven repository

Bintray的JCenter是所有流行的Maven OSS工件的最新集合,包括直接发布到Bintray的工件.

要声明JCenter Maven存储库,请将其添加到您的构建脚本中:

示例2.添加Bintray的JCenter Maven存储库
build.gradle
repositories {
    jcenter()
}
build.gradle.kts
repositories {
    jcenter()
}

Google Maven repository

Google存储库托管Android特定的工件,包括Android SDK. 有关使用示例,请参阅相关的Android文档 .

要声明Google Maven存储库,请将其添加到您的构建脚本中:

例子3.添加Google Maven仓库
build.gradle
repositories {
    google()
}
build.gradle.kts
repositories {
    google()
}

Declaring a custom repository by URL

大多数企业项目都建立了仅在Intranet中可用的二进制存储库. 内部存储库使团队可以发布内部二进制文件,设置用户管理和安全措施并确保正常运行时间和可用性. 如果要声明一个不太受欢迎但可公开使用的存储库,则指定自定义URL也很有用.

通过调用RepositoryHandler API上可用的相应方法,可以将具有自定义URL的存储库指定为Maven或Ivy存储 . Gradle支持httphttps以外的其他协议作为自定义URL的一部分,例如filesftps3 . 有关完整信息,请参见有关支持的存储库类型部分 .

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

Declaring multiple repositories

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

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

例子4.声明多个仓库
build.gradle
repositories {
    jcenter()
    maven {
        url "https://maven.springframework.org/release"
    }
    maven {
        url "https://maven.restlet.com"
    }
}
build.gradle.kts
repositories {
    jcenter()
    maven {
        url = uri("https://maven.springframework.org/release")
    }
    maven {
        url = uri("https://maven.restlet.com")
    }
}

声明的顺序决定了Gradle在运行时如何检查依赖关系. 如果Gradle在特定存储库中找到模块描述符,它将尝试从同一存储库下载该模块的所有工件. 您可以了解有关依赖项下载的内部工作的更多信息.

Strict limitation to declared repositories

Maven POM元数据可以引用其他存储库. 这些将被Gradle 忽略 ,Gradle将仅使用构建本身中声明的存储库.

这是可重现的安全保护措施,也是安全保护措施. 没有它,依赖项的更新版本可能会将工件从任何地方拉入构建.

Supported repository types

Gradle在格式和连接性方面都支持多种依赖项源. 您可以通过以下方式解决依赖关系:

Flat directory repository

一些项目可能更喜欢将依赖项存储在共享驱动器上,或者作为项目源代码的一部分存储,而不是二进制存储库产品. 如果要将(平面)文件系统目录用作存储库,只需键入:

例子5.平面存储库解析器
build.gradle
repositories {
    flatDir {
        dirs 'lib'
    }
    flatDir {
        dirs 'lib1', 'lib2'
    }
}
build.gradle.kts
repositories {
    flatDir {
        dirs("lib")
    }
    flatDir {
        dirs("lib1", "lib2")
    }
}

这将添加存储库,这些存储库将查找一个或多个目录以查找依赖项.

这种类型的存储库不支持任何元数据格式,例如Ivy XML或Maven POM文件. 取而代之的是,Gradle将根据工件的存在情况动态生成模块描述符(不包含任何依赖项信息).

As Gradle prefers to use modules whose descriptor has been created from real meta-data rather than being generated, flat directory repositories cannot be used to override artifacts with real meta-data from other repositories declared in the build.

例如,如果发现摇篮仅jmxri-1.2.1.jar在平坦目录库,但jmxri-1.2.1.pom在另一个存储库,支持元数据时,将使用所述第二存储库以提供模块.

对于用本地对象覆盖远程工件的用例,请考虑使用Ivy或Maven存储库,而不是其URL指向本地目录.

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

Local repositories

以下各节描述存储库格式(Maven或Ivy). 可以使用本地文件系统路径将它们声明为本地存储库.

平面目录存储库的不同之处在于它们确实遵循一种格式并包含元数据.

配置了这样的存储库后,Gradle将完全绕过其依赖项缓存 ,因为无法保证内容在两次执行之间不会发生变化. 由于该限制,它们可能会对性能产生影响.

它们还使构建的可复制性变得更难实现,应将其使用限制为修补或原型制作.

Maven repositories

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

要添加自定义Maven存储库,您可以执行以下操作:

例子6.添加定制的Maven仓库
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
    }
}

Setting up composite Maven repositories

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

例子7.为JAR文件添加额外的Maven存储库
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"
    }
}
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")
    }
}

Gradle将查看POM和JAR的基本url位置. 如果无法在此处找到JAR,则使用额外的artifactUrls查找JAR.

Accessing authenticated Maven repositories

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

请参阅支持的存储库传输协议以获取认证选项.

Local Maven repository

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

Gradle将已解决的依赖性存储在其自己的缓存中 . 即使您从基于Maven的远程存储库中解决依赖关系,构建也无需声明本地Maven存储库.

在将Maven local添加为存储库之前,您应确保确实需要这样做 .

To declare the local Maven cache as a repository add this to your build script:

Example 8. Adding the local Maven cache as a repository
build.gradle
repositories {
    mavenLocal()
}
build.gradle.kts
repositories {
    mavenLocal()
}

Gradle使用与Maven相同的逻辑来标识本地Maven缓存的位置. 如果在settings.xml定义了本地存储库位置,那么将使用此位置. 在settings.xmlUSER_HOME /.m2优先于settings.xmlM2_HOME /conf . 如果没有settings.xml可用,则Gradle使用默认位置USER_HOME /.m2/repository .

The case for mavenLocal()

作为一般建议,应避免将mavenLocal()添加为存储库. 使用mavenLocal() ,您应该注意一些不同的问题:

  • Maven将其用作缓存而不是存储库,这意味着它可以包含部分模块.

    • 例如,如果Maven从不下载给定模块的源文件或javadoc文件,则Gradle将不会找到它们,因为一旦找到模块,它就会在单个存储库中搜索文件 .

  • 作为本地存储库 ,Gradle不信任其内容,因为:

    • 无法追踪工件的来源,这是正确性和安全性问题

    • 工件很容易被覆盖,这是一个安全性,正确性和可再现性问题

  • 为了缓解元数据和/或工件可以更改的事实,Gradle不对本地存储库执行任何缓存

    • 因此,您的构建速度较慢

    • 鉴于存储库的顺序很重要, mavenLocal() 首先添加mavenLocal()意味着您的所有构建速度都会变慢

在某些情况下,您可能必须使用mavenLocal()

  • 为了与Maven互操作

    • 例如,项目A是使用Maven构建的,项目B是使用Gradle构建的,并且您需要在开发过程中共享工件

    • 总是最好使用内部功能齐全的存储库来代替

    • 如果无法做到这一点,则应将其限制为仅本地构建

  • 与Gradle本身的互操作性

    • 在多存储库环境中,您要检查对项目A的更改是否与项目B一起使用

    • 对于此用例,最好使用复合构建

    • 如果由于某种原因既无法构建复合版本,也不具有功能齐全的存储库,则mavenLocal()是最后的选择

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

Ivy repositories

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

Defining an Ivy repository with a standard layout

要使用标准布局声明常春藤存储库,不需要其他自定义. 您只需声明URL.

例子9.常春藤仓库
build.gradle
repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
    }
}
build.gradle.kts
repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
    }
}

Defining a named layout for an Ivy repository

您可以使用命名布局来指定存储库符合Ivy或Maven默认布局.

例子10.具有命名布局的Ivy存储库
build.gradle
repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "maven"
    }
}
build.gradle.kts
repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        layout("maven")
    }
}

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

Defining custom pattern layout for an Ivy repository

要使用非标准布局定义常春藤存储库,可以为存储库定义模式布局:

例子11.具有模式布局的Ivy存储库
build.gradle
repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        patternLayout {
            artifact "[module]/[revision]/[type]/[artifact].[ext]"
        }
    }
}
build.gradle.kts
repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        patternLayout {
            artifact("[module]/[revision]/[type]/[artifact].[ext]")
        }
    }
}

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

为存储库指定的每个artifactivy添加了要使用的其他模式. 模式按照定义的顺序使用.

例子12.具有多个自定义模式的Ivy存储库
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"
        }
    }
}
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")
        }
    }
}

可选地,具有模式布局的存储库可以将其'organisation'部分以Maven样式进行布局,用正斜杠替换点作为分隔符. 例如,组织my.company将被表示为my/company .

例子13.具有Maven兼容布局的Ivy存储库
build.gradle
repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        patternLayout {
            artifact "[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            m2compatible = true
        }
    }
}
build.gradle.kts
repositories {
    ivy {
        url = uri("http://repo.mycompany.com/repo")
        patternLayout {
            artifact("[organisation]/[module]/[revision]/[artifact]-[revision].[ext]")
            setM2compatible(true)
        }
    }
}

Accessing authenticated Ivy repositories

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

例子14.具有身份验证的Ivy存储库
build.gradle
repositories {
    ivy {
        url "http://repo.mycompany.com"
        credentials {
            username "user"
            password "password"
        }
    }
}
build.gradle.kts
repositories {
    ivy {
        url = uri("http://repo.mycompany.com")
        credentials {
            username = "user"
            password = "password"
        }
    }
}

请参阅支持的存储库传输协议以获取认证选项.

Repository content filtering

Gradle公开了一个API,以声明存储库可能包含或不包含的内容. 有不同的用例:

  • 性能,当您知道在特定存储库中永远找不到依赖项时

  • 通过避免泄漏私有项目中使用的依赖项来确保安全性

  • 可靠性,当某些存储库包含损坏的元数据或工件时

考虑到存储库的声明顺序很重要,这一点甚至更为重要.

Declaring a repository filter

例子15.声明存储库内容
build.gradle
repositories {
    maven {
        url "https://repo.mycompany.com/maven2"
        content {
            // this repository *only* contains artifacts with group "my.company"
            includeGroup "my.company"
        }
    }
    jcenter {
        content {
            // this repository contains everything BUT artifacts with group starting with "my.company"
            excludeGroupByRegex "my\\.company.*"
        }
    }
}
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")
        }
    }
    jcenter {
        content {
            // this repository contains everything BUT artifacts with group starting with "my.company"
            excludeGroupByRegex("my\\.company.*")
        }
    }
}

默认情况下,存储库包含所有内容,不包含任何内容:

  • 如果声明包含,那么它排除了一切,但包含的内容.

  • 如果声明一个排除项,则它包括排除项以外的所有内容.

  • 如果声明包含和排除,则它仅包括显式包括但不排除的内容.

可以通过显式groupmoduleversion严格或使用正则表达式进行过滤. 有关详细信息,请参见RepositoryContentDescriptor .

Maven repository filtering

对于Maven存储库 ,通常情况下,存储库将包含发行版或快照. Gradle允许您声明使用此DSL在存储库中找到哪种工件:

例子16.分割快照和发行版
build.gradle
repositories {
    maven {
        url "https://repo.mycompany.com/releases"
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        url "https://repo.mycompany.com/snapshots"
        mavenContent {
            snapshotsOnly()
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/releases")
        mavenContent {
            releasesOnly()
        }
    }
    maven {
        url = uri("https://repo.mycompany.com/snapshots")
        mavenContent {
            snapshotsOnly()
        }
    }
}

Supported metadata sources

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

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

例子17. Maven仓库支持没有元数据的工件
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}

您可以指定多个源来告诉Gradle继续查找是否找不到文件. 在这种情况下,检查源的顺序是预定义的.

支持以下元数据源:

表1.存储库传输协议
元数据源 Description Order Maven 常春藤/平目录

gradleMetadata()

寻找Gradle .module文件

1st

yes

yes

mavenPom()

查找Maven .pom文件

2nd

yes

yes

ivyDescriptor()

Look for ivy.xml files

2nd

no

yes

artifact()

直接寻找伪像

3rd

yes

yes

Ivy和Maven存储库的默认值随Gradle 6.0更改. 在6.0之前的版本中, artifact()包含在默认值中. 当模块完全丢失时导致效率低下. 要恢复此行为,例如,对于Maven mavenCentral { metadataSources { mavenPom(); artifact() } }可以使用mavenCentral { metadataSources { mavenPom(); artifact() } } mavenCentral { metadataSources { mavenPom(); artifact() } } . 以类似的方式,您可以使用mavenCentral { metadataSources { mavenPom() } }加入Gradle较旧的版本中的新行为

从Gradle 5.3开始,在解析元数据文件(无论是Ivy还是Maven)时,Gradle将寻找一个标记,指示存在匹配的Gradle Module元数据文件. 如果找到它,它将代替Ivy或Maven文件使用.

从Gradle 5.6开始,您可以通过将ignoreGradleMetadataRedirection()添加到metadataSources声明来禁用此行为.

例子18.不使用gradle元数据重定向的Maven存储库
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/repo"
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/repo")
        metadataSources {
            mavenPom()
            artifact()
            ignoreGradleMetadataRedirection()
        }
    }
}

Plugin repositories vs. build repositories

在构建期间,Gradle将在两个不同的阶段使用存储库.

第一阶段是在配置构建并加载其应用的插件时. 为此,Gradle将使用一组特殊的存储库.

第二阶段是在依赖关系解析期间. 此时,Gradle将使用项目中声明的存储库,如前几节所示.

Plugin repositories

默认情况下,Gradle将使用Gradle插件门户来查找插件.

但是,由于不同的原因,在其他公共存储库或非公共存储库中都有可用的插件. 当构建需要这些插件之一时,需要指定其他存储库,以便Gradle知道要在哪里搜索.

由于声明存储库的方式及其预期包含的内容取决于插件的应用方式,因此最好参考Custom Plugin Repositories .

Supported repository transport protocols

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

表2.存储库传输协议
Type 凭证类型 Link

file

none

http

username/password

Documentation

https

username/password

Documentation

sftp

username/password

Documentation

s3

访问密钥/秘密密钥/会话令牌或环境变量

Documentation

gcs

默认应用程序凭据来自众所周知的文件,环境变量等.

Documentation

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

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

例子19.声明一个Maven和Ivy存储库
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }

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

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

以下示例显示了如何声明SFTP存储库:

示例20.对存储库使用SFTP协议
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"
        }
    }
}
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"
        }
    }
}

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

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

例子21.声明一个由S3支持的Maven和Ivy存储库
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"
        }
    }
}
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"
        }
    }
}

您还可以使用AwsImAuthentication将所有凭证委派给AWS sdk. 以下示例显示了如何:

示例22.使用IAM声明一个由S3支持的Maven和Ivy存储库
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)
        }
    }
}
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")
        }
    }
}

有关与AWS S3相关的身份验证的详细信息,请参阅" AWS S3存储库配置 "部分.

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

示例23.使用默认的应用程序凭证声明一个由Google Cloud Storage支持的Maven和Ivy存储库
build.gradle
repositories {
    maven {
        url "gcs://myCompanyBucket/maven2"
    }

    ivy {
        url "gcs://myCompanyBucket/ivyrepo"
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("gcs://myCompanyBucket/maven2")
    }

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

有关与Google GCS相关的身份验证的详细信息,请参阅" Google Cloud Storage存储库配置"部分 .

HTTP(S) authentication schemes configuration

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

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

Example 24. Accessing password-protected Maven repository
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
        credentials {
            username "user"
            password "password"
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }
}
该示例的代码可以在Gradle的'-all'发行版的samples/userguide/artifacts/defineRepository中找到.

以下示例显示如何将存储库配置为仅使用DigestAuthentication

示例25.将存储库配置为仅使用摘要身份验证
build.gradle
repositories {
    maven {
        url 'https://repo.mycompany.com/maven2'
        credentials {
            username "user"
            password "password"
        }
        authentication {
            digest(DigestAuthentication)
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<DigestAuthentication>("digest")
        }
    }
}

当前支持的身份验证方案是:

BasicAuthentication

通过HTTP的基本访问身份验证. 使用此方案时,将抢先发送凭据.

DigestAuthentication

通过HTTP的摘要式访问身份验证.

HttpHeaderAuthentication

基于任何自定义HTTP标头的身份验证,例如私有令牌,OAuth令牌等.

Using preemptive authentication

Gradle的默认行为是仅在服务器以HTTP 401响应的形式通过身份验证质询响应时提交凭据. 在某些情况下,服务器将以不同的代码响应(例如,对于托管在GitHub上的存储库,返回404),从而导致依赖性解析失败. 若要解决此问题,凭据可能会抢先发送到服务器. 要启用抢占式身份验证,只需将您的存储库配置为显式使用BasicAuthentication方案:

例子26.配置存储库以使用抢占式认证
build.gradle
repositories {
    maven {
        url 'https://repo.mycompany.com/maven2'
        credentials {
            username "user"
            password "password"
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<BasicAuthentication>("basic")
        }
    }
}

Using HTTP header authentication

您可以使用带有HttpHeaderAuthentication的HttpHeaderCredentials为需要令牌,OAuth2或其他基于HTTP头的身份验证的保护的Maven存储库指定任何HTTP头.

例子27.访问受头部保护的Maven存储库
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
        credentials(HttpHeaderCredentials) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}
该示例的代码可以在Gradle的'-all'发行版的samples/userguide/artifacts/defineRepository中找到.

AWS S3 repositories configuration

S3 configuration properties

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

org.gradle.s3.endpoint

使用不兼容AWS,S3 API的存储服务时,用于覆盖AWS S3终端节点.

org.gradle.s3.maxErrorRetry

指定在S3服务器以HTTP 5xx状态代码响应的情况下重试请求的最大次数. 如果未指定,则使用默认值3.

S3 URL formats

S3 URL是"虚拟主机样式",并且必须采用以下格式

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

e.g. s3://myBucket.s3.eu-central-1.amazonaws.com/maven/release

  • myBucket是AWS S3存储桶名称.

  • s3.eu-central-1.amazonaws.com可选的 区域特定端点 .

  • /maven/release是AWS S3密钥(存储桶中对象的唯一标识符)

S3 proxy settings

可以使用以下系统属性来配置S3的代理:

  • https.proxyHost

  • https.proxyPort

  • https.proxyUser

  • https.proxyPassword

  • http.nonProxyHosts

如果已使用HTTP(非HTTPS)URI指定org.gradle.s3.endpoint属性,则可以使用以下系统代理设置:

  • http.proxyHost

  • http.proxyPort

  • http.proxyUser

  • http.proxyPassword

  • http.nonProxyHosts

AWS S3 V4 Signatures (AWS4-HMAC-SHA256)

某些AWS S3地区(eu-central-1-Frankfurt)要求所有HTTP请求均根据AWS的签名版本4进行签名 . 当使用需要V4签名的存储桶时,建议指定包含区域特定终结点的S3 URL. 例如

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

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

尝试将请求重新发送给.... 使用AWS V4身份验证 为避免将来出现此警告,请使用特定于区域的终结点来访问需要V4签名的区域中的存储桶.

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

  • 每次上传和下载文件时,AWS往返3次,而不是一次.

  • 根据位置-网络等待时间增加,构建速度变慢.

  • 传输失败的可能性增加.

AWS S3 Cross Account Access

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

Google Cloud Storage repositories configuration

GCS configuration properties

以下系统属性可用于配置与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 formats

Google Cloud Storage URL是"虚拟主机样式",并且必须采用以下格式gcs://<bucketName>/<objectKey>

e.g. gcs://myBucket/maven/release

  • myBucket是Google Cloud Storage存储桶名称.

  • /maven/release是Google Cloud Storage密钥(存储桶中对象的唯一标识符)