cURL dipakai di sekitar 20 miliar instalasi di seluruh dunia — sudah jadi bawaan macOS, mayoritas distro Linux, dan Windows 10/11. Tapi kalau Anda tanya ke sepuluh developer soal cara mengarahkan request cURL lewat proxy dengan benar, besar kemungkinan Anda akan mendapat sepuluh jawaban yang sedikit beda, dan separuhnya langsung mentok begitu autentikasi atau SOCKS ikut masuk ke dalam permainan.
Itu celah yang ingin saya tutup lewat panduan ini. Kebanyakan tutorial cuma kasih satu command, bilang “sudah jalan”, lalu selesai. Mereka tidak menunjukkan cara memastikan proxy benar-benar bekerja (spoiler: kadang memang tidak), dan tentu saja tidak membahas kode error yang muncul begitu setup Anda sedikit saja melenceng dari jalur ideal. Panduan ini membahas semuanya — proxy HTTP/HTTPS, SOCKS4/SOCKS5/socks5h, environment variables beserta jebakan khasnya, tabel troubleshooting yang benar-benar berguna, dan apa yang harus dilakukan saat cURL dan proxy sudah tidak cukup lagi.
Apa Itu cURL dan Kenapa Dipakai dengan Proxy?
cURL adalah alat baris perintah untuk mengirim dan menerima data dari sebuah URL. Sesederhana itu — tanpa GUI, tanpa banyak ornamen, hanya program yang berbicara lewat HTTP, HTTPS, FTP, dan beberapa protokol lain. Penggunaan paling dasar adalah:
curl https://example.com
Perintah itu akan mengambil halaman dan menampilkan HTML mentah ke terminal Anda. Berguna, tapi alasan utama developer dan pengguna bisnis yang teknis memakai cURL adalah untuk menguji API, scraping data, mengecek konten yang dibatasi berdasarkan lokasi, dan menjalankan request di pipeline CI/CD.
Proxy berada di tengah-tengah antara mesin Anda dan server tujuan, lalu meneruskan request atas nama Anda. Server tujuan akan melihat IP milik proxy, bukan IP Anda. Ini penting untuk beberapa kebutuhan yang sah: menguji tampilan situs dari negara lain, melewati pembatasan rate limit saat QA, atau mengarahkan trafik lewat gateway korporat yang diwajibkan perusahaan. cURL mendukung semua jenis protokol proxy — HTTP, HTTPS, SOCKS4, dan SOCKS5 — dan flag yang paling sering Anda temui di panduan ini adalah -x / --proxy (alamat proxy), -v (output verbose, sahabat terbaik saat debugging), dan -k (melewati verifikasi SSL, yang pada dasarnya tidak boleh dipakai di luar testing).
Satu catatan penting sebelum lanjut: panduan ini membahas mekanisme jaringan saat memakai proxy dengan cURL. Ini bukan izin untuk mengabaikan syarat penggunaan situs tujuan atau kebijakan keamanan organisasi Anda. Proxy hanya mengubah rute jaringan — bukan mengubah apa yang legal atau diizinkan.
Sebelum Memulai
Tingkat Kesulitan: Pemula sampai Menengah
Waktu yang Dibutuhkan: ~15 menit untuk mengikuti contoh inti
Yang Anda Butuhkan:
- cURL terpasang (cek dengan
curl --version— kalau Anda memakai macOS, Linux, atau Windows 10/11, kemungkinan besar sudah ada) - Kredensial proxy dari penyedia Anda: host, port, protokol (HTTP/HTTPS/SOCKS), dan username/password jika diperlukan
- Terminal (Terminal di macOS, shell apa pun di Linux, PowerShell atau CMD di Windows)
Kalau ternyata cURL belum terpasang, solusinya sederhana: brew install curl di macOS lewat Homebrew, sudo apt install curl di Debian/Ubuntu, atau sudo yum install curl di RHEL/CentOS. Di Windows, cURL sudah dibundel sejak Windows 10 build 17063.
Sepanjang panduan ini saya akan memakai nilai placeholder — proxy.example:8080 untuk alamat proxy dan user:pwd untuk kredensial. Ganti dengan detail proxy Anda yang sebenarnya, dan jangan pernah menempelkan kredensial asli ke shell history, screenshot, atau pesan Slack. Saya sudah melihat lebih banyak password proxy bocor di channel Slack daripada yang ingin saya akui.
Cara Menggunakan cURL dengan Proxy HTTP atau HTTPS
Ini adalah konfigurasi yang paling umum, dan yang akan Anda pakai untuk sebagian besar kebutuhan proxy.
Menggunakan Flag -x / --proxy
Sintaks dasarnya seperti ini:
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x dan --proxy melakukan hal yang sama — pakai mana yang paling mudah Anda ingat. Karena HTTP adalah skema proxy bawaan cURL, secara teknis Anda bisa menghapus prefix http:// dan cukup menulis proxy.example:8080. Tapi saya tetap menyarankan menuliskannya secara eksplisit, karena enam bulan lagi Anda akan berterima kasih ke diri sendiri karena formatnya jelas.
Bungkus seluruh URL dengan tanda kutip ganda. Kalau password Anda mengandung @, #, atau &, string tanpa kutip bisa diproses duluan oleh shell sebelum cURL sempat membacanya.
Menghubungkan Lewat Proxy HTTPS
Beberapa penyedia menjalankan koneksi ke proxy itu sendiri melalui TLS, bukan cuma koneksi dari proxy ke target Anda. Ini berbeda dari mengakses situs HTTPS — protokol proxy dan protokol target adalah dua hal yang terpisah. Untuk menentukannya:
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Kalau di sini muncul error sertifikat, tahan godaan untuk langsung menambahkan -k lalu lanjut. Flag itu mematikan verifikasi sertifikat SSL sepenuhnya, yang mungkin masih oke untuk tes lokal lima menit, tapi jelas ide buruk untuk apa pun yang menyentuh produksi atau data pengguna sungguhan. Kalau Anda berurusan dengan proxy korporat yang melakukan intercept TLS (setup MITM, umum di lingkungan enterprise), perbaikan yang benar adalah mengimpor CA certificate milik proxy, bukan mematikan verifikasi.
Autentikasi dengan --proxy-user
Anda juga bisa memisahkan kredensial ke flag tersendiri alih-alih menaruhnya di URL:
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Perhatikan bahwa huruf kapital -U bukan hal yang sama dengan autentikasi target situs (-u / --user, huruf kecil) — tertukar di sini bisa membuat password proxy Anda terkirim ke tujuan yang salah. Untuk lingkungan korporat yang memakai NTLM atau Digest, bukan Basic auth, tambahkan --proxy-ntlm atau --proxy-digest bersama --proxy-user.
Cara Menggunakan cURL dengan SOCKS Proxy: SOCKS4 vs. SOCKS5 vs. socks5h
SOCKS proxy bekerja di level yang lebih rendah daripada HTTP proxy — protokol yang ditunnel tidak terlalu penting, jadi cocok untuk trafik non-HTTP, koneksi Tor, dan kebutuhan yang sensitif terhadap privasi. Kebanyakan panduan kompetitor cuma kasih satu command lalu selesai. Itu keliru, karena perbedaan antara SOCKS4, SOCKS5, dan socks5h:// memang benar-benar penting.
| Fitur | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Dukungan TCP | Ya | Ya | Ya |
| Dukungan UDP | Tidak | Ya | Ya |
| Autentikasi | Tidak | Ya | Ya |
| Resolusi DNS jarak jauh | Tidak | Tidak (DNS lokal) | Ya (proxy yang resolve) |
| Kompatibel dengan Tor | Tidak | Berisiko (DNS leak) | Ya |
Baris resolusi DNS adalah yang paling sering menjebak orang. Dengan socks5://, mesin Anda akan resolve hostname sebelum koneksi diserahkan ke proxy — artinya resolver DNS lokal Anda (dan secara tidak langsung ISP Anda) bisa melihat domain mana yang ingin Anda akses, meskipun trafik HTTP-nya sendiri lewat proxy. socks5h:// memperbaikinya dengan memindahkan proses resolusi hostname ke proxy, sehingga tidak ada informasi tujuan yang bocor secara lokal. Inilah alasan dokumentasi Tor bersikeras memakai socks5h:// — menggunakan socks5:// biasa akan menghilangkan sebagian besar manfaat anonimitas yang seharusnya diberikan Tor.
Berikut contoh masing-masing varian di cURL:
curl --socks4 "proxy.example:1080" "http://example.com"
curl -x "socks5://user:pwd@proxy.example:1080" "http://example.com"
curl -x "socks5h://user:pwd@proxy.example:1080" "http://example.com"
Kalau tidak ada alasan khusus untuk tidak memakainya, pilih socks5h:// sebagai default. Tidak ada biaya tambahan, dan Anda menutup kebocoran yang mungkin tidak akan pernah Anda sadari.
Menetapkan Proxy dengan Environment Variables (dan Menghindari Jebakannya)
Mengetik -x di setiap command lama-lama melelahkan. Environment variables memungkinkan Anda mengatur proxy sekali per sesi shell, lalu semua panggilan cURL berikutnya otomatis mewarisinya — manual cURL mendokumentasikan http_proxy, HTTPS_PROXY, ALL_PROXY, dan NO_PROXY sebagai set yang didukung.
Dasarnya
export http_proxy="http://user:pwd@proxy.example:8080"
export HTTPS_PROXY="http://user:pwd@proxy.example:8080"
export ALL_PROXY="socks5h://proxy.example:1080"
Bagian yang paling sering bikin orang bingung adalah ini: nama variable merujuk pada protokol URL tujuan, bukan protokol proxy. Jadi http_proxy mengatur request ke URL http://, dan HTTPS_PROXY mengatur request ke URL https:// — keduanya bisa diarahkan ke server HTTP proxy yang sama, dan itu sepenuhnya normal.
Melewati Proxy dengan NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Dipisahkan dengan koma, dan titik di depan .internal.example berfungsi sebagai wildcard untuk semua subdomain. NO_PROXY mengalahkan semua pengaturan lain — bahkan jika -x ditulis secara eksplisit di command line, kecocokan di NO_PROXY akan melewati proxy untuk request tersebut.
Jebakan yang Sering Benar-Benar Menjebak Orang
- Lupa
export. Kalau Anda cuma mengetikhttp_proxy=http://...tanpaexport, variabel itu hanya hidup di shell saat ini dan sama sekali tidak terlihat oleh cURL sebagai child process. Dari pengalaman saya, ini penyebab paling umum dari tiket support bertema “proxy-nya tidak jalan”. - Sensitivitas huruf besar-kecil. cURL secara spesifik mengecek
http_proxyversi huruf kecil terlebih dahulu dan memberi prioritas jika kedua versi ada. Beberapa tools lain hanya membaca huruf besar. Kalau Anda sedang debugging kenapa suatu variabel “tidak terbaca”, cek apakah ada duplikat dengan casing berbeda. - Jebakan alias PowerShell. Di PowerShell 5.1, mengetik
curlsebenarnya tidak menjalankan cURL sama sekali — itu memanggilInvoke-WebRequest, tool yang benar-benar berbeda dengan flag yang berbeda pula. Kalau flag-xAnda memunculkan error aneh di Windows, ketikcurl.exesecara eksplisit untuk memastikan Anda memang menjalankan cURL. - Perbedaan sintaks di Windows. CMD memakai
set http_proxy=...; PowerShell memakai$env:http_proxy = "...". Menukar keduanya antar sesi terminal sangat mudah membuat Anda kehilangan waktu seharian. - Variabel yang sudah usang.
unset http_proxydanunset https_proxyakan membersihkan konfigurasi proxy lama yang diam-diam mengarahkan — dan gagal pada — setiap request.
Untuk toggle cepat, beberapa alias di .bashrc bisa menghemat waktu nyata:
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Membuat cURL Selalu Menggunakan Proxy (File Config)
Kalau Anda berada di balik proxy korporat 95% waktu, file .curlrc (di sistem Unix-like, di direktori home) atau _curlrc (di Windows, di folder app-data) bisa menetapkan default permanen tanpa menyentuh environment variables sama sekali:
proxy="http://proxy.example:8080"
Untuk request satu kali yang ingin melewatinya, --noproxy "*" akan mengesampingkan config tersebut hanya untuk eksekusi itu. Urutan prioritas umumnya adalah flag command line > environment variable > config file, jadi -x di command line selalu menang kalau ada konflik.
Satu peringatan penting: jangan simpan password plaintext di .curlrc kalau file itu ada di lokasi yang mungkin tersinkron, di-backup, atau tanpa sengaja ikut di-commit ke repo. Untuk pipeline CI, gunakan secret manager milik platform Anda dan injeksikan kredensial sebagai environment variable yang dimasking.
Cara Memastikan Proxy Benar-Benar Berjalan
Ini bagian yang hampir selalu dilewatkan panduan lain, padahal justru paling menghemat waktu debugging. Menyetel proxy lalu mengasumsikan trafik sudah melewatinya adalah cara orang habisin berjam-jam menelusuri masalah pada scraper yang sebenarnya dari awal belum pernah memakai proxy.
Metode 1: Bandingkan IP Keluar Anda
Jalankan request echo IP yang sama dua kali — sekali langsung, sekali lewat proxy — lalu bandingkan:
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Kalau kedua command mengembalikan alamat IP yang sama, berarti proxy Anda tidak melakukan apa-apa. Cek syntax flag, environment variable, atau apakah NO_PROXY tanpa sengaja cocok dengan target Anda.
Metode 2: Baca Output Verbose
Tambahkan -v ke request proxy apa pun dan cURL akan menampilkan seluruh handshake:
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Cari baris seperti * Connected to proxy.example (xx.xx.xx.xx) port 8080, lalu > CONNECT httpbin.org:443 HTTP/1.1 dan akhirnya < HTTP/1.1 200 Connection established. Urutan itu — connect ke proxy, lalu tunnel CONNECT ke target — adalah metode HTTP CONNECT yang sedang bekerja, dan memang itulah yang harus terjadi saat target HTTPS diarahkan lewat proxy HTTP. Kalau baris CONNECT itu tidak pernah muncul, berarti flag proxy-nya tidak diterapkan. Satu catatan saat memakai mode ini: gunakan -v hanya ketika sedang debugging aktif, dan redaksi output sebelum dibagikan ke mana pun — mode verbose bisa menampilkan kredensial proxy dalam bentuk plain text.
Metode 3: Bandingkan Hasil Secara Berdampingan
Untuk pengujian geo yang spesifik, simpan kedua output ke file lalu bandingkan dengan diff:
curl https://httpbin.org/ip > direct.json
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip > proxied.json
diff direct.json proxied.json
Kalau isi respons (atau header, untuk konten yang dibatasi lokasi) berbeda, Anda mendapat bukti visual bahwa proxy memang mengubah jalur jaringan — cara cepat dan ringan untuk menghilangkan keraguan sebelum masuk ke penyelidikan lebih jauh.
Troubleshooting Error Proxy cURL yang Umum
Kebanyakan panduan cuma menyinggung ini sekilas dan menyebut -k sekali. Topik ini pantas dapat tabel referensi yang benar-benar nyata.
| Error | Kemungkinan Penyebab | Solusi |
|---|---|---|
curl: (7) Failed to connect | Host/port proxy salah, atau proxy sedang down | Verifikasi alamat; uji konektivitas mentah dengan telnet host port atau nc -zv host port |
407 Proxy Authentication Required | Kredensial proxy salah atau tidak ada | Tambahkan --proxy-user user:pass; cek apakah penyedia mensyaratkan NTLM/Digest/Negotiate bukan Basic |
curl: (56) Recv failure: Connection reset by peer | Proxy memutus koneksi di tengah transfer | Periksa stabilitas proxy dengan penyedia; kalau ini proxy yang mengakhiri TLS, verifikasi penanganan sertifikat alih-alih memaksa mematikannya |
curl: (28) Connection timed out | Firewall memblokir, proxy lama, atau port salah | Jalankan env | grep -i proxy untuk mengecek variabel yang masih tersisa; hapus yang usang; coba request langsung untuk mengisolasi penyebab |
| Gagal verifikasi sertifikat | Sertifikat proxy tidak tepercaya atau melakukan intercept | Dapatkan rantai CA yang benar dan gunakan --proxy-cacert; hindari mematikan verifikasi kecuali untuk diagnosis sekali pakai |
Langkah pertama yang paling berguna untuk semua kasus di atas adalah menambahkan -v. Itu akan menunjukkan dengan jelas di mana koneksi gagal — resolusi DNS, koneksi TCP, handshake TLS, atau pertukaran autentikasi proxy — alih-alih membuat Anda menebak dari kode error tiga digit.
Untuk proxy korporat, --proxy-ntlm dan --proxy-negotiate mendukung skema autentikasi domain Windows. Satu hal yang memang tidak ditangani cURL secara native: file PAC (Proxy Auto-Config scripts yang dipakai sebagian enterprise untuk menetapkan proxy secara dinamis). Kalau perusahaan Anda menggunakannya, Anda perlu mengekstrak host dan port proxy yang sebenarnya secara manual — biasanya dari pengaturan jaringan browser — karena cURL tidak punya parser PAC bawaan.
Saat cURL + Proxy Tidak Cukup
cURL dengan proxy menangani HTML statis, panggilan REST API, dan pengambilan data sederhana dengan sangat baik. Tapi ia mulai kewalahan saat menghadapi pertahanan web modern: single-page app yang dirender oleh JavaScript, sistem anti-bot seperti Cloudflare atau Akamai, dan halaman CAPTCHA. Arahkan cURL ke aplikasi React atau Vue yang berada di balik lapisan ini, dan Anda mungkin hanya akan mendapat <div id="root"></div> kosong — secara teknis request berhasil, secara praktis datanya tidak berguna. Itu bukan bug cURL. cURL memang bukan browser, dan tidak pernah mengaku sebagai browser.
Kalau Anda sudah nyaman menjalankan cURL dari terminal lalu mentok di titik ini, langkah berikutnya yang paling masuk akal bukan pindah ke toolchain yang sama sekali berbeda — melainkan menambahkan lapisan yang menangani rendering dan struktur data untuk Anda. Itulah celah yang ingin ditutup oleh developer tools Thunderbit.
| Skenario | cURL + Proxy | Thunderbit API (POST /extract) |
|---|---|---|
| Halaman HTML statis | Bekerja sempurna | Bekerja, dan hasilnya juga terstruktur |
| SPA yang dirender JS | Mendapat HTML kosong/sebagian | renderMode: "full" menangani JS |
| Anti-bot / CAPTCHA | Diblokir | Penanganan bawaan |
| Output data terstruktur | HTML mentah — harus diparse sendiri | JSON lewat skema Anda sendiri |
| Batch (100+ URL) | Loop manual + rate limiting sendiri | POST /batch/extract |
Open API milik Thunderbit menyediakan endpoint /extract yang mengembalikan JSON yang cocok dengan skema langsung dari halaman berat-JS, serta endpoint /distill untuk konversi Markdown yang rapi — keduanya bisa dipanggil dari sesi terminal yang sama tempat Anda selama ini menjalankan command cURL. Ada juga server MCP untuk AI coding assistant seperti Claude atau Cursor, serta CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json) kalau Anda ingin tetap sepenuhnya di dalam script. Semua ini bukan pengganti cURL untuk pekerjaan yang memang cocok dikerjakan cURL — melainkan meneruskan pekerjaan ketika cURL secara struktural tidak bisa melangkah lebih jauh. Kalau Anda ingin melihat gambaran yang lebih luas tentang kapan ekstraksi berbantuan AI lebih tepat dibanding menulis logika scraper sendiri, ulasan AI web scraping dan perbandingan best AI web scrapers kami membahasnya lebih detail, dan artikel web scraping tanpa coding juga bagus sebagai pengantar kalau Anda datang dari sudut pandang bisnis, bukan engineering.
Penutup
Membuat cURL dan proxy bekerja bareng sebenarnya tidak sulit begitu Anda tahu titik kegagalan yang nyata — dan ternyata hampir tidak ada yang berasal dari proxy itu sendiri. Lupa export. Tertukar antara -u dan -U. Memakai socks5:// padahal yang dimaksud socks5h://. Menjalankan alias curl milik PowerShell alih-alih curl.exe. Semua itu memunculkan error yang membingungkan dan terlihat umum, padahal sumber masalahnya sama sekali bukan penyedia proxy.
Kebiasaan yang paling hemat waktu: verifikasi dulu sebelum troubleshooting. Jalankan pengecekan IP echo, lihat sekilas output -v, dan pastikan proxy memang ada di jalur request sebelum menganggap ada sesuatu yang rusak di hilir. Dan ketika target Anda mulai mengirim JavaScript alih-alih HTML bersih, itu bukan masalah cURL yang bisa diselesaikan dengan lebih banyak flag — itu sinyal untuk memakai tool yang memang dibuat untuk rendering, seperti API Thunderbit, yang menyediakan paket gratis kalau Anda ingin melihat sendiri perbedaan antara JSON keluar dan HTML mentah.
FAQ
Apakah cURL memakai proxy secara default?
Tidak. Kecuali Anda sudah mengatur environment variable http_proxy / HTTPS_PROXY atau mengonfigurasi file .curlrc, cURL akan terhubung langsung ke target tanpa proxy.
Bagaimana cara menghentikan cURL agar tidak memakai proxy untuk satu request saja?
Tambahkan --noproxy "*" ke command tersebut. Untuk menonaktifkannya di seluruh sesi shell, jalankan unset http_proxy && unset https_proxy.
Bisakah saya memakai cURL dengan rotating proxy?
Bisa — kalau penyedia Anda menawarkan rotating gateway (satu endpoint yang memberi IP baru di setiap request), cukup arahkan -x ke alamat gateway itu seperti proxy biasa. Untuk logika rotasi yang lebih kompleks pada target yang dirender JavaScript, layer API seperti Thunderbit menangani rotasi dan anti-bot secara internal, jadi Anda tidak perlu mengelola retry logic secara manual.
Kenapa socks5:// membocorkan request DNS saya sementara socks5h:// tidak?
Dengan socks5://, mesin lokal Anda resolve hostname tujuan sebelum request koneksi dikirim ke proxy — artinya resolver DNS ISP Anda bisa melihat domain yang Anda kunjungi. socks5h:// memindahkan resolusi hostname ke proxy itu sendiri, sehingga informasi tujuan tidak terlihat secara lokal.
Apakah legal memakai cURL dengan proxy?
Menggunakan proxy umumnya legal di banyak yurisdiksi. Yang penting adalah apa yang Anda lakukan dengannya — selalu patuhi syarat penggunaan situs tujuan, robots.txt jika berlaku, dan hukum privasi data yang relevan. Panduan ini hanya membahas aspek teknis, bukan persetujuan hukum untuk kasus penggunaan tertentu.
Pelajari Lebih Lanjut
