Comprehensive Guide to Configuring Gradle Proxy in Android Studio

Introduction

In Android development, Gradle plays a crucial role as a build tool. However, when the development environment is behind a proxy network, Gradle often encounters connection timeout issues during initialization, typically manifested as Failed to import Gradle project: Connection timed out: connect. Such problems not only affect development efficiency but may also prevent normal project builds. Based on practical development experience, this article systematically introduces multiple methods for configuring Gradle proxy in Android Studio, particularly recommending the optimal solution of configuring through Gradle VM options.

Core Principles of Gradle Proxy Configuration

During the build process, Gradle needs to download dependency libraries and plugins from remote repositories, typically through HTTP or HTTPS protocols. When the development environment is within an enterprise network or requires proxy access to the internet, proxy parameters must be correctly configured. Gradle supports proxy configuration through system properties, including proxy host, port, user authentication information, and excluded host lists.

Key system properties for proxy configuration include:

• http.proxyHost and https.proxyHost: Specify proxy server address
• http.proxyPort and https.proxyPort: Specify proxy server port
• http.proxyUser and https.proxyUser: Proxy authentication username
• http.proxyPassword and https.proxyPassword: Proxy authentication password
• http.nonProxyHosts and https.nonProxyHosts: Lists of hosts excluded from proxy

Configuring Proxy Through Gradle VM Options (Recommended Approach)

In Android Studio, the most direct and effective method for proxy configuration is through Gradle VM options. This approach offers advantages such as simple configuration, quick activation, and no impact on project files.

Specific operation steps:

1. Open Android Studio and navigate to settings
2. Use shortcut Ctrl+Alt+S on Windows and Linux systems; access via Android Studio > Preferences on macOS
3. Navigate to Build, Execution, Deployment > Gradle options
4. Enter proxy parameters in the Gradle VM options field

Example proxy parameter configuration:

-Dhttp.proxyHost=www.somehost.org -Dhttp.proxyPort=8080 -Dhttp.proxyUser=user -Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost -Dhttps.proxyHost=www.somehost.org -Dhttps.proxyPort=8080 -Dhttps.proxyUser=user -Dhttps.proxyPassword=password -Dhttps.nonProxyHosts=localhost

Advantages of this configuration method:

• Configuration takes effect immediately without restarting Android Studio
• Parameter scope is limited to the current Gradle process, not affecting other system applications
• Easy to manage and modify, especially when proxy settings require frequent changes

Configuring Proxy Through gradle.properties File

In addition to the VM options approach, proxy can also be configured by setting system properties in the gradle.properties file. This method is suitable for scenarios requiring persistent proxy configuration.

Add the following configuration in the gradle.properties file at the project root directory:

systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=user
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=localhost
systemProp.http.auth.ntlm.domain=domain

systemProp.https.proxyHost=www.somehost.org
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=user
systemProp.https.proxyPassword=password
systemProp.https.nonProxyHosts=localhost
systemProp.https.auth.ntlm.domain=domain

For global configuration, create or modify the gradle.properties file in the .gradle folder under the user home directory:

# Example path for Windows systems
C:/Users/USERNAME/.gradle/gradle.properties

Common Issues and Solutions

During proxy configuration, developers often encounter 407 proxy authentication errors. According to the analysis in the reference article, this error is typically caused by incomplete proxy authentication information configuration.

Typical causes of 407 error:

• Only proxy host and port are configured, but authentication information is not provided
• Mismatched HTTP and HTTPS proxy configurations
• Incorrect authentication domain (NTLM domain) configuration

Solutions:

1. Ensure simultaneous configuration of proxyHost, proxyPort, proxyUser, and proxyPassword
2. Configure HTTP and HTTPS proxy parameters separately, even if they use the same proxy server
3. For environments requiring NTLM authentication, correctly set the auth.ntlm.domain property
4. Use --stacktrace, --info, or --debug options to obtain detailed error information

Best Practices for Proxy Configuration

Based on practical development experience, we summarize the following best practices for proxy configuration:

1. Prioritize Gradle VM Options: For temporary or development environment-specific proxy configurations, recommend using the VM options approach to avoid contaminating project configuration files.
2. Complete Authentication Information Configuration: Even if the proxy server does not require authentication, in some cases it is necessary to provide empty or virtual authentication parameters, as mentioned in the reference article about adding virtual proxyUser and proxyPassword.
3. Reasonably Set nonProxyHosts: Add local addresses and intranet domain names to the nonProxyHosts list to avoid unnecessary proxy forwarding:

systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.local|*.company.com
systemProp.https.nonProxyHosts=localhost|127.0.0.1|*.local|*.company.com

Conclusion

When developing Android applications in proxy network environments, correctly configuring Gradle proxy is crucial for ensuring normal project builds. This article详细介绍介绍了通过Gradle VM选项和gradle.properties文件两种主要的代理配置方式，分析了各自的优缺点和适用场景。通过Gradle VM选项配置代理是最为推荐的方法，它具有配置灵活、生效快速、不影响项目文件等优势。同时，本文还提供了常见代理问题的解决方案和最佳实践建议，帮助开发者高效解决网络连接问题，提升开发效率。

In practical applications, developers should choose appropriate proxy configuration solutions based on specific network environments and project requirements, and follow security best practices to properly manage proxy authentication information. As Android development tools continue to evolve, proxy configuration methods may change. It is recommended to stay updated with official documentation and community dynamics, and adjust configuration strategies accordingly.