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

支持的传输协议

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

类型 凭证类型 链接

file

无

http

用户名/密码

文档

https

用户名/密码

文档

sftp

用户名/密码

文档

s3

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

文档

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 库支持的所有方案。但是，您可能希望显式指定与远程服务器交互时应使用哪些身份验证方案。显式声明后，将只使用指定的方案。

基本身份验证 (Basic authentication)

您可以使用 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"
        }
    }
}

摘要身份验证 (Digest Authentication)

要配置仓库仅使用 摘要身份验证 (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 令牌。

使用抢先身份验证

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

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 角色拥有所需的 IAM 权限（如果启用存储桶版本控制，则包括 PutObjectAcl 和 PutObjectVersionAcl）。更多详细信息，请参阅 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 properties 中查找其值。

例如，考虑以下仓库配置

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 的属性中查找。

配置属性前缀

配置属性前缀，称为标识符 (identity)，派生自仓库名称。可以通过任何受支持的 Gradle 属性机制提供凭证：gradle.properties 文件、命令行参数、环境变量或这些机制的组合。

条件式凭证要求

仅当构建过程需要凭证时才会要求提供。例如，如果一个项目配置为将制品发布到安全的仓库，但未调用发布任务，则 Gradle 不会要求提供凭证。但是，如果需要凭证的任务是构建过程的一部分，Gradle 将在运行任何任务之前检查它们是否存在，以防止因缺少凭证而导致构建失败。

支持的凭证类型

仅支持下表中列出的凭证类型进行查找

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

PasswordCredentials

username

用户名

必需

password

密码

必需

AwsCredentials

accessKey

访问密钥

必需

secretKey

Secret 密钥

必需

sessionToken

会话令牌

可选

HttpHeaderCredentials

name

AuthHeaderName

必需

value

AuthHeaderValue

必需