Gradle Proxy Configuration – Gradle 代理配置

1. Overview

1.概述

A proxy server acts as an intermediary between a client and a server. It helps evaluate requests from a client before forwarding them to target servers based on certain criteria. This gives a system flexibility to determine which network to connect to or not.

代理服务器充当客户端和服务器之间的中介。它帮助评估来自客户端的请求，然后根据特定标准将其转发到目标服务器。这让系统可以灵活地决定是否连接到哪个网络。

In this tutorial, we’ll learn how to configure Gradle to work behind a proxy server. In our example, our proxy is running on localhost with a proxy port 3128 for both HTTP and HTTPS connections.

在本教程中，我们将学习如何配置 Gradle 以在代理服务器后面工作。在我们的示例中，代理服务器运行在 localhost 上，代理端口 3128 用于 HTTP 和 HTTPS 连接。

2. Proxy Configuration

2.代理配置

We can configure Gradle to work behind a proxy server with or without authentication credentials.

我们可以配置 Gradle 在代理服务器后面工作，无论是否需要验证凭据。

2.1. Basic Proxy Configuration

2.1.基本代理配置

To begin with, let’s set up a basic proxy configuration that doesn’t require authentication credentials. First, let’s create a file named gradle.properties in the root directory of a Gradle project.

首先，让我们设置一个不需要验证凭据的基本代理配置。首先，让我们在 Gradle 项目的根目录中创建一个名为 gradle.properties 的文件。

Next, let’s define the system properties for the proxy server in the gradle.properties file:

接下来，让我们在 gradle.properties 文件中定义代理服务器的 系统属性：

systemProp.http.proxyHost=localhost
systemProp.http.proxyPort=3128
systemProp.https.proxyHost=localhost
systemProp.https.proxyPort=3128

Here, we define system properties that Gradle will use during the build process. We define system properties for both HTTP and HTTPS connections. In this case, they both have the same hostname and proxy port.

在这里，我们定义了 Gradle 在构建过程中会用到的系统属性。我们为 HTTP 和 HTTPS 连接定义了系统属性。在这种情况下，它们都有相同的主机名和代理端口。

Also, we can specify a host in the gradle.properties file to bypass the proxy server:

此外，我们还可以在 gradle.properties 文件中指定主机，以绕过代理服务器：

systemProp.http.nonProxyHosts=*.nonproxyrepos.com
systemProp.https.nonProxyHosts=*.nonproxyrepos.com

In the configuration above, the subdomain nonproxyrepos.com will bypass the proxy server and request resources directly from a server.

在上述配置中，子域 nonproxyrepos.com 将绕过代理服务器，直接从服务器请求资源。

Alternatively, we can run the ./gradlew build command with the system properties as an option via the terminal:

或者，我们可以通过终端运行 ./gradlew build 命令，并将系统属性作为选项：

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3128 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3128 build

Here, we define the system properties to connect to the proxy server via the terminal.

在此，我们定义了通过终端连接代理服务器的系统属性。

Notably, defining the system properties via the terminal overrides the configuration of the gradle.properties file.

值得注意的是，通过终端定义系统属性会覆盖 gradle.properties 文件的配置。

2.2. Adding Authentication Credentials

2.2.添加身份验证凭据

In a case where the proxy is secured, we can add authentication credentials to the gradle.properties file:

如果代理是安全的，我们可以在gradle.properties文件中添加身份验证凭据：

systemProp.http.proxyUser=Baeldung
systemProp.http.proxyPassword=admin
systemProp.https.proxyUser=Baeldung
systemProp.https.proxyPassword=admin

Here, we add authentication credentials by defining the system properties for the username and password. Also, we implement authentication credentials for both HTTP and HTTPS connections.

在这里，我们通过定义用户名和密码的系统属性来添加身份验证凭证。此外，我们还为 HTTP 和 HTTPS 连接实施了身份验证凭证。

Alternatively, we can specify the username and password via the terminal:

或者，我们也可以通过终端指定用户名和密码：

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3128 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3128 -Dhttps.proxyUser=Baeldung -Dhttps.proxyPassword=admin build

Here, we include the authentication credentials in the terminal command.

这里，我们在终端命令中加入了身份验证凭据。

3. Possible Errors

3.可能出现的错误

An error may occur if the hostname and the proxy port are incorrect:

如果主机名和代理端口不正确，可能会发生错误：

> Could not get resource 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Could not GET 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> localhosty: Name or service not known

Here, the build failed because we mistakenly wrote the proxy host as “localhosty” instead of “localhost”.

这里，构建失败是因为我们错误地将代理主机写成了”localhosty“，而不是”localhost”。

Also, in a case where we define the system properties in a gradle.properties file and command line, the command line definition has the highest precedence during the build:

此外，当我们在 gradle.properties 文件和命令行中定义系统属性时，命令行定义在构建过程中具有最高优先级：

$ ./gradlew -Dhttp.proxyHost=localhost -Dhttp.proxyPort=3120 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=3120 build

Here, the proxy port value in the command line is 3120, which is wrong. The gradle.properties file proxy port value is 3128, which is correct. However, the build fails with the following error message:

这里，命令行中的代理端口值是 3120，这是错误的。gradle.properties 文件中的代理端口值为 3128，这是正确的。但是，编译失败时会出现以下错误信息：

> Could not get resource 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Could not GET 'https://repo.maven.apache.org/maven2/io/micrometer/micrometer-core/1.12.0/micrometer-core-1.12.0.pom'.
> Connect to localhost:3120 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1] failed: Connection refused

Here, the proxy server rejects the connection because the proxy port definition in the command line argument is wrong though the gradle.properties file proxy port value is right. The command line parameters definition takes precedence over gradle.properties values.

在这里，代理服务器拒绝连接，因为 命令行参数中的代理端口定义是错误的，而 gradle.properties 文件中的代理端口值是正确的。命令行参数定义优先于 gradle.properties 值。

Furthermore, the proxy server will reject the connection when the authentication credentials are wrong in a secured proxy server. To avoid these errors, it’s required to check the configuration properly.

此外，在安全代理服务器中，如果验证凭据有误，代理服务器会拒绝连接。为了避免这些错误，需要正确检查配置。

4. Conclusion

4.结论

In this article, we learned how to configure Gradle to work behind a proxy by defining the required system properties in a gradle.properties file. Also, we saw how to define the system properties via the terminal. Finally, we saw a few easy-to-make errors and how to avoid them.

在本文中，我们学习了如何在 gradle.properties 文件中定义所需的系统属性，从而配置 Gradle 在代理后工作。此外，我们还学习了如何通过终端定义系统属性。最后，我们看到了一些容易犯的错误以及如何避免它们。

As always, the complete example code is available over on GitHub.

与往常一样，完整的示例代码可在 GitHub 上获取。