Si Android Studio se "congela" en la etapa de sincronización de Gradle, el SDK Manager no carga componentes y las dependencias de Maven Central no se descargan, en el 80% de los casos el problema no está en el código, sino en el entorno de red. Un firewall corporativo, VPN, bloqueo de IP del repositorio o simplemente la falta de acceso directo a Internet — todo esto se resuelve con la configuración adecuada del proxy en tres niveles: IDE, Gradle y SDK Manager. Vamos a ver cómo configurar el proxy correctamente y sin errores de sincronización innecesarios.
¿Por qué necesita un proxy un desarrollador de Android?
Más comúnmente, el proxy se utiliza en conjunto con Android Studio en varios escenarios. El primero es en una red corporativa, donde el acceso directo a Internet está cerrado, y todo el tráfico, incluidas las solicitudes a google(), mavenCentral() y dl.google.com, debe pasar por el servidor proxy de la empresa. El segundo es para eludir restricciones regionales: algunos componentes de SDK, API de Google Play Services o repositorios de terceros no están disponibles directamente desde ciertos países, y el desarrollador se ve obligado a enrutar el tráfico a través de una IP de otra geolocalización.
El tercer escenario es la prueba de funcionalidad geo-dependiente de la aplicación. Si la aplicación muestra contenido, precios o publicidad diferentes según el país del usuario, los ingenieros de QA y los desarrolladores necesitan emular solicitudes desde la región deseada incluso en la etapa de construcción y depuración, sin esperar al lanzamiento. El cuarto es trabajar con runners de CI/CD que están físicamente ubicados en centros de datos con acceso limitado a ciertos servicios, y el proxy se convierte en la única forma de "acceder" al repositorio o API necesarios.
En todos estos casos, la lógica es la misma: Gradle, SDK Manager y la propia IDE deben conocer la dirección, el puerto y, si es necesario, las credenciales del servidor proxy; de lo contrario, la sincronización del proyecto fallará con timeouts o errores de conexión.
Qué tipo de proxy elegir para el desarrollo
Para el desarrollo y las pruebas, no es tanto la anonimidad lo que importa, sino la estabilidad de la conexión y un bajo porcentaje de interrupciones durante las largas descargas (por ejemplo, las herramientas de plataforma de Android SDK pesan cientos de megabytes). A continuación, se presenta una comparación de tipos de proxy aplicables a las tareas del desarrollador de Android.
| Tipo de proxy | Cuándo usar | Características |
|---|---|---|
| Proxies de centros de datos | Descarga de SDK, sincronización de Gradle, CI/CD | Alta velocidad, bajo costo, estables para grandes descargas |
| Proxies residenciales | Pruebas de API y contenido geo-dependiente | IP de usuarios reales, bloqueados menos frecuentemente por los servicios |
| Proxies móviles | Pruebas de API móviles y notificaciones push desde un país específico | IP de operadores de telecomunicaciones, muy cercanas al tráfico móvil real |
Para una sincronización limpia de Gradle y la descarga de dependencias, es más sensato utilizar proxies de centros de datos — ofrecen una velocidad alta y estable sin retrasos innecesarios. Sin embargo, si la tarea es verificar cómo responde el backend de la aplicación a un usuario de otro país, es mejor optar por IP residenciales o móviles.
Configuración del proxy en gradle.properties
El archivo gradle.properties es el principal lugar donde Gradle busca configuraciones de proxy para conexiones HTTP y HTTPS. El archivo puede estar en la raíz del proyecto (solo afecta a este) o en el directorio global ~/.gradle/gradle.properties (afecta a todos los proyectos en la máquina). Para un funcionamiento constante a través del proxy, se recomienda la segunda opción.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# opcional — excepciones que van directamente, omitiendo el proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
Después de guardar el archivo, asegúrese de hacer clic en File → Sync Project with Gradle Files o en el icono de "elefante" en la barra de herramientas. Si la IDE no detecta los cambios automáticamente, reinicie Android Studio — a veces, la caché de configuraciones del proxy se mantiene hasta que se reinicia el proceso Gradle Daemon.
Un matiz importante: los parámetros systemProp.* actúan a nivel de la JVM en la que se ejecuta Gradle, por lo que afectan no solo a la descarga de dependencias, sino también a cualquier solicitud de red dentro de los scripts de construcción (por ejemplo, si tiene una tarea Gradle personalizada que llama a una API externa).
Configuración del proxy en Android Studio
Además de Gradle, la IDE tiene sus propias configuraciones de red — necesarias para el funcionamiento de plugins, actualizaciones de la IDE, verificación de licencias y algunas funciones como sugerencias de Google. Puede abrirlas a través de File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (en macOS — Android Studio → Preferences).
En la ventana que se abre, seleccione Manual proxy configuration, indique el host y el puerto, y si es necesario, marque Proxy authentication e ingrese el usuario y la contraseña. También hay un botón conveniente Check connection — ingrese una URL de prueba (por ejemplo, https://dl.google.com) y presione para asegurarse de que la conexión se realiza correctamente antes de iniciar la sincronización completa del proyecto.
Es importante entender la diferencia
Las configuraciones de HTTP Proxy en Settings afectan a la propia IDE (plugins, actualizaciones), mientras que los parámetros en gradle.properties afectan al proceso de construcción de Gradle. Estos son dos mecanismos independientes, y para un funcionamiento completo a través del proxy, generalmente es necesario configurar ambos.
Proxy para SDK Manager
SDK Manager es un componente separado que descarga plataformas de Android, herramientas de construcción, emuladores y imágenes del sistema. Tiene su propia configuración de proxy, que históricamente se establece a través de las mismas configuraciones del sistema de la IDE, pero al trabajar a través del sdkmanager independiente (una herramienta CLI desde la línea de comandos), los parámetros deben pasarse explícitamente a través de las banderas de JVM.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Si el sdkmanager se ejecuta a través de un script, puede especificar el proxy directamente en la variable de entorno JAVA_OPTS, que es leída por el archivo ejecutable:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Un error común es configurar el proxy en Android Studio, pero olvidar las utilidades independientes como sdkmanager o avdmanager, que se ejecutan en un proceso Java separado y no heredan automáticamente las configuraciones de la IDE.
Proxy para gradlew y variables de entorno
Si está construyendo el proyecto desde la terminal a través del envoltorio ./gradlew, omitiendo la IDE (por ejemplo, en CI/CD o simplemente por costumbre), puede pasar el proxy directamente en el comando sin modificar gradle.properties:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Para un uso constante, es más conveniente establecer la variable de entorno GRADLE_OPTS en el perfil de la shell (.bashrc, .zshrc para Linux/macOS o variables de entorno de Windows):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Esto es especialmente útil en runners de CI como GitHub Actions, GitLab CI o Jenkins, donde las variables de entorno se establecen una vez a nivel de trabajo y son automáticamente recogidas por todos los pasos posteriores de la construcción, sin necesidad de editar los archivos del proyecto.
Errores típicos de sincronización y su solución
Vamos a revisar los errores más comunes que enfrentan los desarrolladores al configurar el proxy y los pasos específicos para solucionarlos.
| Error | Causa | Solución |
|---|---|---|
| Connection timed out | Proxy no especificado o no disponible | Verifique el host/puerto en gradle.properties, pruebe la disponibilidad del proxy a través de curl |
| 407 Proxy Authentication Required | No se proporcionaron usuario/contraseña | Agregue systemProp.http.proxyUser y systemProp.http.proxyPassword |
| Unable to resolve host | La resolución DNS no pasa a través del proxy | Utilice socksProxyHost en lugar de http para SOCKS5 con DNS remoto |
| Could not GET 'https://dl.google.com/...' | Configuraciones de Gradle establecidas, pero no en la IDE (o viceversa) | Sincronice las configuraciones en ambos lugares: Settings → HTTP Proxy y gradle.properties |
| SSL handshake failed | El proxy intercepta SSL (MITM corporativo) | Importe el certificado raíz del proxy en cacerts de su JDK |
Si el error ocurre específicamente al descargar ciertos artefactos de Maven (por ejemplo, bibliotecas androidx.*), es útil habilitar temporalmente el registro extendido de Gradle con el comando ./gradlew build --info — en la salida se verá en qué solicitud específica se produce la interrupción de la conexión y qué código de respuesta devuelve el servidor.
Proxy con autenticación: usuario y contraseña
Si el proxy requiere autenticación (esta es una situación estándar para servicios de proxy de pago y gateways corporativos), es necesario agregar dos líneas más en gradle.properties:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Almacenar la contraseña del proxy en texto claro en el gradle.properties del proyecto, que se incluye en el sistema de control de versiones, es una mala práctica. Utilice un archivo global en el directorio personal del usuario, que no se comite en Git, o pase la contraseña a través de variables de entorno en la etapa de CI/CD, para que los secretos no se filtren en el repositorio.
Para escenarios donde se requiere la rotación de IP (por ejemplo, pruebas de límites de API desde diferentes direcciones), es más conveniente utilizar servicios de proxy con un grupo de direcciones listo y un único usuario — así, la rotación se configura del lado del proveedor, y en gradle.properties solo se cambia el puerto de la sesión, sin reescribir la configuración de todo el proyecto.
Lista de verificación de diagnóstico
Si después de todas las configuraciones la sincronización sigue fallando, siga los siguientes puntos en orden:
- Verifique la disponibilidad del proxy directamente con el comando
curl -x http://proxy.example.com:8080 https://dl.google.com - Asegúrese de que las configuraciones estén establecidas tanto en Settings → HTTP Proxy como en gradle.properties al mismo tiempo
- Limpiar la caché de Gradle:
./gradlew --stopy elimine la carpeta.gradle/caches - Verifique que no haya espacios o comillas adicionales alrededor de los valores de host/puerto en el archivo
- Si se utiliza SOCKS5, especifique socksProxyHost/socksProxyPort en lugar de http.proxyHost
- Para proxies corporativos MITM, importe el certificado en el almacén de certificados de confianza de JDK (keytool -import)
- Reinicie Android Studio y Gradle Daemon después de cualquier cambio en los archivos de properties
Conclusión
Configurar el proxy en el desarrollo de Android es un trabajo que se realiza en tres niveles: configuraciones del sistema de Android Studio para la propia IDE, parámetros systemProp en gradle.properties para el proceso de construcción, y una configuración separada para utilidades independientes como sdkmanager. La mayoría de los errores de sincronización surgen precisamente porque uno de los niveles está configurado y el otro se olvida, o debido a la falta de autorización en el proxy que la requiere.
Si la tarea es simplemente descargar dependencias y componentes de SDK de manera estable a través de un proxy de trabajo, los proxies de centros de datos son una excelente opción — son rápidos y no generan retrasos innecesarios en grandes descargas. Y si necesita probar cómo se comporta la aplicación para un usuario de un país específico o desde un operador móvil, considere los proxies residenciales o IP móviles — ofrecen una imagen más realista del comportamiento de los servicios en diferentes regiones.