← Torna al blog

Come configurare un proxy in Android Studio e Gradle: gradle.properties e SDK Manager

Analizziamo come configurare correttamente il proxy in gradle.properties, impostare SDK Manager e Android Studio, e risolvere gli errori di sincronizzazione più comuni di Gradle.

📅13 novembre 2026

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