cURL běží zhruba na 20 miliardách instalací po celém světě — je součástí macOS, většiny linuxových distribucí a ve výchozím nastavení také Windows 10/11. A přesto když se deset vývojářů zeptáte, jak správně směrovat požadavek cURL přes cURL proxy, dostanete deset mírně odlišných odpovědí, z nichž polovina přestane fungovat ve chvíli, kdy do hry vstoupí autentizace nebo SOCKS.
Právě tuhle mezeru chci tady zaplnit. Většina návodů ukáže jeden příkaz, řekne, že funguje, a jde dál. Neukáže vám, jak ověřit, že proxy skutečně něco dělá (spoiler: někdy nedělá), a už vůbec vás neprovedou chybovými kódy, které se objeví hned ve chvíli, kdy se vaše nastavení byť jen trochu odchýlí od ideálního scénáře. Tento průvodce pokrývá vše podstatné — HTTP/HTTPS proxy, SOCKS4/SOCKS5/socks5h, proměnné prostředí (a jejich velmi specifické nástrahy), přehlednou tabulku pro řešení problémů i situace, kdy cURL a proxy už prostě nestačí.
Co je cURL a proč ho používat s proxy?
cURL je nástroj pro příkazovou řádku, který slouží k přenosu dat z a do URL. Nic víc — žádné GUI, žádné zbytečnosti, jen program, který umí mluvit HTTP, HTTPS, FTP a několika dalšími protokoly. Nejjednodušší použití vypadá takto:
curl https://example.com
Tímto příkazem stáhnete stránku a vypíšete syrové HTML do terminálu. To samo o sobě je užitečné, ale skutečný důvod, proč po cURL sahají vývojáři a techničtí business uživatelé, je testování API, sběr dat, kontrola geograficky omezeného obsahu a spouštění požadavků v CI/CD pipeline.
Proxy stojí mezi vaším počítačem a cílovým serverem a předává požadavek vaším jménem. Cílový server vidí IP proxy, ne vaši vlastní. To je důležité z řady legitimních důvodů: testování, jak web vypadá z jiné země, obcházení rate limitů během QA nebo směrování provozu přes firemní gateway, kterou vaše organizace vyžaduje. cURL podporuje celé spektrum proxy protokolů — HTTP, HTTPS, SOCKS4 i SOCKS5 — a v tomhle průvodci budete opakovaně vídat přepínače -x / --proxy (adresa proxy), -v (podrobný výstup, váš nejlepší parťák pro debugování) a -k (vypne ověřování SSL, což byste mimo testování prakticky nikdy používat neměli).
Ještě krátká poznámka, než půjdeme dál: tenhle průvodce je o síťové mechanice práce s proxy v cURL. Neznamená to, že můžete ignorovat podmínky používání cílového webu nebo bezpečnostní pravidla vaší organizace. Proxy mění síťovou cestu — nemění to, co je legální nebo povolené.
Než začnete
Obtížnost: Začátečník až mírně pokročilý
Časová náročnost: přibližně 15 minut na projití hlavních příkladů
Co budete potřebovat:
- nainstalovaný cURL (ověříte příkazem
curl --version— na macOS, Linuxu nebo Windows 10/11 už tam s největší pravděpodobností je) - přihlašovací údaje k proxy od poskytovatele: host, port, protokol (HTTP/HTTPS/SOCKS) a případně uživatelské jméno a heslo
- terminál (Terminal na macOS, jakýkoli shell na Linuxu, PowerShell nebo CMD na Windows)
Pokud cURL z nějakého důvodu nainstalovaný není, je to otázka jednoho příkazu: brew install curl na macOS přes Homebrew, sudo apt install curl na Debianu/Ubuntu nebo sudo yum install curl na RHEL/CentOS. Ve Windows je součástí systému od buildu 17063 ve Windows 10.
V celém článku budu používat zástupné hodnoty — proxy.example:8080 pro adresu proxy a user:pwd pro přihlašovací údaje. Vyměňte je za skutečné údaje své proxy a nikdy nevkládejte reálné přihlašovací údaje do historie shellu, na screenshot nebo do Slacku. Proxy hesel uniklých ve Slack kanálech jsem už viděl víc, než bych chtěl přiznat.
Jak používat cURL s HTTP nebo HTTPS proxy
Tohle je nejběžnější nastavení a to, které použijete ve většině případů.
Použití přepínače -x / --proxy
Základní syntaxe vypadá takto:
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x a --proxy dělají přesně totéž — použijte ten, který se vám lépe pamatuje. Protože HTTP je výchozí proxy schéma cURL, můžete teoreticky vynechat předponu http:// a napsat jen proxy.example:8080. Já bych ji ale nechával explicitně, protože za půl roku si za tu srozumitelnost poděkujete.
Celou adresu uzavřete do uvozovek. Pokud heslo obsahuje @, # nebo &, neuzavřený řetězec si shell přebere po svém ještě dřív, než se k němu cURL vůbec dostane.
Připojení přes HTTPS proxy
Někteří poskytovatelé šifrují nejen spojení z proxy na cílový server, ale i samotné spojení z vašeho počítače na proxy. To je něco jiného než přístup na HTTPS web — protokol proxy a protokol cíle jsou nezávislé věci. Zadáte to takto:
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Pokud tady dostanete chybu certifikátu, nenechte se svést k tomu, abyste přidali -k a šli dál. Tenhle přepínač vypne ověřování SSL certifikátu úplně, což je v pořádku pro pětiminutový lokální test, ale pro cokoli v produkci nebo s reálnými uživatelskými daty je to špatný nápad. Pokud řešíte firemní proxy, která zachytává TLS (MITM nastavení běžné v enterprise prostředí), správné řešení je importovat CA certifikát proxy, ne vypínat ověřování.
Autentizace pomocí --proxy-user
Přihlašovací údaje můžete také zadat zvlášť do vlastního přepínače, místo abyste je vkládali do URL:
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Pozor na to, že velké -U není totéž co autentizace vůči cílovému webu (-u / --user, malé písmeno) — snadno se to zamění a pak pošlete proxy heslo úplně jinam. V enterprise prostředí, které používá místo Basic auth NTLM nebo Digest, přidejte k --proxy-user ještě --proxy-ntlm nebo --proxy-digest.
Jak používat cURL se SOCKS proxy: SOCKS4 vs. SOCKS5 vs. socks5h
SOCKS proxy fungují na nižší vrstvě než HTTP proxy — nezáleží jim na tom, jaký protokol tunelujete, takže jsou vhodné pro ne-HTTP provoz, Tor a cokoli, kde záleží na soukromí. Většina konkurenčních návodů to odbude jedním příkazem a jde dál. To je ale chyba, protože rozdíly mezi SOCKS4, SOCKS5 a socks5h:// jsou opravdu důležité.
| Vlastnost | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Podpora TCP | Ano | Ano | Ano |
| Podpora UDP | Ne | Ano | Ano |
| Autentizace | Ne | Ano | Ano |
| Vzdálené DNS řešení | Ne | Ne (lokální DNS) | Ano (DNS řeší proxy) |
| Kompatibilita s Tor | Ne | Rizikové (únik DNS) | Ano |
Právě řádek s DNS bývá největší past. U socks5:// vaše zařízení přeloží název hostitele ještě před tím, než spojení předá proxy — to znamená, že váš lokální DNS resolver a ve výsledku i váš ISP vidí, na jakou doménu se snažíte připojit, i když samotný HTTP provoz už jde přes proxy. socks5h:// to řeší tak, že rozlišení hostitele provádí proxy, takže lokálně nic neuniká. Proto také Tor dokumentace trvá na socks5h:// — použití prostého socks5:// znehodnocuje velkou část anonymity, kterou Tor poskytuje.
V cURL vypadá každá varianta takto:
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"
Pokud k tomu nemáte zvláštní důvod, používejte defaultně socks5h://. Nestojí to nic navíc a zároveň tím odstraníte únik, kterého byste si jinak vůbec nevšimli.
Nastavení proxy pomocí proměnných prostředí (a jak se vyhnout pastem)
Psát -x ke každému příkazu omrzí velmi rychle. Proměnné prostředí vám umožní nastavit proxy jednou pro celou shell session a všechny následné příkazy cURL ji automaticky zdědí — manuál cURL uvádí jako podporované http_proxy, HTTPS_PROXY, ALL_PROXY a NO_PROXY.
Základ
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"
Tady je část, na které lidé pořád narážejí: název proměnné odkazuje na protokol cílové URL, ne na protokol proxy. Takže http_proxy řídí požadavky na http:// adresy a HTTPS_PROXY řídí požadavky na https:// adresy — obě proměnné můžete směrovat na stejný HTTP proxy server, a je to naprosto normální.
Vynechání přes NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Hodnoty oddělíte čárkami a úvodní tečka u .internal.example funguje jako zástupný znak pro všechny subdomény. NO_PROXY přebíjí všechno ostatní — i když je -x v příkazu výslovně nastavené, shoda v NO_PROXY daný požadavek z proxy obejde.
Nástrahy, na které lidé skutečně narážejí
- Zapomenuté
export. Když jen napíšetehttp_proxy=http://...bezexport, proměnná existuje jen v aktuálním shellu a cURL ji jako podřízený proces vůbec nevidí. Podle mých zkušeností je to nejčastější důvod hlášek typu „proxy nefunguje“. - Citlivost na velikost písmen. cURL výslovně kontroluje nejdřív malé
http_proxya dává mu přednost, pokud existují obě varianty. Některé jiné nástroje čtou jen velká písmena. Když zjišťujete, proč se proměnná „nebere“, zkontrolujte, jestli nemáte duplicitní zápis s jinou velikostí písmen. - Past s PowerShell aliasem. V PowerShell 5.1 příkaz
curlvůbec nespustí cURL — voláInvoke-WebRequest, což je úplně jiný nástroj s jinými přepínači. Pokud vám na Windows hází-xdivné chyby, napište explicitněcurl.exe, abyste měli jistotu, že skutečně spouštíte cURL. - Rozdíly v syntaxi na Windows. CMD používá
set http_proxy=...; PowerShell používá$env:http_proxy = "...". Zaměnit to mezi terminálovými relacemi je snadný způsob, jak ztratit půl dne. - Zastaralé proměnné.
unset http_proxyaunset https_proxyodstraní starou proxy konfiguraci, která tiše směruje — a často i neúspěšně směruje — každý požadavek.
Pro rychlé přepínání se hodí pár aliasů v .bashrc:
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Jak přimět cURL používat proxy vždy (konfigurační soubor)
Pokud jste za firemní proxy 95 % času, soubor .curlrc (na unixových systémech v domovské složce) nebo _curlrc (na Windows ve složce app-data) nastaví trvalý výchozí stav bez zásahu do proměnných prostředí:
proxy="http://proxy.example:8080"
Když chcete u jednoho konkrétního požadavku proxy vynechat, --noproxy "*" přepíše konfiguraci jen pro dané spuštění. Priorita obvykle funguje jako: přepínač v příkazové řádce > proměnná prostředí > konfigurační soubor, takže -x v příkazu vždy vyhraje, pokud nastane konflikt.
Důležité upozornění: nedávejte prosté heslo do .curlrc, pokud je soubor uložený někde, kde by se mohl synchronizovat, zálohovat nebo omylem dostat do repozitáře. Pro CI pipeline používejte secret manager vaší platformy a přihlašovací údaje vkládejte jako maskované proměnné prostředí.
Jak ověřit, že proxy opravdu funguje
Tohle je část, kterou většina ostatních návodů vynechává, a přitom právě ta ušetří nejvíc času při debugování. Proxy nastavit a jen předpokládat, že skutečně směruje provoz, je přesně ten důvod, proč lidé tráví hodiny laděním scraperu, který ve skutečnosti přes proxy nikdy nešel.
Metoda 1: Porovnejte odchozí IP adresu
Spusťte stejný dotaz na echo IP dvakrát — jednou přímo a jednou přes proxy — a porovnejte výstup:
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Pokud oba příkazy vrátí stejnou IP adresu, proxy ve skutečnosti nic nedělá. Zkontrolujte syntaxi přepínačů, proměnné prostředí nebo to, jestli NO_PROXY omylem neodpovídá vašemu cíli.
Metoda 2: Přečtěte si podrobný výstup
Přidejte k jakémukoli proxy požadavku -v a cURL vypíše celý průběh spojení:
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Hledejte řádek jako * Connected to proxy.example (xx.xx.xx.xx) port 8080, následovaný > CONNECT httpbin.org:443 HTTP/1.1 a nakonec < HTTP/1.1 200 Connection established. Tahle sekvence — připojení k proxy a následně CONNECT tunel k cíli — je práce HTTP CONNECT metody a přesně to má nastat, když je HTTPS cíl směrován přes HTTP proxy. Pokud se řádek CONNECT vůbec neobjeví, proxy přepínač se nepoužívá. Jedno upozornění: -v používejte jen při aktivním debugování a před sdílením výstup vždy začerněte — verbose režim může vypsat proxy přihlašovací údaje v čistém textu.
Metoda 3: Porovnání vedle sebe
Pro testování geolokace uložte oba výstupy do souborů a porovnejte je:
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
Pokud se odpovědi (nebo hlavičky u geograficky omezeného obsahu) liší, máte vizuální potvrzení, že proxy skutečně mění síťovou cestu — rychlý a nenáročný způsob, jak si ověřit, že všechno funguje, než půjdete dál.
Řešení běžných chyb cURL s proxy
Většina návodů tady mává rukou a jednou zmíní -k. Tohle téma si zaslouží pořádnou referenční tabulku.
| Chyba | Pravděpodobná příčina | Oprava |
|---|---|---|
curl: (7) Failed to connect | Špatný host/port proxy nebo je proxy nedostupná | Ověřte adresu; otestujte syrové připojení pomocí telnet host port nebo nc -zv host port |
407 Proxy Authentication Required | Chybějící nebo nesprávné přihlašovací údaje k proxy | Přidejte --proxy-user user:pass; zkontrolujte, zda poskytovatel nevyžaduje místo Basic NTLM/Digest/Negotiate |
curl: (56) Recv failure: Connection reset by peer | Proxy během přenosu spojení přerušila | Ověřte stabilitu proxy u poskytovatele; pokud jde o proxy ukončující TLS, zkontrolujte práci s certifikátem místo vypínání ověření |
curl: (28) Connection timed out | Firewall blokuje provoz, proxy je zastaralá nebo je špatný port | Spusťte env | grep -i proxy a zkontrolujte zbytkové proměnné; neaktuální proměnné smažte; otestujte přímý požadavek, abyste izolovali příčinu |
| Selhání ověření certifikátu | Nedůvěryhodný nebo zachytávající certifikát proxy | Získejte správný CA řetězec a použijte --proxy-cacert; mimo jednorázovou diagnostiku nechte ověřování zapnuté |
První univerzální krok u všech těchto chyb je přidat -v. Ukáže vám přesně, kde se spojení láme — při DNS rozlišení, TCP připojení, TLS handshaku nebo při autentizační výměně s proxy — místo toho, abyste hádali jen podle tříciferného kódu.
Pro firemní proxy konkrétně --proxy-ntlm a --proxy-negotiate pokrývají autentizační schémata domén Windows. Co cURL nativně neumí: PAC soubory (Proxy Auto-Config skripty, které některé firmy používají k dynamickému přidělování proxy). Pokud je vaše firma používá, budete muset skutečný host a port proxy zjistit ručně — obvykle v nastavení sítě prohlížeče — protože cURL nemá vestavěný parser PAC.
Kdy cURL + proxy nestačí
cURL s proxy zvládá statické HTML, REST API i jednoduché stahování dat zhruba tak dobře, jak to jen jde. Kde naráží, je moderní web a jeho oblíbené obrany: single-page aplikace renderované JavaScriptem, anti-bot systémy jako Cloudflare nebo Akamai a CAPTCHA. Když na React nebo Vue aplikaci za jednou z těchto ochran pošlete cURL, dostanete zpátky prázdné <div id="root"></div> — technicky úspěšný požadavek, prakticky nepoužitelná data. To není chyba cURL. Jen to není prohlížeč a nikdy se za něj nevydával.
Pokud už umíte spouštět cURL z terminálu a narazíte na tenhle strop, přirozený další krok není přechod na úplně jiný toolchain — je to přidání vrstvy, která za vás zajistí renderování a strukturování dat. Přesně tuhle mezeru mají zaplnit nástroje pro vývojáře od Thunderbit.
| Scénář | cURL + Proxy | Thunderbit API (POST /extract) |
|---|---|---|
| Statická HTML stránka | Funguje bez problémů | Funguje, a navíc vrací strukturovaná data |
| SPA renderovaná přes JS | Vytáhne prázdné nebo neúplné HTML | renderMode: "full" zpracuje JavaScript |
| Anti-bot / CAPTCHA | Zablokováno | Vestavěné řešení |
| Výstup strukturovaných dat | Syrové HTML — musíte parsovat sami | JSON podle vlastního schématu |
| Dávkové zpracování (100+ URL) | Ruční smyčka + vlastní rate limiting | POST /batch/extract |
Thunderbit Open API nabízí endpoint /extract, který vrací JSON odpovídající schématu přímo z JS-heavy stránek, a endpoint /distill pro čistý převod do Markdownu — obojí můžete volat ze stejné terminálové session, ve které jste dosud spouštěli cURL. K dispozici je také MCP server pro AI coding asistenty jako Claude nebo Cursor a CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json), pokud chcete zůstat čistě u skriptů. Nic z toho nenahrazuje cURL v úlohách, pro které je cURL skvělý — jen to přebírá práci tam, kam už se cURL strukturálně nedostane. Pokud chcete širší přehled o tom, kde dává AI asistovaný sběr dat smysl oproti vlastnoručnímu scraperu, podívejte se na naše přehledy AI web scraping, nejlepší AI web scrapery a web scraping bez programování, které to vysvětlují podrobněji.
Shrnutí
Rozchodit cURL s proxy není těžké, jakmile víte, kde se ve skutečnosti láme spojení — a ukazuje se, že skoro nikdy to není samotná proxy. Zapomenuté export. Záměna -u a -U. Použití socks5:// místo socks5h://. Spuštění PowerShell aliasu curl místo curl.exe. Každý z těchto případů vyvolá matoucí, obecně vypadající chybu, která s poskytovatelem proxy nemá nic společného.
Nejvíc času šetří tento zvyk: nejdřív ověřte, teprve potom řešte problém. Spusťte kontrolu IP, podívejte se na výstup -v, potvrďte, že proxy je vůbec v cestě požadavku, než začnete předpokládat, že se něco rozbilo dál po trase. A když vám cíl začne posílat JavaScript místo čistého HTML, není to problém cURL, který by se vyřešil dalším přepínačem — je to signál, že je čas sáhnout po nástroji stavěném na renderování, třeba po API Thunderbit, které má i bezplatnou verzi, pokud si chcete sami vyzkoušet rozdíl mezi JSON výstupem a syrovým HTML.
Nejčastější dotazy
Používá cURL proxy automaticky?
Ne. Pokud nemáte nastavené proměnné prostředí http_proxy / HTTPS_PROXY nebo nakonfigurovaný soubor .curlrc, cURL se připojí přímo k cíli bez proxy.
Jak zabráním tomu, aby cURL použil proxy jen pro jeden požadavek?
Přidejte k danému příkazu --noproxy "*". Chcete-li to vypnout pro celou shell session, spusťte unset http_proxy && unset https_proxy.
Můžu cURL používat s rotujícími proxy?
Ano — pokud vám poskytovatel nabízí rotační gateway (jedno endpoint, které při každém požadavku přidělí novou IP), stačí na něj v -x ukázat stejně jako na jakoukoli jinou proxy. U složitější rotace proti JS-renderovaným cílům zvládne rotační logiku i anti-bot vrstvu interně API jako Thunderbit, takže retry logiku nemusíte spravovat ručně.
Proč socks5:// uniká DNS dotazy, ale socks5h:// ne?
U socks5:// váš lokální počítač přeloží cílový hostname ještě před tím, než pošle požadavek proxy — takže DNS resolver vašeho ISP vidí doménu, kterou navštěvujete. socks5h:// přesune rozlišení hostitele na samotnou proxy, takže lokálně není vidět nic o cíli.
Je legální používat cURL s proxy?
Používání proxy je ve většině jurisdikcí samo o sobě legální. Důležité je, co s ní děláte — vždy respektujte podmínky cílového webu, robots.txt, pokud je relevantní, a všechny příslušné zákony o ochraně dat. Tenhle průvodce pokrývá jen technickou stránku věci, ne právní souhlas pro jakýkoli konkrétní případ použití.
Další informace
