← Kembali ke blog

Cara Mengatur Proxy di Android Studio dan Gradle: gradle.properties dan SDK Manager

Kami membahas cara menulis proxy dengan benar di gradle.properties, mengatur SDK Manager dan Android Studio, serta mengatasi kesalahan sinkronisasi Gradle yang paling umum.

📅13 November 2026

Jika Android Studio "tergantung" pada tahap sinkronisasi Gradle, SDK Manager tidak memuat komponen, dan dependensi dari Maven Central tidak diunduh — dalam 80% kasus, masalahnya bukan pada kode, tetapi pada lingkungan jaringan. Firewall perusahaan, VPN, pemblokiran IP repositori, atau hanya kurangnya akses langsung ke internet — semua ini dapat diselesaikan dengan pengaturan proxy yang benar di tiga tingkat: IDE, Gradle, dan SDK Manager. Mari kita bahas cara menulis proxy dengan benar dan tanpa kesalahan sinkronisasi yang tidak perlu.

Mengapa pengembang Android membutuhkan proxy

Proxy sering digunakan dalam kombinasi dengan Android Studio dalam beberapa skenario. Pertama — jaringan perusahaan, di mana akses langsung ke internet diblokir, dan semua lalu lintas, termasuk permintaan ke google(), mavenCentral() dan dl.google.com, harus melalui server proxy perusahaan. Kedua — menghindari pembatasan regional: beberapa komponen SDK, API Google Play Services, atau repositori pihak ketiga tidak dapat diakses langsung dari negara tertentu, dan pengembang terpaksa merutekan lalu lintas melalui IP dari geolokasi lain.

Skenario ketiga — pengujian fungsionalitas aplikasi yang bergantung pada geo. Jika aplikasi menunjukkan konten, harga, atau iklan yang berbeda tergantung pada negara pengguna, insinyur QA dan pengembang perlu mensimulasikan permintaan dari wilayah yang diperlukan bahkan pada tahap pembuatan dan debugging, tanpa menunggu rilis. Keempat — bekerja dengan runner CI/CD yang secara fisik terletak di pusat data dengan akses terbatas ke layanan tertentu, dan proxy menjadi satu-satunya cara untuk "menghubungi" repositori atau API yang diperlukan.

Dalam semua kasus ini, logika yang sama berlaku: Gradle, SDK Manager, dan IDE itu sendiri harus mengetahui alamat, port, dan, jika perlu, kredensial server proxy, jika tidak, sinkronisasi proyek akan gagal dengan timeout atau kesalahan koneksi.

Jenis proxy apa yang harus dipilih untuk pengembangan

Untuk pengembangan dan pengujian, yang lebih penting bukanlah anonimitas, tetapi stabilitas koneksi dan persentase pemutusan yang rendah selama unduhan yang lama (misalnya, Android SDK Platform Tools memiliki ukuran ratusan megabyte). Di bawah ini adalah perbandingan jenis proxy yang relevan untuk tugas pengembang Android.

Jenis Proxy Kapan digunakan Fitur
Proxy Data Center Unduhan SDK, sinkronisasi Gradle, CI/CD Kecepatan tinggi, harga rendah, stabil untuk unduhan besar
Proxy Residensial Pengujian API dan konten yang bergantung pada geo IP pengguna nyata, jarang diblokir oleh layanan
Proxy Seluler Pengujian API seluler dan push-notifikasi dari negara tertentu IP operator seluler, sangat mendekati lalu lintas seluler yang nyata

Untuk sinkronisasi Gradle yang bersih dan pengunduhan dependensi, lebih bijaksana menggunakan proxy data center — mereka memberikan kecepatan tinggi yang stabil tanpa penundaan yang tidak perlu. Namun, jika tugasnya adalah memeriksa bagaimana backend aplikasi merespons pengguna dari negara lain, lebih baik menggunakan IP residensial atau seluler.

Pengaturan proxy di gradle.properties

File gradle.properties adalah tempat utama di mana Gradle mencari pengaturan proxy untuk koneksi HTTP dan HTTPS. File ini dapat terletak di root proyek (berlaku hanya untuk proyek tersebut) atau di direktori global ~/.gradle/gradle.properties (berlaku untuk semua proyek di mesin). Untuk penggunaan yang berkelanjutan melalui proxy, disarankan untuk menggunakan opsi kedua.

