Gradle 支持多种用于 Maven 和 Ivy 仓库的传输协议。

支持的传输协议

这些协议决定了 Gradle 如何与仓库通信以解析依赖项。

类型 凭据类型 链接

file

无

http

用户名/密码

文档

https

用户名/密码

文档

sftp

用户名/密码

文档

s3

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

文档

gcs

默认应用程序凭据，来源于已知文件、环境变量等。

文档
用户名和密码绝不应以纯文本形式存储在您的构建文件中。相反，请将凭据存储在本地 gradle.properties 文件中，或使用开源 Gradle 插件来加密和使用凭据，例如 credentials 插件。

传输协议在仓库 URL 中指定。

以下是如何使用各种协议声明仓库的示例

示例 1. 声明基于 HTTP 的 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"
    }
}
示例 2. 声明仓库的 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"
        }
    }
}
示例 3. 声明 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"
        }
    }
}
示例 4. 声明使用 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)
        }
    }
}
示例 5. 声明 GCS 支持的 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"
    }
}

配置身份验证方案

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

当配置使用 HTTP 或 HTTPS 传输协议的仓库时，有几种身份验证方案可用。默认情况下，Gradle 尝试使用 Apache HttpClient 库 支持的所有方案。但是，您可能希望显式指定与远程服务器交互时应使用哪些身份验证方案。当显式声明时，将仅使用那些指定的方案。

基本身份验证

您可以使用 PasswordCredentials 为基本身份验证保护的 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

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 令牌。

使用抢先身份验证

默认情况下，仅当服务器响应身份验证质询 (HTTP 401) 时，Gradle 才会提交凭据。但是，某些服务器可能会响应不同的代码（例如，GitHub 返回 404），这可能会导致依赖项解析失败。在这种情况下，您可以配置 Gradle 通过显式使用 BasicAuthentication 方案来抢先发送凭据

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

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 仓库配置

当配置使用 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

    • https.proxyHost

    • https.proxyPort

    • https.proxyUser

    • https.proxyPassword

    • http.nonProxyHosts（注意：这不是拼写错误。）*对于 HTTP（如果 org.gradle.s3.endpoint 设置为 HTTP URI）

    • http.proxyHost

    • http.proxyPort

    • http.proxyUser

    • http.proxyPassword

    • http.nonProxyHosts

S3 V4 签名 (AWS4-HMAC-SHA256)

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

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

如果未为需要 V4 签名的存储桶指定区域特定端点，Gradle 将默认为 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.

未能为此类存储桶指定区域特定端点会导致

  • 增加网络流量：每个文件上传/下载到 AWS 的往返次数增加到三次，而不是一次。

  • 构建速度变慢：由于网络延迟增加。

  • 更高的传输失败率：由于额外的网络开销。

S3 跨账户访问

在具有多个 AWS 账户（例如，每个团队一个）的组织中，存储桶所有者可能与工件发布者或使用者不同。为确保使用者可以访问工件，存储桶所有者必须授予适当的访问权限。Gradle 会自动将 bucket-owner-full-control Canned ACL 应用于上传的对象。确保发布者具有所需的 IAM 权限（如果启用了存储桶版本控制，则为 PutObjectAcl 和 PutObjectVersionAcl），可以直接或通过承担的 IAM 角色获得。有关更多详细信息，请参阅 AWS S3 访问权限。

Google Cloud Storage 仓库配置

当配置使用 Google Cloud Storage (GCS) 的仓库时，有几个配置选项和设置可用。

GCS 配置属性

您可以使用以下系统属性来配置与 GCS 仓库的交互

org.gradle.gcs.endpoint

覆盖 Google Cloud Storage 端点，当使用与 GCS API 兼容但不托管在 Google Cloud Platform 上的存储服务时非常有用。

org.gradle.gcs.servicePath

指定 GCS 客户端构建请求的根服务路径，默认值为 /。

GCS URL 格式

GCS URL 使用“虚拟主机样式”格式，并且必须符合以下结构

gcs://<bucketName>/<objectKey>

  • <bucketName>: Google Cloud Storage 存储桶的名称。

  • <objectKey>: 存储桶内对象的唯一标识符。

示例: gcs://myBucket/maven/release

  • myBucket: 存储桶名称。

  • /maven/release: GCS 对象密钥。

处理凭据

仓库凭据绝不应硬编码在您的构建脚本中，而应保持外部化。Gradle 在 工件仓库中提供了一个 API，允许您声明所需的凭据类型，其值将从构建期间的 Gradle 属性 中查找。

例如，考虑以下仓库配置

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 将在运行任何任务之前检查其是否存在，以防止由于缺少凭据而导致构建失败。

支持的凭据类型

仅支持查找下表列出的凭据类型

类型 参数 基本属性名称 是否必需？

PasswordCredentials

username

Username

必需

password

Password

必需

AwsCredentials

accessKey

AccessKey

必需

secretKey

SecretKey

必需

sessionToken

SessionToken

可选

HttpHeaderCredentials

name

AuthHeaderName

必需

value

AuthHeaderValue

必需