← Voltar ao blog

Como configurar proxy no Android Studio e Gradle: gradle.properties e SDK Manager

Analisamos como configurar corretamente o proxy no gradle.properties, configurar o SDK Manager e o Android Studio, além de resolver os erros de sincronização mais comuns do Gradle.

📅13 de novembro de 2026

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