Se Android Studio "si blocca" durante la fase di sincronizzazione di Gradle, SDK Manager non carica i componenti e le dipendenze da Maven Central non vengono scaricate — nell'80% dei casi il problema non è nel codice, ma nell'ambiente di rete. Firewall aziendale, VPN, blocco IP del repository o semplicemente mancanza di accesso diretto a Internet — tutto questo può essere risolto con la corretta configurazione del proxy a tre livelli: IDE, Gradle e SDK Manager. Analizziamo come configurare correttamente il proxy senza errori di sincronizzazione.
Perché uno sviluppatore Android ha bisogno di un proxy
Il proxy viene utilizzato più frequentemente in combinazione con Android Studio in diversi scenari. Il primo è la rete aziendale, dove l'accesso diretto a Internet è bloccato e tutto il traffico, comprese le richieste a google(), mavenCentral() e dl.google.com, deve passare attraverso il server proxy dell'azienda. Il secondo è il bypass delle restrizioni regionali: alcuni componenti SDK, API di Google Play Services o repository di terze parti non sono accessibili direttamente da determinati paesi, e lo sviluppatore è costretto a instradare il traffico attraverso un IP di un'altra geolocalizzazione.
Il terzo scenario è il test delle funzionalità geo-dipendenti dell'applicazione. Se l'app mostra contenuti, prezzi o pubblicità diversi a seconda del paese dell'utente, gli ingegneri QA e gli sviluppatori devono emulare le richieste dalla regione desiderata già nella fase di compilazione e debug, senza aspettare il rilascio. Il quarto è il lavoro con i runner CI/CD, che sono fisicamente posizionati in data center con accesso limitato a determinati servizi, e il proxy diventa l'unico modo per "raggiungere" il repository o l'API desiderata.
In tutti questi casi la logica è la stessa: Gradle, SDK Manager e l'IDE stesso devono conoscere l'indirizzo, la porta e, se necessario, le credenziali del server proxy, altrimenti la sincronizzazione del progetto fallirà con timeout o errori di connessione.
Quale tipo di proxy scegliere per lo sviluppo
Per lo sviluppo e il testing, non è tanto l'anonimato a essere importante, quanto la stabilità della connessione e la bassa percentuale di interruzioni durante i lunghi download (ad esempio, gli strumenti della piattaforma Android SDK pesano centinaia di megabyte). Di seguito è riportato un confronto dei tipi di proxy in relazione alle esigenze dello sviluppatore Android.
| Tipo di proxy | Quando utilizzare | Caratteristiche |
|---|---|---|
| Proxy di data center | Download SDK, sincronizzazione Gradle, CI/CD | Alta velocità, basso costo, stabili per grandi download |
| Proxy residenziali | Testing di API e contenuti geo-dipendenti | IP di utenti reali, bloccati meno frequentemente dai servizi |
| Proxy mobili | Testing di API mobili e notifiche push da un paese specifico | IP di operatori di telecomunicazioni, massimamente vicini al traffico mobile reale |
Per una sincronizzazione pulita di Gradle e il download delle dipendenze, è più ragionevole utilizzare proxy di data center — offrono una velocità alta e stabile senza ritardi inutili. Se invece l'obiettivo è verificare come il backend dell'app risponde a un utente di un altro paese, sono più adatti gli IP residenziali o mobili.
Configurazione del proxy in gradle.properties
Il file gradle.properties è il principale luogo in cui Gradle cerca le impostazioni del proxy per le connessioni HTTP e HTTPS. Il file può trovarsi nella radice del progetto (vale solo per quel progetto) o nella directory globale ~/.gradle/gradle.properties (vale per tutti i progetti sulla macchina). Per un funzionamento continuo tramite proxy, si consiglia la seconda opzione.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# opzionale — eccezioni che vanno direttamente, bypassando il proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
Dopo aver salvato il file, assicurati di cliccare su File → Sync Project with Gradle Files o sull'icona "elefante" nella barra degli strumenti. Se l'IDE non ha rilevato le modifiche automaticamente, riavvia Android Studio — a volte la cache delle impostazioni del proxy persiste fino al riavvio del processo Gradle Daemon.
Un punto importante: i parametri systemProp.* agiscono a livello di JVM in cui viene eseguito Gradle, quindi influenzano non solo il download delle dipendenze, ma anche qualsiasi richiesta di rete all'interno degli script di build (ad esempio, se hai un'attività Gradle personalizzata che chiama un'API esterna).
Configurazione del proxy in Android Studio
Oltre a Gradle, l'IDE ha le proprie impostazioni di rete — necessarie per il funzionamento dei plugin, aggiornamenti dell'IDE, verifica delle licenze e alcune funzionalità come suggerimenti da Google. Puoi aprirle tramite File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (su macOS — Android Studio → Preferences).
Nella finestra aperta, seleziona Manual proxy configuration, specifica l'host e la porta, se necessario seleziona Proxy authentication e inserisci nome utente e password. C'è anche un comodo pulsante Check connection — inserisci un URL di test (ad esempio, https://dl.google.com) e cliccalo per assicurarti che la connessione funzioni correttamente prima di avviare la sincronizzazione completa del progetto.
È importante capire la differenza
Le impostazioni HTTP Proxy in Settings influenzano l'IDE stessa (plugin, aggiornamenti), mentre i parametri in gradle.properties influenzano il processo di build di Gradle. Questi sono due meccanismi indipendenti, e per un funzionamento completo dietro un proxy è solitamente necessario configurare entrambi.
Proxy per SDK Manager
SDK Manager è un componente separato che scarica le piattaforme Android, gli strumenti di build, gli emulatori e le immagini di sistema. Ha una propria configurazione del proxy, che storicamente è impostata tramite le stesse impostazioni di sistema dell'IDE, ma quando si lavora tramite sdkmanager standalone (utility CLI da riga di comando), i parametri devono essere passati esplicitamente tramite i flag JVM.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Se sdkmanager viene avviato tramite uno script, puoi specificare il proxy direttamente nella variabile di ambiente JAVA_OPTS, che viene letta dal file eseguibile:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Un errore comune è configurare il proxy in Android Studio, ma dimenticare le utility standalone come sdkmanager o avdmanager, che vengono eseguite in un processo Java separato e non ereditano automaticamente le impostazioni dell'IDE.
Proxy per gradlew e variabili di ambiente
Se stai compilando il progetto dal terminale tramite il wrapper ./gradlew, bypassando l'IDE (ad esempio, in CI/CD o semplicemente per abitudine), puoi passare il proxy direttamente nel comando senza modificare gradle.properties:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Per un utilizzo costante, è più comodo impostare la variabile di ambiente GRADLE_OPTS nel profilo della shell (.bashrc, .zshrc per Linux/macOS o variabili di ambiente di Windows):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Questo è particolarmente utile nei runner CI di GitHub Actions, GitLab CI o Jenkins, dove le variabili di ambiente vengono impostate una volta a livello di job e vengono automaticamente rilevate da tutti i passaggi successivi della build, senza la necessità di modificare i file del progetto.
Errori di sincronizzazione comuni e le loro soluzioni
Analizziamo gli errori più comuni che gli sviluppatori incontrano durante la configurazione del proxy e i passaggi specifici per risolverli.
| Errore | Causa | Soluzione |
|---|---|---|
| Connection timed out | Proxy non specificato o non disponibile | Controlla host/port in gradle.properties, testa la disponibilità del proxy tramite curl |
| 407 Proxy Authentication Required | Nome utente/password non forniti | Aggiungi systemProp.http.proxyUser e systemProp.http.proxyPassword |
| Unable to resolve host | Il DNS non viene risolto tramite il proxy | Usa socksProxyHost invece di http per SOCKS5 con DNS remoto |
| Could not GET 'https://dl.google.com/...' | Le impostazioni di Gradle sono impostate, ma nell'IDE no (o viceversa) | Sincronizza le impostazioni in entrambi i luoghi: Settings → HTTP Proxy e gradle.properties |
| SSL handshake failed | Il proxy intercetta SSL (MITM aziendale) | Importa il certificato radice del proxy in cacerts della tua JDK |
Se l'errore si verifica durante il download di specifici artefatti Maven (ad esempio, librerie androidx.*), è utile attivare temporaneamente il log dettagliato di Gradle con il comando ./gradlew build --info — nell'output sarà visibile quale richiesta sta causando l'interruzione della connessione e quale codice di risposta restituisce il server.
Proxy con autenticazione: nome utente e password
Se il proxy richiede autenticazione (situazione standard per i servizi proxy a pagamento e i gateway aziendali), in gradle.properties è necessario aggiungere altre due righe:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Conservare la password del proxy in chiaro nel file gradle.properties del progetto, che viene inserito nel sistema di controllo versione, è una cattiva pratica. Utilizza un file globale nella directory home dell'utente, che non viene committato in Git, oppure passa la password tramite variabili di ambiente durante la fase di CI/CD, in modo che i segreti non trapelino nel repository.
Per scenari in cui è necessaria la rotazione degli IP (ad esempio, testare i limiti API da indirizzi diversi), è più comodo utilizzare servizi proxy con un pool di indirizzi già pronti e un'unica login — in questo modo la rotazione viene configurata dal provider, mentre in gradle.properties cambia solo la porta della sessione, senza dover riscrivere la configurazione dell'intero progetto.
Checklist di diagnostica
Se dopo tutte le configurazioni la sincronizzazione continua a fallire, segui i seguenti punti in ordine:
- Controlla la disponibilità del proxy direttamente con il comando
curl -x http://proxy.example.com:8080 https://dl.google.com - Assicurati che le impostazioni siano presenti sia in Settings → HTTP Proxy che in gradle.properties contemporaneamente
- Pulisci la cache di Gradle:
./gradlew --stope rimuovi la cartella.gradle/caches - Controlla che nel file non ci siano spazi o virgolette in eccesso attorno ai valori host/port
- Se utilizzi SOCKS5 — specifica socksProxyHost/socksProxyPort invece di http.proxyHost
- Per i proxy aziendali MITM, importa il certificato nel keystore dei certificati fidati della JDK (keytool -import)
- Riavvia Android Studio e Gradle Daemon dopo qualsiasi modifica nei file properties
Conclusione
La configurazione del proxy nello sviluppo Android è un lavoro su tre livelli: impostazioni di sistema di Android Studio per l'IDE stesso, parametri systemProp in gradle.properties per il processo di build e una configurazione separata per utility standalone come sdkmanager. La maggior parte degli errori di sincronizzazione si verifica proprio perché uno dei livelli è configurato e l'altro è dimenticato, oppure a causa della mancanza di autorizzazione su un proxy che la richiede.
Se l'obiettivo è semplicemente scaricare stabilmente dipendenze e componenti SDK tramite un proxy funzionante, i proxy di data center sono ottimi — sono veloci e non creano ritardi inutili durante i grandi download. Se invece è necessario testare come si comporta l'app per un utente di un paese specifico o da un operatore mobile, dai un'occhiata ai proxy residenziali o agli IP mobili — offrono un quadro più realistico del comportamento dei servizi in diverse regioni.