# ~/.gradle/gradle.properties

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

# opsional — pengecualian yang diakses langsung, melewati proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

Setelah menyimpan file, pastikan untuk mengklik File → Sync Project with Gradle Files atau ikon "gajah" di toolbar. Jika IDE tidak menangkap perubahan secara otomatis, restart Android Studio — terkadang cache pengaturan proxy tetap ada hingga proses Gradle Daemon di-restart.

Nuansa penting: parameter systemProp.* berlaku pada tingkat JVM di mana Gradle dijalankan, sehingga mempengaruhi tidak hanya pengunduhan dependensi, tetapi juga semua permintaan jaringan di dalam skrip build (misalnya, jika Anda memiliki tugas Gradle kustom yang memanggil API eksternal).

Pengaturan proxy di Android Studio itu sendiri

Selain Gradle, IDE memiliki pengaturan jaringan sendiri — ini diperlukan untuk bekerja dengan plugin, pembaruan IDE, pemeriksaan lisensi, dan beberapa fitur seperti saran dari Google. Anda dapat membukanya melalui File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (di macOS — Android Studio → Preferences).

Di jendela yang terbuka, pilih Manual proxy configuration, masukkan host dan port, jika perlu centang Proxy authentication dan masukkan login dan password. Di sana juga ada tombol nyaman Check connection — masukkan URL uji (misalnya, https://dl.google.com) dan tekan untuk memastikan bahwa koneksi berjalan dengan benar sebelum menjalankan sinkronisasi proyek yang lengkap.

Penting untuk memahami perbedaannya

Pengaturan HTTP Proxy di Settings mempengaruhi IDE itu sendiri (plugin, pembaruan), sedangkan parameter di gradle.properties mempengaruhi proses build Gradle. Ini adalah dua mekanisme independen, dan untuk bekerja secara penuh di belakang proxy biasanya perlu mengatur keduanya.

Proxy untuk SDK Manager

SDK Manager adalah komponen terpisah yang mengunduh platform Android, build-tools, emulator, dan citra sistem. Ia memiliki konfigurasi proxy sendiri, yang secara historis ditetapkan melalui pengaturan sistem IDE yang sama, tetapi saat bekerja melalui sdkmanager mandiri (CLI utility dari command line), parameter harus disampaikan secara eksplisit melalui flag JVM.

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

Jika sdkmanager dijalankan melalui skrip, Anda dapat menetapkan proxy langsung di variabel lingkungan JAVA_OPTS yang dibaca oleh file eksekusi:

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

Kesalahan umum adalah mengatur proxy di Android Studio, tetapi melupakan utilitas mandiri seperti sdkmanager atau avdmanager, yang dijalankan sebagai proses Java terpisah dan tidak mewarisi pengaturan IDE secara otomatis.

Proxy untuk gradlew dan variabel lingkungan

Jika Anda membangun proyek dari terminal melalui pembungkus ./gradlew, melewati IDE (misalnya, dalam CI/CD atau hanya karena kebiasaan), proxy dapat disampaikan langsung dalam perintah tanpa mengubah gradle.properties:

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

Untuk penggunaan yang berkelanjutan, lebih nyaman untuk menetapkan variabel lingkungan GRADLE_OPTS di profil shell (.bashrc, .zshrc untuk Linux/macOS atau variabel lingkungan Windows):

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

Ini sangat berguna dalam runner CI seperti GitHub Actions, GitLab CI, atau Jenkins, di mana variabel lingkungan ditetapkan sekali di tingkat job dan secara otomatis diambil oleh semua langkah build berikutnya, tanpa perlu mengedit file proyek.

Kesalahan sinkronisasi yang umum dan solusinya

Mari kita bahas kesalahan yang paling sering dihadapi pengembang saat mengatur proxy, dan langkah-langkah konkret untuk mengatasinya.

Kesalahan Penyebab Solusi
Connection timed out Proxy tidak ditentukan atau tidak tersedia Periksa host/port di gradle.properties, uji ketersediaan proxy melalui curl
407 Proxy Authentication Required Login/password tidak disertakan Tambahkan systemProp.http.proxyUser dan systemProp.http.proxyPassword
Unable to resolve host DNS resolution tidak melalui proxy Gunakan socksProxyHost sebagai pengganti http untuk SOCKS5 dengan DNS jarak jauh
Could not GET 'https://dl.google.com/...' Pengaturan Gradle ditetapkan, tetapi di IDE tidak (atau sebaliknya) Sinkronkan pengaturan di kedua tempat: Settings → HTTP Proxy dan gradle.properties
SSL handshake failed Proxy menangkap SSL (MITM perusahaan) Impor sertifikat root proxy ke cacerts JDK Anda

Jika kesalahan terjadi saat mengunduh artefak Maven tertentu (misalnya, pustaka androidx.*), berguna untuk sementara mengaktifkan log tingkat lanjut Gradle dengan perintah ./gradlew build --info — dalam output Anda akan melihat pada permintaan mana koneksi terputus dan kode respons apa yang dikembalikan oleh server.

Proxy dengan otorisasi: login dan password

Jika proxy memerlukan autentikasi (ini adalah situasi standar untuk layanan proxy berbayar dan gateway perusahaan), Anda perlu menambahkan dua baris lagi di gradle.properties:

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

Menyimpan password proxy dalam bentuk terbuka di gradle.properties proyek yang masuk ke sistem kontrol versi adalah praktik yang buruk. Gunakan file global di direktori home pengguna, yang tidak dikomit ke Git, atau sampaikan password melalui variabel lingkungan selama tahap CI/CD, agar rahasia tidak bocor ke repositori.

Untuk skenario di mana rotasi IP diperlukan (misalnya, pengujian batas API dari alamat yang berbeda), lebih nyaman menggunakan layanan proxy dengan kumpulan alamat yang sudah siap dan satu login — sehingga rotasi diatur di sisi penyedia, dan di gradle.properties hanya port sesi yang diubah, tanpa menulis ulang konfigurasi seluruh proyek.

Checklist diagnosis

Jika setelah semua pengaturan sinkronisasi masih gagal, ikuti langkah-langkah berikut secara berurutan:

  • Periksa ketersediaan proxy secara langsung dengan perintah curl -x http://proxy.example.com:8080 https://dl.google.com
  • Pastikan pengaturan ditetapkan baik di Settings → HTTP Proxy, maupun di gradle.properties secara bersamaan
  • Bersihkan cache Gradle: ./gradlew --stop dan hapus folder .gradle/caches
  • Periksa bahwa tidak ada spasi atau tanda kutip yang tidak perlu di sekitar nilai host/port di file
  • Jika menggunakan SOCKS5 — tulis socksProxyHost/socksProxyPort sebagai pengganti http.proxyHost
  • Untuk proxy MITM perusahaan, impor sertifikat ke penyimpanan sertifikat tepercaya JDK (keytool -import)
  • Restart Android Studio dan Gradle Daemon setelah melakukan perubahan pada file properties

Kesimpulan

Pengaturan proxy dalam pengembangan Android adalah pekerjaan di tiga tingkat: pengaturan sistem Android Studio untuk IDE itu sendiri, parameter systemProp di gradle.properties untuk proses build, dan konfigurasi terpisah untuk utilitas mandiri seperti sdkmanager. Sebagian besar kesalahan sinkronisasi terjadi karena salah satu tingkat telah diatur, sementara yang lain terlupakan, atau karena kurangnya otorisasi pada proxy yang memerlukannya.

Jika tujuannya hanya untuk secara stabil mengunduh dependensi dan komponen SDK melalui proxy yang berfungsi, proxy data center sangat cocok — mereka cepat dan tidak menyebabkan penundaan yang tidak perlu saat melakukan unduhan besar. Namun, jika perlu menguji bagaimana aplikasi berperilaku untuk pengguna dari negara tertentu atau dari operator seluler, pertimbangkan untuk menggunakan proxy residensial atau IP seluler — mereka memberikan gambaran yang lebih realistis tentang perilaku layanan di berbagai wilayah.