← Retour au blog

Comment configurer un proxy dans Android Studio et Gradle : gradle.properties et SDK Manager

Nous expliquons comment configurer correctement le proxy dans gradle.properties, configurer le SDK Manager et Android Studio, ainsi que résoudre les erreurs de synchronisation Gradle les plus courantes.

📅13 novembre 2026

Si Android Studio « bloque » lors de la synchronisation Gradle, que SDK Manager ne télécharge pas les composants, et que les dépendances de Maven Central ne sont pas téléchargées — dans 80% des cas, le problème ne vient pas du code, mais de l'environnement réseau. Un pare-feu d'entreprise, un VPN, un blocage IP du dépôt ou simplement l'absence d'accès direct à Internet — tout cela peut être résolu par une configuration correcte du proxy à trois niveaux : IDE, Gradle et SDK Manager. Voyons comment configurer le proxy correctement et sans erreurs de synchronisation inutiles.

Pourquoi un développeur Android a-t-il besoin d'un proxy

Le proxy est le plus souvent utilisé avec Android Studio dans plusieurs scénarios. Le premier — un réseau d'entreprise où l'accès direct à Internet est bloqué, et tout le trafic, y compris les appels à google(), mavenCentral() et dl.google.com, doit passer par le serveur proxy de l'entreprise. Le deuxième — contourner les restrictions régionales : certains composants SDK, API Google Play Services ou dépôts tiers ne sont pas accessibles directement depuis certains pays, et le développeur doit router le trafic via une IP d'une autre géolocalisation.

Le troisième scénario — tester des fonctionnalités de l'application dépendantes de la géolocalisation. Si l'application affiche un contenu, des prix ou des publicités différents en fonction du pays de l'utilisateur, les ingénieurs QA et les développeurs doivent émuler des requêtes depuis la région souhaitée dès la phase de construction et de débogage, sans attendre la sortie. Le quatrième — travailler avec des runners CI/CD qui sont physiquement situés dans des centres de données avec un accès limité à certains services, et le proxy devient le seul moyen d'accéder au dépôt ou à l'API nécessaires.

Dans tous ces cas, la logique est la même : Gradle, SDK Manager et l'IDE lui-même doivent connaître l'adresse, le port et, si nécessaire, les informations d'identification du serveur proxy, sinon la synchronisation du projet échouera avec des délais d'attente ou des erreurs de connexion.

Quel type de proxy choisir pour le développement

Pour le développement et les tests, il est plus important d'avoir une connexion stable et un faible pourcentage de coupures pendant les longs téléchargements (par exemple, les outils de plateforme Android SDK pèsent des centaines de mégaoctets). Ci-dessous se trouve une comparaison des types de proxy en fonction des tâches du développeur Android.

Type de proxy Quand utiliser Caractéristiques
Proxies de centre de données Téléchargement SDK, synchronisation Gradle, CI/CD Haute vitesse, faible coût, stables pour de gros téléchargements
Proxies résidentiels Test des API et contenus dépendants de la géolocalisation IP d'utilisateurs réels, moins souvent bloquées par les services
Proxies mobiles Test des API mobiles et des notifications push depuis un pays spécifique IP des opérateurs de télécommunication, très proches du trafic mobile réel

Pour une synchronisation Gradle propre et le téléchargement des dépendances, il est plus judicieux d'utiliser des proxies de centre de données — ils offrent une vitesse élevée et stable sans délais inutiles. Si l'objectif est de vérifier comment le backend de l'application répond à un utilisateur d'un autre pays, des IP résidentielles ou mobiles seront plus appropriées.

Configuration du proxy dans gradle.properties

Le fichier gradle.properties est l'endroit principal où Gradle recherche les paramètres de proxy pour les connexions HTTP et HTTPS. Le fichier peut se trouver à la racine du projet (il ne s'applique qu'à celui-ci) ou dans le répertoire global ~/.gradle/gradle.properties (il s'applique à tous les projets sur la machine). Pour un fonctionnement permanent via un proxy, il est recommandé d'opter pour la deuxième option.

# ~/.gradle/gradle.properties

systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

# optionnel — exceptions qui passent directement, contournant le proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

Après avoir enregistré le fichier, n'oubliez pas de cliquer sur File → Sync Project with Gradle Files ou sur l'icône « éléphant » dans la barre d'outils. Si l'IDE n'a pas pris en compte les modifications automatiquement, redémarrez Android Studio — parfois, le cache des paramètres proxy persiste jusqu'à ce que le processus Gradle Daemon soit redémarré.

Un point important : les paramètres systemProp.* agissent au niveau de la JVM dans laquelle Gradle s'exécute, donc ils influencent non seulement le téléchargement des dépendances, mais aussi toutes les requêtes réseau à l'intérieur des scripts de construction (par exemple, si vous avez une tâche Gradle personnalisée qui appelle une API externe).

Configuration du proxy dans Android Studio

En plus de Gradle, l'IDE a ses propres paramètres réseau — ils sont nécessaires pour le fonctionnement des plugins, des mises à jour de l'IDE, de la vérification des licences et de certaines fonctionnalités comme les suggestions de Google. Vous pouvez les ouvrir via File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (sur macOS — Android Studio → Preferences).

Dans la fenêtre qui s'ouvre, sélectionnez Manual proxy configuration, indiquez l'hôte et le port, et si nécessaire, cochez Proxy authentication et entrez votre identifiant et mot de passe. Il y a également un bouton pratique Check connection — entrez une URL de test (par exemple, https://dl.google.com) et cliquez dessus pour vous assurer que la connexion fonctionne correctement avant de lancer la synchronisation complète du projet.

Il est important de comprendre la différence

Les paramètres HTTP Proxy dans les paramètres affectent l'IDE elle-même (plugins, mises à jour), tandis que les paramètres dans gradle.properties affectent le processus de construction Gradle. Ce sont deux mécanismes indépendants, et pour un fonctionnement complet derrière un proxy, il est généralement nécessaire de configurer les deux.

Proxy pour SDK Manager

SDK Manager est un composant distinct qui télécharge les plateformes Android, les outils de construction, les émulateurs et les images système. Il a sa propre configuration de proxy, qui est historiquement définie via les mêmes paramètres système que l'IDE, mais lors de l'utilisation de sdkmanager autonome (outil CLI depuis la ligne de commande), les paramètres doivent être passés explicitement via les drapeaux JVM.

sdkmanager --proxy=http \
  --proxy_host=proxy.example.com \
  --proxy_port=8080 \
  --list

Si sdkmanager est lancé via un script, vous pouvez définir le proxy directement dans la variable d'environnement JAVA_OPTS, que le fichier exécutable lit :

export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

Une erreur courante consiste à configurer le proxy dans Android Studio, mais à oublier les utilitaires autonomes comme sdkmanager ou avdmanager, qui s'exécutent dans un processus Java distinct et ne prennent pas automatiquement les paramètres de l'IDE.

Proxy pour gradlew et variables d'environnement

Si vous construisez le projet depuis le terminal via l'enveloppe ./gradlew, en contournant l'IDE (par exemple, dans CI/CD ou simplement par habitude), vous pouvez transmettre le proxy directement dans la commande sans modifier gradle.properties :

./gradlew build \
  -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
  -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

Pour une utilisation permanente, il est plus pratique de définir la variable d'environnement GRADLE_OPTS dans le profil de la shell (.bashrc, .zshrc pour Linux/macOS ou variables d'environnement Windows) :

export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

Cela est particulièrement utile dans les runners CI de GitHub Actions, GitLab CI ou Jenkins, où les variables d'environnement sont définies une fois au niveau du job et sont automatiquement récupérées par toutes les étapes suivantes de la construction, sans avoir besoin de modifier les fichiers du projet.

Erreurs de synchronisation courantes et leurs solutions

Examinons les erreurs les plus fréquentes rencontrées par les développeurs lors de la configuration du proxy, ainsi que les étapes spécifiques pour les résoudre.

