← Zurück zum Blog

So richten Sie einen Proxy in Android Studio und Gradle ein: gradle.properties und SDK Manager

Wir erklären, wie man Proxys korrekt in gradle.properties einträgt, den SDK Manager und Android Studio einrichtet und die häufigsten Gradle-Synchronisierungsfehler behebt.

📅13. November 2026

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 --stop und 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.