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

支持的传输协议

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

类型 凭据类型 链接

文件

无

http

用户名/密码

文档

https

用户名/密码

文档

sftp

用户名/密码

文档

s3

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

文档

gcs

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

文档
用户名和密码不应以明文形式存储在构建文件中。相反，请将凭据存储在本地 gradle.properties 文件中，或通过环境变量提供凭据。

传输协议是作为仓库 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 的基本访问认证。凭据会预先发送。

摘要认证

通过 HTTP 的摘要访问认证。

HttpHeaderAuthentication

基于自定义 HTTP 头的认证，例如私有令牌或 OAuth 令牌。

使用抢先认证

默认情况下，Gradle 仅在服务器响应认证质询 (HTTP 401) 时提交凭据。但是，某些服务器可能会响应不同的代码（例如，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 预设 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

用户名

必需

password

密码

必需

AwsCredentials

accessKey

AccessKey

必需

secretKey

SecretKey

必需

sessionToken

SessionToken

可选

HttpHeaderCredentials

name

AuthHeaderName

必需

value

AuthHeaderValue

必需