Erreur Cause Solution
Connection timed out Le proxy n'est pas spécifié ou est inaccessible Vérifiez l'hôte/le port dans gradle.properties, testez l'accessibilité du proxy via curl
407 Proxy Authentication Required Identifiant/mot de passe non fournis Ajoutez systemProp.http.proxyUser et systemProp.http.proxyPassword
Unable to resolve host La résolution DNS ne passe pas par le proxy Utilisez socksProxyHost à la place de http pour SOCKS5 avec DNS distant
Could not GET 'https://dl.google.com/...' Les paramètres Gradle sont définis, mais pas dans l'IDE (ou vice versa) Synchronisez les paramètres aux deux endroits : Settings → HTTP Proxy et gradle.properties
SSL handshake failed Le proxy intercepte SSL (MITM d'entreprise) Importez le certificat racine du proxy dans cacerts de votre JDK

Si l'erreur se produit lors du téléchargement d'artefacts Maven spécifiques (par exemple, des bibliothèques androidx.*), il est utile d'activer temporairement le log détaillé de Gradle avec la commande ./gradlew build --info — la sortie montrera sur quelle requête la connexion échoue et quel code de réponse le serveur renvoie.

Proxy avec authentification : identifiant et mot de passe

Si le proxy nécessite une authentification (c'est une situation standard pour les services de proxy payants et les passerelles d'entreprise), il faut ajouter deux lignes supplémentaires dans gradle.properties :

systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword

Conserver le mot de passe du proxy en clair dans le fichier gradle.properties du projet, qui est soumis à un système de contrôle de version, est une mauvaise pratique. Utilisez un fichier global dans le répertoire personnel de l'utilisateur, qui n'est pas commis dans Git, ou passez le mot de passe via des variables d'environnement lors de l'étape CI/CD, afin que les secrets ne fuient pas dans le dépôt.

Pour les scénarios nécessitant une rotation d'IP (par exemple, tester les limites de l'API depuis différentes adresses), il est plus pratique d'utiliser des services de proxy avec un pool d'adresses prêt à l'emploi et un identifiant unique — ainsi, la rotation est configurée du côté du fournisseur, et dans gradle.properties, seul le port de session change, sans réécriture de la configuration de l'ensemble du projet.

Liste de contrôle de diagnostic

Si après toutes les configurations, la synchronisation échoue toujours, passez en revue les points suivants dans l'ordre :

  • Vérifiez l'accessibilité du proxy directement avec la commande curl -x http://proxy.example.com:8080 https://dl.google.com
  • Assurez-vous que les paramètres sont définis à la fois dans Settings → HTTP Proxy et dans gradle.properties en même temps
  • Nettoyez le cache de Gradle : ./gradlew --stop et supprimez le dossier .gradle/caches
  • Vérifiez qu'il n'y a pas d'espaces ou de guillemets superflus autour des valeurs d'hôte/port dans le fichier
  • Si vous utilisez SOCKS5 — spécifiez socksProxyHost/socksProxyPort au lieu de http.proxyHost
  • Pour les proxies MITM d'entreprise, importez le certificat dans le magasin de certificats de confiance de la JDK (keytool -import)
  • Redémarrez Android Studio et Gradle Daemon après toute modification dans les fichiers properties

Conclusion

La configuration du proxy dans le développement Android implique un travail à trois niveaux : les paramètres système d'Android Studio pour l'IDE lui-même, les paramètres systemProp dans gradle.properties pour le processus de construction, et une configuration distincte pour les utilitaires autonomes comme sdkmanager. La plupart des erreurs de synchronisation surviennent précisément parce qu'un des niveaux est configuré, tandis qu'un autre est oublié, ou en raison de l'absence d'authentification sur un proxy qui l'exige.

Si l'objectif est simplement de télécharger de manière stable des dépendances et des composants SDK via un proxy de travail, les proxies de centre de données conviennent parfaitement — ils sont rapides et ne créent pas de délais supplémentaires lors de gros téléchargements. Et si vous devez tester comment l'application se comporte pour un utilisateur d'un pays spécifique ou d'un opérateur mobile, envisagez des proxies résidentiels ou des IP mobiles — ils offrent une image plus réaliste du comportement des services dans différentes régions.