Wenn Android Studio beim Gradle-Synchronisieren „hängt“, der SDK Manager keine Komponenten lädt und Abhängigkeiten aus Maven Central nicht heruntergeladen werden — in 80% der Fälle liegt das Problem nicht im Code, sondern in der Netzwerkumgebung. Eine Unternehmensfirewall, VPN, IP-Blockierung des Repositories oder einfach das Fehlen eines direkten Internetzugangs — all dies kann durch die richtige Proxy-Konfiguration auf drei Ebenen gelöst werden: IDE, Gradle und SDK Manager. Lassen Sie uns untersuchen, wie man Proxys korrekt und ohne zusätzliche Synchronisierungsfehler einträgt.
Warum Android-Entwickler einen Proxy benötigen
Proxys werden in Verbindung mit Android Studio häufig in mehreren Szenarien verwendet. Das erste — ein Unternehmensnetzwerk, in dem der direkte Internetzugang gesperrt ist und der gesamte Datenverkehr, einschließlich Anfragen an google(), mavenCentral() und dl.google.com, über den Proxy-Server des Unternehmens geleitet werden muss. Das zweite — Umgehung regionaler Einschränkungen: Einige SDK-Komponenten, die API von Google Play Services oder Drittanbieter-Repositories sind aus bestimmten Ländern nicht direkt zugänglich, und der Entwickler muss den Datenverkehr über eine IP einer anderen Geolokation leiten.
Das dritte Szenario — Testen von geoabhängigen Funktionen der Anwendung. Wenn die Anwendung je nach Land des Benutzers unterschiedliche Inhalte, Preise oder Werbung anzeigt, müssen QA-Ingenieure und Entwickler Anfragen aus der gewünschten Region bereits während des Build- und Debugging-Prozesses emulieren, ohne auf die Veröffentlichung zu warten. Das vierte — Arbeiten mit CI/CD-Runnern, die physisch in Rechenzentren mit eingeschränktem Zugang zu bestimmten Diensten untergebracht sind, und der Proxy wird zur einzigen Möglichkeit, um auf das benötigte Repository oder die API zuzugreifen.
In all diesen Fällen ist die Logik dieselbe: Gradle, SDK Manager und die IDE selbst müssen die Adresse, den Port und, falls erforderlich, die Anmeldedaten des Proxy-Servers kennen, andernfalls wird die Projektsynchronisierung mit Timeouts oder Verbindungsfehlern fehlschlagen.
Welchen Proxy-Typ für die Entwicklung wählen
Für die Entwicklung und das Testen ist nicht so sehr die Anonymität wichtig, sondern die Stabilität der Verbindung und ein niedriger Abbruchprozentsatz während langer Downloads (zum Beispiel wiegt Android SDK Platform Tools Hunderte von Megabyte). Im Folgenden finden Sie einen Vergleich der Proxy-Typen in Bezug auf die Aufgaben eines Android-Entwicklers.
| Proxy-Typ | Wann verwenden | Besonderheiten |
|---|---|---|
| Rechenzentrums-Proxys | SDK-Downloads, Gradle-Synchronisierung, CI/CD | Hohe Geschwindigkeit, niedriger Preis, stabil für große Downloads |
| Residential Proxys | Testen von geoabhängigen APIs und Inhalten | IP echter Benutzer, seltener von Diensten blockiert |
| Mobile Proxys | Testen von mobilen APIs und Push-Benachrichtigungen aus einem bestimmten Land | IP von Mobilfunkanbietern, maximal nah am echten mobilen Datenverkehr |
Für eine saubere Gradle-Synchronisierung und das Herunterladen von Abhängigkeiten ist es sinnvoll, Rechenzentrums-Proxys zu verwenden — sie bieten eine stabile hohe Geschwindigkeit ohne unnötige Verzögerungen. Wenn das Ziel jedoch darin besteht, zu überprüfen, wie das Backend der Anwendung auf einen Benutzer aus einem anderen Land reagiert, sind Residential oder mobile IPs besser geeignet.
Proxy in gradle.properties einrichten
Die Datei gradle.properties ist der Hauptort, an dem Gradle die Proxy-Einstellungen für HTTP- und HTTPS-Verbindungen sucht. Die Datei kann im Stammverzeichnis des Projekts liegen (wirkt nur für dieses) oder im globalen Verzeichnis ~/.gradle/gradle.properties (wirkt für alle Projekte auf dem Rechner). Für einen dauerhaften Betrieb über einen Proxy wird die zweite Option empfohlen.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# optional — Ausnahmen, die direkt gehen, ohne den Proxy zu verwenden
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
Nach dem Speichern der Datei klicken Sie unbedingt auf Datei → Projekt mit Gradle-Dateien synchronisieren oder auf das „Elefant“-Symbol in der Symbolleiste. Wenn die IDE die Änderungen nicht automatisch übernommen hat, starten Sie Android Studio neu — manchmal bleibt der Proxy-Einstellungs-Cache bis zum Neustart des Gradle Daemon-Prozesses bestehen.
Ein wichtiger Punkt: Die Parameter systemProp.* wirken genau auf der Ebene der JVM, in der Gradle ausgeführt wird, daher beeinflussen sie nicht nur das Herunterladen von Abhängigkeiten, sondern auch alle Netzwerk-Anfragen innerhalb der Build-Skripte (zum Beispiel, wenn Sie eine benutzerdefinierte Gradle-Aufgabe haben, die eine externe API aufruft).
Proxy in Android Studio selbst einrichten
Neben Gradle hat die IDE eigene Netzwerkeinstellungen — diese sind erforderlich für die Funktion von Plugins, IDE-Updates, Lizenzüberprüfungen und einige Funktionen wie Google-Vorschläge. Sie können sie über Datei → Einstellungen → Erscheinungsbild & Verhalten → Systemeinstellungen → HTTP-Proxy öffnen (auf macOS — Android Studio → Einstellungen).
Wählen Sie im geöffneten Fenster Manuelle Proxy-Konfiguration, geben Sie Host und Port an, und aktivieren Sie bei Bedarf Proxy-Authentifizierung und geben Sie Benutzername und Passwort ein. Dort gibt es auch einen praktischen Button Verbindung überprüfen — geben Sie eine Test-URL (zum Beispiel https://dl.google.com) ein und klicken Sie darauf, um sicherzustellen, dass die Verbindung korrekt funktioniert, bevor Sie die vollständige Projektsynchronisierung starten.
Es ist wichtig, den Unterschied zu verstehen
Die HTTP-Proxy-Einstellungen in den Einstellungen wirken sich auf die IDE selbst (Plugins, Updates) aus, während die Parameter in gradle.properties den Gradle-Build-Prozess beeinflussen. Dies sind zwei unabhängige Mechanismen, und für eine vollständige Proxy-Nutzung müssen in der Regel beide konfiguriert werden.
Proxy für SDK Manager
Der SDK Manager ist eine separate Komponente, die Android-Plattformen, Build-Tools, Emulatoren und System-Images herunterlädt. Er hat eine eigene Proxy-Konfiguration, die historisch über dieselben Systemeinstellungen der IDE festgelegt wird, aber beim Arbeiten mit dem standalone sdkmanager (CLI-Tool aus der Befehlszeile) müssen die Parameter explizit über JVM-Flags übergeben werden.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Wenn der sdkmanager über ein Skript gestartet wird, kann der Proxy direkt in der Umgebungsvariablen JAVA_OPTS angegeben werden, die von der ausführbaren Datei gelesen wird:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Ein häufiger Fehler ist es, den Proxy in Android Studio einzurichten, aber standalone-Tools wie sdkmanager oder avdmanager zu vergessen, die in einem separaten Java-Prozess gestartet werden und die IDE-Einstellungen nicht automatisch erben.
Proxy für gradlew und Umgebungsvariablen
Wenn Sie das Projekt über die Wrapper-Datei ./gradlew aus dem Terminal erstellen, ohne die IDE zu verwenden (zum Beispiel in CI/CD oder einfach aus Gewohnheit), können Sie den Proxy direkt im Befehl übergeben, ohne gradle.properties zu ändern:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Für eine dauerhafte Nutzung ist es bequemer, die Umgebungsvariable GRADLE_OPTS in Ihrem Shell-Profil (.bashrc, .zshrc für Linux/macOS oder Umgebungsvariablen für Windows) festzulegen:
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Dies ist besonders nützlich in CI-Runnern wie GitHub Actions, GitLab CI oder Jenkins, wo Umgebungsvariablen einmal auf Job-Ebene festgelegt werden und automatisch von allen nachfolgenden Build-Schritten übernommen werden, ohne dass Projektdateien bearbeitet werden müssen.
Typische Synchronisierungsfehler und deren Lösungen
Lassen Sie uns die häufigsten Fehler untersuchen, mit denen Entwickler bei der Proxy-Konfiguration konfrontiert sind, und konkrete Schritte zu deren Behebung.
| Fehler | Ursache | Lösung |
|---|---|---|
| Verbindung timed out | Proxy nicht angegeben oder nicht verfügbar | Überprüfen Sie Host/Port in gradle.properties, testen Sie die Erreichbarkeit des Proxys über curl |
| 407 Proxy-Authentifizierung erforderlich | Benutzername/Passwort nicht übergeben | Fügen Sie systemProp.http.proxyUser und systemProp.http.proxyPassword hinzu |
| Host konnte nicht aufgelöst werden | DNS-Resolving erfolgt nicht über den Proxy | Verwenden Sie socksProxyHost anstelle von http für SOCKS5 mit entferntem DNS |
| Konnte 'https://dl.google.com/...' nicht abrufen | Gradle-Einstellungen sind gesetzt, aber in der IDE nicht (oder umgekehrt) | Synchronisieren Sie die Einstellungen an beiden Stellen: Einstellungen → HTTP-Proxy und gradle.properties |
| SSL-Handshake fehlgeschlagen | Proxy fängt SSL ab (unternehmensseitiger MITM) | Importieren Sie das Root-Zertifikat des Proxys in cacerts Ihrer JDK |
Wenn der Fehler beim Herunterladen bestimmter Maven-Artefakte (z.B. androidx.* Bibliotheken) auftritt, kann es hilfreich sein, das erweiterte Gradle-Logging mit dem Befehl ./gradlew build --info vorübergehend zu aktivieren — im Output wird sichtbar, bei welcher Anfrage die Verbindung abbricht und welcher Antwortcode vom Server zurückgegeben wird.
Proxy mit Authentifizierung: Benutzername und Passwort
Wenn der Proxy eine Authentifizierung erfordert (was bei kostenpflichtigen Proxy-Diensten und Unternehmensgateways Standard ist), müssen in gradle.properties noch zwei Zeilen hinzugefügt werden:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Das Speichern des Proxy-Passworts im Klartext in der Projektdatei gradle.properties, die in das Versionskontrollsystem eingeht, ist eine schlechte Praxis. Verwenden Sie eine globale Datei im Home-Verzeichnis des Benutzers, die nicht in Git eingecheckt wird, oder übergeben Sie das Passwort über Umgebungsvariablen während des CI/CD-Prozesses, um zu verhindern, dass Geheimnisse in das Repository gelangen.
Für Szenarien, in denen eine IP-Rotation erforderlich ist (z.B. Testen von API-Limits von verschiedenen Adressen), ist es praktischer, Proxy-Dienste mit einem vorhandenen Pool von Adressen und einem einzigen Login zu verwenden — dann wird die Rotation auf der Anbieterseite konfiguriert, und in gradle.properties muss nur der Sitzungssport geändert werden, ohne die gesamte Projektkonfiguration neu zu schreiben.
Diagnoseliste
Wenn die Synchronisierung nach all diesen Einstellungen immer noch fehlschlägt, gehen Sie die folgenden Punkte der Reihe nach durch:
- Überprüfen Sie die Erreichbarkeit des Proxys direkt mit dem Befehl
curl -x http://proxy.example.com:8080 https://dl.google.com - Stellen Sie sicher, dass die Einstellungen sowohl in Einstellungen → HTTP-Proxy als auch in gradle.properties gleichzeitig eingetragen sind
- Leeren Sie den Gradle-Cache:
./gradlew --stopund löschen Sie den Ordner.gradle/caches - Überprüfen Sie, dass in der Datei keine überflüssigen Leerzeichen und Anführungszeichen um die Werte host/port vorhanden sind
- Wenn SOCKS5 verwendet wird — geben Sie socksProxyHost/socksProxyPort anstelle von http.proxyHost an
- Für Unternehmens-MITM-Proxys importieren Sie das Zertifikat in den vertrauenswürdigen Zertifikatsspeicher der JDK (keytool -import)
- Starten Sie Android Studio und den Gradle Daemon nach Änderungen in den properties-Dateien neu
Fazit
Die Einrichtung von Proxys in der Android-Entwicklung erfolgt auf drei Ebenen: die Systemeinstellungen von Android Studio für die IDE selbst, die systemProp-Parameter in gradle.properties für den Build-Prozess und eine separate Konfiguration für standalone-Tools wie sdkmanager. Die meisten Synchronisierungsfehler entstehen genau dann, wenn eine der Ebenen konfiguriert ist, die andere jedoch vergessen wurde, oder aufgrund fehlender Authentifizierung bei einem Proxy, der diese verlangt.
Wenn das Ziel einfach darin besteht, Abhängigkeiten und SDK-Komponenten stabil über einen funktionierenden Proxy herunterzuladen, sind Rechenzentrums-Proxys dafür hervorragend geeignet — sie sind schnell und verursachen keine unnötigen Verzögerungen bei großen Downloads. Wenn jedoch getestet werden muss, wie sich die Anwendung für einen Benutzer aus einem bestimmten Land oder von einem Mobilfunkanbieter verhält, sollten Sie sich Residential Proxys oder mobile IPs ansehen — sie bieten ein realistischeres Bild des Verhaltens von Diensten in verschiedenen Regionen.