Se o Android Studio "trava" na etapa de sincronização do Gradle, o SDK Manager não carrega componentes e as dependências do Maven Central não são baixadas — em 80% dos casos, o problema não está no código, mas no ambiente de rede. Firewall corporativo, VPN, bloqueio de IP do repositório ou simplesmente a falta de acesso direto à internet — tudo isso pode ser resolvido com a configuração correta do proxy em três níveis: IDE, Gradle e SDK Manager. Vamos ver como configurar o proxy corretamente e sem erros de sincronização desnecessários.
Por que um desenvolvedor Android precisa de um proxy
Na maioria das vezes, o proxy em conjunto com o Android Studio é usado em vários cenários. O primeiro — uma rede corporativa, onde o acesso direto à internet é bloqueado, e todo o tráfego, incluindo chamadas para google(), mavenCentral() e dl.google.com, deve passar pelo servidor proxy da empresa. O segundo — contornar restrições regionais: alguns componentes do SDK, API do Google Play Services ou repositórios de terceiros não estão disponíveis diretamente de determinados países, e o desenvolvedor é forçado a roteirizar o tráfego através de um IP de outra geolocalização.
O terceiro cenário — testar funcionalidades do aplicativo dependentes de geolocalização. Se o aplicativo exibe conteúdo, preços ou anúncios diferentes dependendo do país do usuário, os engenheiros de QA e desenvolvedores precisam emular solicitações da região desejada ainda na fase de construção e depuração, sem esperar pelo lançamento. O quarto — trabalhar com runners de CI/CD, que estão fisicamente localizados em data centers com acesso restrito a determinados serviços, e o proxy se torna a única maneira de "conectar-se" ao repositório ou API desejados.
Em todos esses casos, a lógica é a mesma: Gradle, SDK Manager e a própria IDE devem conhecer o endereço, a porta e, se necessário, as credenciais do servidor proxy; caso contrário, a sincronização do projeto falhará com timeouts ou erros de conexão.
Qual tipo de proxy escolher para desenvolvimento
Para desenvolvimento e teste, a anonimidade não é tão importante quanto a estabilidade da conexão e a baixa taxa de interrupções durante downloads longos (por exemplo, as ferramentas de plataforma do Android SDK pesam centenas de megabytes). Abaixo está uma comparação dos tipos de proxy aplicáveis às necessidades do desenvolvedor Android.
| Tipo de proxy | Quando usar | Características |
|---|---|---|
| Proxies de data center | Baixar SDK, sincronização do Gradle, CI/CD | Alta velocidade, baixo custo, estáveis para grandes downloads |
| Proxies residenciais | Teste de APIs e conteúdo dependentes de geolocalização | IP de usuários reais, bloqueados com menos frequência pelos serviços |
| Proxies móveis | Teste de APIs móveis e push notifications de um país específico | IP de operadoras de telecomunicações, muito próximos ao tráfego móvel real |
Para uma sincronização limpa do Gradle e download de dependências, é mais sensato usar proxies de data center — eles oferecem uma velocidade alta e estável sem atrasos desnecessários. Se a tarefa é verificar como o backend do aplicativo responde a um usuário de outro país, proxies residenciais ou móveis são mais adequados.
Configuração de proxy em gradle.properties
O arquivo gradle.properties é o principal local onde o Gradle procura as configurações de proxy para conexões HTTP e HTTPS. O arquivo pode estar localizado na raiz do projeto (apenas para ele) ou no diretório global ~/.gradle/gradle.properties (vale para todos os projetos na máquina). Para um funcionamento contínuo através do proxy, recomenda-se a segunda opção.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# opcional — exceções que vão diretamente, passando pelo proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
Após salvar o arquivo, não se esqueça de clicar em File → Sync Project with Gradle Files ou no ícone "elefante" na barra de ferramentas. Se a IDE não capturou as alterações automaticamente, reinicie o Android Studio — às vezes, o cache das configurações do proxy persiste até que o processo do Gradle Daemon seja reiniciado.
Um ponto importante: os parâmetros systemProp.* atuam exatamente no nível da JVM em que o Gradle é executado, portanto, eles afetam não apenas o download de dependências, mas também qualquer solicitação de rede dentro dos scripts de build (por exemplo, se você tiver uma tarefa Gradle personalizada que chama uma API externa).
Configuração de proxy no próprio Android Studio
Além do Gradle, a IDE possui suas próprias configurações de rede — elas são necessárias para o funcionamento de plugins, atualizações da IDE, verificação de licenças e algumas funcionalidades como dicas do Google. Você pode acessá-las através de File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (no macOS — Android Studio → Preferences).
Na janela aberta, selecione Manual proxy configuration, insira o host e a porta, e, se necessário, marque Proxy authentication e insira o login e a senha. Também há um botão conveniente Check connection — insira uma URL de teste (por exemplo, https://dl.google.com) e clique nele para garantir que a conexão está correta antes de iniciar a sincronização completa do projeto.
É importante entender a diferença
As configurações de HTTP Proxy nas Configurações afetam a própria IDE (plugins, atualizações), enquanto os parâmetros em gradle.properties afetam o processo de build do Gradle. Esses são dois mecanismos independentes, e para um funcionamento completo através do proxy, geralmente é necessário configurar ambos.
Proxy para SDK Manager
O SDK Manager é um componente separado que baixa plataformas Android, ferramentas de build, emuladores e imagens de sistema. Ele possui sua própria configuração de proxy, que historicamente é definida através das mesmas configurações de sistema da IDE, mas ao trabalhar com o sdkmanager standalone (uma ferramenta CLI a partir da linha de comando), os parâmetros precisam ser passados explicitamente através de flags JVM.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Se o sdkmanager for iniciado através de um script, você pode definir o proxy diretamente na variável de ambiente JAVA_OPTS, que é lida pelo arquivo executável:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Um erro comum é configurar o proxy no Android Studio, mas esquecer as ferramentas standalone como sdkmanager ou avdmanager, que são executadas em um processo Java separado e não herdam automaticamente as configurações da IDE.
Proxy para gradlew e variáveis de ambiente
Se você estiver construindo o projeto a partir do terminal usando a wrapper ./gradlew, ignorando a IDE (por exemplo, em CI/CD ou apenas por hábito), você pode passar o proxy diretamente no comando sem alterar gradle.properties:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Para uso contínuo, é mais conveniente definir a variável de ambiente GRADLE_OPTS no perfil do shell (.bashrc, .zshrc para Linux/macOS ou variáveis de ambiente do Windows):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Isso é especialmente útil em runners de CI como GitHub Actions, GitLab CI ou Jenkins, onde as variáveis de ambiente são definidas uma vez no nível do job e automaticamente capturadas por todos os passos subsequentes da build, sem a necessidade de editar os arquivos do projeto.
Erros comuns de sincronização e suas soluções
Vamos discutir os erros mais frequentes que os desenvolvedores enfrentam ao configurar o proxy e os passos específicos para resolvê-los.
| Erro | Causa | Solução |
|---|---|---|
| Connection timed out | Proxy não especificado ou indisponível | Verifique host/port em gradle.properties, teste a acessibilidade do proxy através do curl |
| 407 Proxy Authentication Required | Login/senha não fornecidos | Adicione systemProp.http.proxyUser e systemProp.http.proxyPassword |
| Unable to resolve host | Resolução de DNS não está passando pelo proxy | Use socksProxyHost em vez de http para SOCKS5 com DNS remoto |
| Could not GET 'https://dl.google.com/...' | Configurações do Gradle definidas, mas na IDE não (ou vice-versa) | Sincronize as configurações em ambos os locais: Settings → HTTP Proxy e gradle.properties |
| SSL handshake failed | Proxy intercepta SSL (MITM corporativo) | Importe o certificado raiz do proxy para o cacerts do seu JDK |
Se o erro ocorrer especificamente ao baixar artefatos Maven (por exemplo, bibliotecas androidx.*), é útil ativar temporariamente o log detalhado do Gradle com o comando ./gradlew build --info — na saída, será possível ver em qual solicitação específica a conexão falha e qual código de resposta o servidor retorna.
Proxy com autenticação: login e senha
Se o proxy requer autenticação (o que é uma situação padrão para serviços de proxy pagos e gateways corporativos), você deve adicionar mais duas linhas em gradle.properties:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Armazenar a senha do proxy em texto claro no gradle.properties do projeto, que vai para o sistema de controle de versões, é uma má prática. Use um arquivo global no diretório home do usuário, que não é comitado no Git, ou passe a senha através de variáveis de ambiente na fase de CI/CD, para que segredos não vazem para o repositório.
Para cenários onde a rotação de IP é necessária (por exemplo, testar limites de API de diferentes endereços), é mais conveniente usar serviços de proxy com um pool de endereços pronto e um único login — assim, a rotação é configurada do lado do provedor, e em gradle.properties apenas a porta da sessão é alterada, sem reescrever a configuração de todo o projeto.
Checklist de diagnóstico
Se, após todas as configurações, a sincronização ainda falhar, siga os seguintes passos na ordem:
- Verifique a acessibilidade do proxy diretamente com o comando
curl -x http://proxy.example.com:8080 https://dl.google.com - Certifique-se de que as configurações estão definidas tanto em Settings → HTTP Proxy quanto em gradle.properties ao mesmo tempo
- Limpe o cache do Gradle:
./gradlew --stope delete a pasta.gradle/caches - Verifique se não há espaços ou aspas extras em torno dos valores de host/port no arquivo
- Se estiver usando SOCKS5 — defina socksProxyHost/socksProxyPort em vez de http.proxyHost
- Para proxies corporativos MITM, importe o certificado para o armazenamento de certificados confiáveis do JDK (keytool -import)
- Reinicie o Android Studio e o Gradle Daemon após qualquer alteração nos arquivos properties
Conclusão
Configurar o proxy no desenvolvimento Android é um trabalho em três níveis: configurações do sistema do Android Studio para a própria IDE, parâmetros systemProp em gradle.properties para o processo de build, e uma configuração separada para ferramentas standalone como sdkmanager. A maioria dos erros de sincronização ocorre exatamente porque um dos níveis está configurado e o outro foi esquecido, ou devido à falta de autenticação no proxy que a requer.
Se a tarefa é simplesmente baixar dependências e componentes do SDK de forma estável através de um proxy de trabalho, os proxies de data center são uma excelente escolha — eles são rápidos e não criam atrasos desnecessários durante grandes downloads. E se for necessário testar como o aplicativo se comporta para um usuário de um país específico ou de uma operadora móvel, considere usar proxies residenciais ou IP móvel — eles oferecem uma visão mais realista do comportamento dos serviços em diferentes regiões.