Eğer Android Studio, Gradle senkronizasyon aşamasında "donuyorsa", SDK Manager bileşenleri yüklemiyorsa ve Maven Central'dan bağımlılıklar indirilemiyorsa — %80 oranında sorun kodda değil, ağ ortamındadır. Kurumsal güvenlik duvarı, VPN, depo IP'sinin engellenmesi veya doğrudan internet erişiminin olmaması — bunların hepsi, IDE, Gradle ve SDK Manager'da doğru proxy ayarları ile çözülebilir. Proxy'yi doğru ve gereksiz senkronizasyon hataları olmadan nasıl ayarlayacağımızı inceleyelim.
Android geliştiricisi için proxy neden gereklidir
Proxy, Android Studio ile birkaç senaryoda kullanılır. İlk senaryo, doğrudan internet erişiminin kapalı olduğu kurumsal ağlardır; tüm trafik, google(), mavenCentral() ve dl.google.com'a yapılan istekler dahil, şirketin proxy sunucusu üzerinden gitmelidir. İkinci senaryo, bölgesel kısıtlamaların aşılmasıdır: bazı SDK bileşenleri, Google Play Services API'leri veya üçüncü taraf depoları belirli ülkelerden doğrudan erişilemez, bu nedenle geliştirici trafiği başka bir coğrafi konumun IP'si üzerinden yönlendirmek zorundadır.
Üçüncü senaryo, uygulamanın coğrafi olarak bağımlı işlevselliğinin test edilmesidir. Uygulama, kullanıcının ülkesine bağlı olarak farklı içerikler, fiyatlar veya reklamlar gösteriyorsa, QA mühendisleri ve geliştiriciler, sürüm beklemeden, derleme ve hata ayıklama aşamasında gerekli bölgeden istekleri taklit etmelidir. Dördüncü senaryo, belirli hizmetlere sınırlı erişimi olan veri merkezlerinde fiziksel olarak bulunan CI/CD koşucuları ile çalışmaktır; proxy, gerekli depoya veya API'ye "ulaşmanın" tek yolu haline gelir.
Tüm bu durumlarda mantık aynıdır: Gradle, SDK Manager ve IDE'nin proxy sunucusunun adresini, portunu ve gerekirse kimlik bilgilerini bilmesi gerekir; aksi takdirde, proje senkronizasyonu zaman aşımı veya bağlantı hataları ile başarısız olur.
Geliştirme için hangi proxy türü seçilmeli
Geliştirme ve test aşamasında anonimlikten çok, bağlantının istikrarı ve uzun yüklemeler sırasında düşük kesinti oranı önemlidir (örneğin, Android SDK Platform Araçları yüzlerce megabayt ağırlığındadır). Aşağıda, Android geliştiricisinin görevlerine uygun proxy türlerinin karşılaştırması bulunmaktadır.
| Proxy Türü | Ne zaman kullanılmalı | Özellikler |
|---|---|---|
| Veri merkezi proxy'leri | SDK indirme, Gradle senkronizasyonu, CI/CD | Yüksek hız, düşük maliyet, büyük indirmeler için istikrarlı |
| Konut proxy'leri | Coğrafi bağımlı API ve içerik testleri | Gerçek kullanıcı IP'leri, hizmetler tarafından daha az engellenir |
| Mobil proxy'ler | Belirli bir ülkeden mobil API ve push bildirimleri test etme | İletişim operatörlerinin IP'leri, gerçek mobil trafiğe en yakın olanlar |
Gradle'ın temiz senkronizasyonu ve bağımlılıkların indirilmesi için en mantıklısı veri merkezi proxy'leri kullanmaktır — bunlar gereksiz gecikmeler olmadan istikrarlı yüksek hız sağlar. Ancak, görev bir uygulamanın arka ucunun başka bir ülkeden bir kullanıcıya nasıl yanıt verdiğini kontrol etmekse, konut veya mobil IP'ler daha uygun olacaktır.
gradle.properties dosyasında proxy ayarları
gradle.properties dosyası, Gradle'ın HTTP ve HTTPS bağlantıları için proxy ayarlarını aradığı ana yerdir. Dosya, projenin kökünde bulunabilir (sadece onun için geçerli) veya global dizinde ~/.gradle/gradle.properties (makinedeki tüm projeler için geçerli) bulunabilir. Proxy üzerinden sürekli çalışmak için ikinci seçenek önerilir.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# isteğe bağlı — doğrudan giden istisnalar
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
Dosyayı kaydettikten sonra File → Sync Project with Gradle Files veya araç çubuğundaki "fil" simgesine tıklamayı unutmayın. IDE değişiklikleri otomatik olarak almadıysa, Android Studio'yu yeniden başlatın — bazen proxy ayarlarının önbelleği, Gradle Daemon sürecinin yeniden başlatılmasını gerektirir.
Önemli bir nokta: systemProp.* parametreleri, Gradle'ın çalıştığı JVM seviyesinde geçerlidir, bu nedenle yalnızca bağımlılıkların indirilmesini değil, aynı zamanda build betikleri içindeki herhangi bir ağ isteğini de etkiler (örneğin, harici bir API'yi çağıran özel bir Gradle göreviniz varsa).
Android Studio'da proxy ayarları
Gradle dışında, IDE'nin kendi ağ ayarları vardır — bunlar eklentilerin çalışması, IDE güncellemeleri, lisans kontrolü ve Google'dan gelen ipuçları gibi bazı özellikler için gereklidir. Bunları File → Settings → Appearance & Behavior → System Settings → HTTP Proxy üzerinden açabilirsiniz (macOS'ta Android Studio → Preferences).
Açılan pencerede Manual proxy configuration seçeneğini seçin, host ve portu belirtin, gerekirse Proxy authentication seçeneğini işaretleyin ve kullanıcı adı ile şifreyi yazın. Ayrıca, bağlantının düzgün geçtiğinden emin olmak için test URL'si (örneğin, https://dl.google.com) girip Check connection butonuna tıklayabileceğiniz kullanışlı bir düğme bulunmaktadır.
Farkı anlamak önemlidir
Ayarlar'daki HTTP Proxy ayarları IDE'yi (eklenti, güncellemeler) etkilerken, gradle.properties'deki parametreler Gradle derleme sürecini etkiler. Bunlar bağımsız mekanizmalardır ve proxy üzerinden tam işlevsellik için genellikle her ikisinin de ayarlanması gerekir.
SDK Manager için proxy
SDK Manager, Android platformlarını, build-tools, emülatörleri ve sistem görüntülerini indiren ayrı bir bileşendir. Kendi proxy yapılandırması vardır; bu yapılandırma, tarihsel olarak IDE'nin aynı sistem ayarları üzerinden belirlenir, ancak standalone sdkmanager (komut satırından bir CLI aracı) ile çalışırken, parametrelerin açıkça JVM bayrakları ile iletilmesi gerekir.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Eğer sdkmanager bir betik aracılığıyla başlatılıyorsa, proxy'yi doğrudan JAVA_OPTS ortam değişkeninde belirtebilirsiniz; bu değişken, yürütülebilir dosya tarafından okunur:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Sık yapılan bir hata, Android Studio'da proxy ayarlarını yapmak ama sdkmanager veya avdmanager gibi standalone araçları unutmaktır; bu araçlar ayrı bir Java süreci başlatır ve IDE ayarlarını otomatik olarak miras almaz.
gradlew için proxy ve ortam değişkenleri
Eğer projeyi IDE'yi atlayarak terminalden ./gradlew ile derliyorsanız (örneğin, CI/CD'de veya sadece alışkanlıkla), proxy'yi gradle.properties dosyasını değiştirmeden doğrudan komutla iletebilirsiniz:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Sürekli kullanım için, kabuk profilinde GRADLE_OPTS ortam değişkenini ayarlamak daha uygundur (.bashrc, .zshrc Linux/macOS için veya Windows ortam değişkenleri):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Bu, GitHub Actions, GitLab CI veya Jenkins gibi CI koşucularında özellikle yararlıdır; burada ortam değişkenleri bir kez iş tanımı seviyesinde ayarlanır ve sonraki tüm derleme adımları tarafından otomatik olarak alınır, proje dosyalarını düzenleme gereği olmadan.
Yaygın senkronizasyon hataları ve çözümleri
Proxy ayarlarını yaparken geliştiricilerin karşılaştığı en yaygın hataları ve bunların nasıl giderileceğine dair somut adımları inceleyelim.
| Hata | Sebep | Çözüm |
|---|---|---|
| Bağlantı zaman aşımına uğradı | Proxy belirtilmemiş veya erişilemez | gradle.properties dosyasındaki host/port'u kontrol edin, proxy'nin erişilebilirliğini curl ile test edin |
| 407 Proxy Kimlik Doğrulaması Gerekli | Kullanıcı adı/şifre verilmedi | systemProp.http.proxyUser ve systemProp.http.proxyPassword ekleyin |
| Host çözülemedi | DNS çözümü proxy üzerinden gitmiyor | SOCKS5 için http yerine socksProxyHost kullanın |
| 'https://dl.google.com/...' alınamadı | Gradle ayarları yapıldı, ancak IDE'de yapılmadı (veya tam tersi) | Her iki yerde de ayarları senkronize edin: Settings → HTTP Proxy ve gradle.properties |
| SSL el sıkışması başarısız oldu | Proxy SSL'yi yakalıyor (kurumsal MITM) | Proxy'nin kök sertifikasını JDK'nızın cacerts dosyasına içe aktarın |
Eğer hata, belirli Maven artefaktlarını indirirken ortaya çıkıyorsa (örneğin, androidx.* kütüphaneleri), Gradle'ın genişletilmiş günlük kaydını ./gradlew build --info komutuyla geçici olarak etkinleştirmek faydalı olabilir — çıktıda, bağlantının kesildiği isteğin ne olduğunu ve sunucunun hangi yanıt kodunu döndürdüğünü göreceksiniz.
Kimlik doğrulamalı proxy: kullanıcı adı ve şifre
Eğer proxy kimlik doğrulaması gerektiriyorsa (bu, ücretli proxy hizmetleri ve kurumsal geçitler için standart bir durumdur), gradle.properties dosyasına iki satır daha eklemeniz gerekir:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Proxy şifresini açık bir şekilde proje içindeki gradle.properties dosyasında saklamak, versiyon kontrol sistemine girmesi nedeniyle kötü bir uygulamadır. Git'e eklenmeyecek kullanıcı ana dizinindeki global bir dosyayı kullanın veya şifreyi CI/CD aşamasında ortam değişkenleri aracılığıyla geçirin, böylece gizli bilgiler depo içine sızmaz.
IP değişimi gerektiren senaryolar için (örneğin, farklı adreslerden API limitlerini test etmek), adres havuzuna sahip ve tek bir kullanıcı adı ile hizmet veren proxy hizmetlerini almak daha uygundur — böylece değişim sağlayıcı tarafında ayarlanır ve gradle.properties dosyasında yalnızca oturum portu değiştirilir, tüm projenin yapılandırmasını yeniden yazmaya gerek kalmaz.
Tanı kontrol listesi
Eğer tüm ayarlara rağmen senkronizasyon hala başarısız oluyorsa, aşağıdaki maddeleri sırayla kontrol edin:
- Proxy'nin doğrudan erişilebilirliğini
curl -x http://proxy.example.com:8080 https://dl.google.comkomutuyla kontrol edin - Hem Settings → HTTP Proxy'de hem de gradle.properties dosyasında ayarların yapıldığından emin olun
- Gradle önbelleğini temizleyin:
./gradlew --stopve.gradle/cachesklasörünü silin - Dosyada gereksiz boşluklar ve değerlerin etrafında tırnak olmadığından emin olun
- SOCKS5 kullanılıyorsa — http.proxyHost yerine socksProxyHost/socksProxyPort yazın
- Kurumsal MITM proxy'leri için sertifikayı JDK'nın güvenilir sertifikalar deposuna içe aktarın (keytool -import)
- properties dosyalarında herhangi bir değişiklikten sonra Android Studio ve Gradle Daemon'ı yeniden başlatın
Sonuç
Android geliştirmede proxy ayarları, üç seviyede çalışmayı gerektirir: Android Studio'nun sistem ayarları IDE için, gradle.properties dosyasındaki systemProp parametreleri derleme süreci için ve sdkmanager gibi standalone araçlar için ayrı bir yapılandırma. Çoğu senkronizasyon hatası, bu seviyelerden birinin ayarlandığı, diğerinin unutulduğu veya kimlik doğrulaması gerektiren bir proxy'nin ayarlanmadığı durumlarda ortaya çıkar.
Eğer amacınız, iş yerindeki proxy üzerinden bağımlılıkları ve SDK bileşenlerini istikrarlı bir şekilde indirmekse, veri merkezi proxy'leri bu iş için mükemmeldir — hızlıdırlar ve büyük indirmelerde gereksiz gecikmeler yaratmazlar. Ancak, uygulamanın belirli bir ülkeden veya mobil operatörden bir kullanıcı için nasıl davrandığını test etmek gerekiyorsa, konut proxy'leri veya mobil IP'ler daha gerçekçi bir hizmet davranışı sunar.