Como Usar cURL Com um Proxy: Exemplos de HTTP, HTTPS e SOCKS5

TL;DR:

• Use -x ou --proxy para direcionar uma solicitação cURL através de um proxy HTTP, HTTPS ou SOCKS. Mantenha a URL de destino separada do endereço do proxy.
• Um alvo HTTPS não requer um proxy HTTPS. Um proxy HTTP comumente cria um túnel CONNECT para um destino HTTPS; uma URL de proxy https:// adicionalmente criptografa o salto do cliente para o proxy.
• Use socks5h:// quando o proxy deve resolver o nome do host de destino. O socks5:// puro resolve localmente, o que pode expor o comportamento DNS ou falhar em um nome de host apenas proxy.
• Mantenha credenciais fora de URLs e arquivos de origem. Cite variáveis de shell, proteja arquivos de configuração e nunca publique nomes de usuários, senhas ou tokens de gateway reais.
• Verifique mais do que o IP de saída. Verifique status, conteúdo esperado, localização, comportamento DNS e uma solicitação de controle não proxy em um alvo autorizado.

O suporte a proxy cURL está embutido no comando que a maioria dos desenvolvedores já usa para diagnósticos HTTP. Uma única opção pode direcionar uma solicitação através de um gateway HTTP, um proxy HTTPS ou um servidor SOCKS5, com autenticação e regras de exclusão de host quando necessário.

A sintaxe é simples. O comportamento da rede não é. Os alvos HTTPS usam túneis, os esquemas SOCKS decidem onde a resolução DNS acontece, as variáveis de ambiente diferem por caso e as credenciais podem vazar por meio de um histórico de comandos descuidado.

Este guia começa com um comando mínimo e constrói uma configuração que funciona em macOS, Linux e Windows.

Exemplo Rápido de Proxy cURL

Use um alvo público de teste autorizado e um proxy que você controla ou tem permissão para usar:

curl --proxy "http://proxy.example.com:8080" \
  --connect-timeout 10 \
  --max-time 30 \
  --show-error \
  "https://example.com/"

A longa opção --proxy e a opção curta -x são equivalentes. A referência da linha de comando cURL documenta os esquemas de proxy suportados, opções de autenticação e comportamento de exclusão.

Adicione --verbose durante o diagnóstico para ver a sequência de conexão. Remova a saída detalhada dos logs normais porque cabeçalhos e detalhes de conexão podem ser sensíveis.

Como Funcionam as URLs de Proxy cURL

A opção de proxy aceita um esquema, host e porta:

scheme://proxy-host:port

Os esquemas comuns são:

• http:// para um proxy HTTP;
• https:// para TLS entre cURL e o proxy;
• socks4:// e socks4a:// para variantes SOCKS4;
• socks5:// para SOCKS5 com resolução de nome de alvo local;
• socks5h:// para SOCKS5 com resolução de nome de alvo do lado do proxy.

A URL de destino permanece como o último argumento. Não combine o destino e o proxy em uma única URL.

Use um Proxy HTTP Com cURL

Para um alvo HTTP puro, o cURL envia a solicitação através do proxy. Para um alvo HTTPS, normalmente solicita ao proxy que abra um túnel com o método HTTP CONNECT e, em seguida, realiza TLS com o destino através desse túnel.

# HTTP target through an HTTP proxy
curl -x "http://proxy.example.com:8080" "http://example.com/"

# HTTPS target through the same HTTP proxy
curl -x "http://proxy.example.com:8080" "https://example.com/"

O segundo comando ainda protege a solicitação e resposta HTTP com TLS de destino. A conexão cliente-para-proxy em si não é criptografada separadamente antes do túnel ser estabelecido, portanto, observadores locais da rede podem ver a conexão do proxy e os metadados do destino do túnel.

A especificação de Semântica HTTP define o método CONNECT usado para estabelecer um túnel.

Use um Proxy HTTPS Com cURL

Um proxy HTTPS criptografa o salto do cURL para o proxy. Prefixe a URL do proxy com https://:

curl --proxy "https://proxy.example.com:8443" \
  --proxy-cacert "/path/to/proxy-ca.pem" \
  "https://example.com/"

--proxy-cacert fornece um pacote CA para verificar o certificado do proxy quando o armazenamento padrão de confiança não contém a CA emissora. Não use --proxy-insecure como uma correção permanente; isso desativa a verificação do certificado do proxy.

Nem todo endpoint de proxy aceita TLS. Combine o esquema da URL e a porta com a documentação do provedor.

Use um Proxy SOCKS5 Com cURL

Proxies SOCKS operam abaixo do HTTP e podem transportar vários protocolos de aplicação. Para solicitações da web, a escolha importante é onde o nome do host de destino é resolvido.

# Resolve example.com on the local machine
curl --proxy "socks5://proxy.example.com:1080" "https://example.com/"

# Send example.com to the proxy for resolution
curl --proxy "socks5h://proxy.example.com:1080" "https://example.com/"

# Equivalent long option for proxy-side hostname resolution
curl --socks5-hostname "proxy.example.com:1080" "https://example.com/"

Use socks5h:// quando o nome do host de destino não deve ser resolvido pelo resolvedor local, quando o nome do host é visível apenas da rede do proxy, ou quando o DNS local fornece o resultado regional errado.

A guia Everything cURL SOCKS explica a distinção entre resolução de nome local e de proxy. O protocolo em si é definido em RFC 1928.

Autentique-se em um Proxy com Segurança

Use --proxy-user ou -U em vez de embutir credenciais na URL do proxy:

export PROXY_HOST="proxy.example.com"
export PROXY_PORT="8080"
export PROXY_USER="replace-with-user"
read -r -s -p "Proxy password: " PROXY_PASS
printf '\n'

curl --proxy "http://${PROXY_HOST}:${PROXY_PORT}" \
  --proxy-user "${PROXY_USER}:${PROXY_PASS}" \
  "https://example.com/"

unset PROXY_PASS

Citar impede que espaços, sinais de cifrão, pontos de exclamação e outros caracteres de shell sejam reinterpretados. Não digite uma senha real diretamente em um comando de shell compartilhado, ticket, captura de tela ou repositório.
Argumentos de linha de comando podem ser visíveis para inspeção de processos locais. Para automação, prefira um gerenciador de segredos que injete um valor de curta duração em um trabalho isolado. Se você usar um arquivo de configuração cURL, restrinja suas permissões e mantenha-o fora do controle de versão:

proxy = "http://proxy.example.com:8080"
proxy-user = "replace-with-user:replace-with-password"
connect-timeout = 10
max-time = 30
show-error

No macOS ou Linux, defina permissões com chmod 600 proxy.conf, depois execute curl --config proxy.conf https://example.com/. Exclua ou rotacione a credencial se o arquivo for exposto.

Definir Variáveis de Ambiente Proxy

cURL reconhece variáveis de ambiente para aplicativos que devem compartilhar roteamento proxy:

export http_proxy="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export ALL_PROXY="socks5h://proxy.example.com:1080"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

curl "https://example.com/"

A forma em minúsculas http_proxy é intencional. cURL aceita apenas minúsculas para essa variável como uma medida de segurança, enquanto outras variáveis de proxy podem ser em maiúsculas. ALL_PROXY atua como um fallback; variáveis específicas de protocolo têm precedência.

O guias de variáveis de ambiente do Everything cURL documentam regras de maiúsculas e NO_PROXY correspondência.

Utilize variáveis de ambiente para trabalhos controlados, não como uma configuração global de desktop que você esquece estar ativa. Inspecione-as quando um pedido utiliza inesperadamente um proxy.

Excluir Hosts Selecionados do Roteamento Proxy

Use --noproxy para um comando:

curl --proxy "http://proxy.example.com:8080" \
  --noproxy "localhost,127.0.0.1,.internal.example.com" \
  "https://internal.example.com/health"

Um nome de host exato corresponde a esse host. Um domínio que começa com um ponto corresponde ao domínio e seus subdomínios. Um asterisco desativa o proxy para todos os hosts, o que é útil apenas para diagnóstico.

Trate as listas de exclusão como política. Um sufixo amplo pode direcionar destinos sensíveis ou internos fora do gateway pretendido.

Configurar cURL Proxy no Windows

As opções do cURL são multiplataforma. Apenas a sintaxe de ambiente e de citação muda.

No PowerShell:

$env:http_proxy = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.internal.example.com"

curl.exe --proxy "http://proxy.example.com:8080" `
  --proxy-user "replace-with-user:replace-with-password" `
  --show-error `
  "https://example.com/"

Remove-Item Env:http_proxy, Env:HTTPS_PROXY, Env:NO_PROXY

Use curl.exe em ambientes do Windows PowerShell onde curl pode ser resolvido em outro comando. No Prompt de Comando, as variáveis usam %NAME%; para automação repetível, prefira PowerShell ou um arquivo de configuração cURL protegido.

Verificar o IP de Saída do Proxy

Primeiro registre uma resposta de controle direto, depois faça a mesma solicitação através do proxy:

curl --silent --show-error "https://httpbin.org/ip"

curl --silent --show-error \
  --proxy "http://proxy.example.com:8080" \
  "https://httpbin.org/ip"

Valores IP diferentes mostram que o roteamento mudou. Eles não provam o país solicitado, o comportamento da sessão, o nível de anonimato ou o sucesso da página de destino.

Para um teste de aceitação real, verifique todos os seguintes itens:

• cURL sai com sucesso;
• o status HTTP é o esperado;
• o corpo contém um marcador necessário;
• o IP de saída ou região atende à política da tarefa;
• a resolução de DNS acontece do lado pretendido;
• nenhum host não aprovado aparece na saída de conexão detalhada.

Você pode imprimir o status e o endereço do par remoto sem salvar o corpo:

curl --output /dev/null --silent --show-error \
  --write-out 'status=%{http_code} peer=%{remote_ip}\n' \
  --proxy "http://proxy.example.com:8080" \
  "https://example.com/"

Erros Comuns do Proxy cURL

407 Proxy Authentication Required

O proxy não aceitou as credenciais fornecidas ou a conta/canal não pode atender à solicitação. Confirme o formato do nome de usuário, a senha, o estado do canal e o método de autenticação permitido. Mantenha os erros de 401 do site de destino separados dos erros de 407 do proxy.

Conexão excedeu o tempo

Verifique o nome do host do proxy, a porta, conflitos de firewall e VPN, e se o ponto final espera HTTP, HTTPS ou SOCKS. Use --connect-timeout para limitar a configuração de conexão e --max-time para limitar toda a operação.

Erro de certificado proxy

Para um proxy HTTPS, certifique-se de que o nome do host do proxy corresponda ao seu certificado e que a CA correta seja confiável. Uma opção de CA de destino e uma opção de CA do proxy protegem diferentes conexões TLS.

Could not resolve host

Se a mensagem nomear o destino enquanto usa socks5://, mude para socks5h:// quando o DNS do lado do proxy for pretendido. Se nomear o proxy, conserte o DNS local ou o nome do host do proxy.

Solicitação direta funciona, mas solicitação pelo proxy falha

Compare a saída detalhada, a política de destino, a localização do proxy, o protocolo e o marcador do corpo. Um ponto de saída IP pode funcionar enquanto o alvo real rejeita o tráfego, então sempre teste o nome de host de produção permitido separadamente.

Usar cURL Com Proxys Scrapeless

A página do produto Scrapeless Proxy Solutions cobre opções residenciais, de datacenter, ISP estáticas e IPv6. Crie um canal no painel do Scrapeless e, em seguida, copie o gateway gerado, nome de usuário e senha. Não invente o formato do nome de usuário; ele pode incluir tipo de proxy, localização e parâmetros de sessão selecionados para aquele canal.

Defina os valores gerados como variáveis protegidas:

export SCRAPELESS_PROXY_HOST="gw-us.scrapeless.io"
export SCRAPELESS_PROXY_PORT="8789"
export SCRAPELESS_PROXY_USER="replace-with-generated-username"
read -r -s -p "Scrapeless proxy password: " SCRAPELESS_PROXY_PASS
printf '\n'

curl --proxy "http://${SCRAPELESS_PROXY_HOST}:${SCRAPELESS_PROXY_PORT}" \
  --proxy-user "${SCRAPELESS_PROXY_USER}:${SCRAPELESS_PROXY_PASS}" \
  --connect-timeout 10 \
  --max-time 30 \
  --show-error \
  "https://httpbin.org/ip"

unset SCRAPELESS_PROXY_PASS

O gateway acima é um ponto de extremidade dos EUA documentado atualmente; escolha o ponto de extremidade mais próximo da sua aplicação no painel ou na documentação atual. A geografia de saída é controlada separadamente através dos parâmetros de nome de usuário gerados.
Siga o guia de configuração de proxy da Scrapeless para criar um canal e, em seguida, use a referência de recursos de proxy para os campos atuais de gateway e localização.

Se você estiver escolhendo entre tipos de endereço, o guia de proxy de datacenter vs. residencial explica as compensações operacionais. Revise preços da Scrapeless para os termos atuais.

Checklist de Proxy cURL

• Confirme que o alvo e o proxy estão autorizados para a tarefa.
• Combine o esquema da URL do proxy com o endpoint do provedor.
• Use socks5h:// quando o DNS do lado do proxy for necessário.
• Mantenha as credenciais fora de URLs, prompts, logs e repositórios.
• Coloque entre aspas cada variável que possa conter caracteres especiais.
• Limite o tempo de conexão e o tempo total.
• Configure NO_PROXY ou --noproxy de forma restrita.
• Compare um controle direto com a resposta proxy.
• Valide o conteúdo esperado, não apenas o IP de saída.
• Remova diagnósticos verbose dos logs normais.

Crie um canal de proxy Scrapeless e teste primeiro contra um endpoint público ao qual você tem permissão para acessar.

FAQ

Q: Qual é a sintaxe do proxy cURL?

Use curl --proxy "scheme://host:port" "https://target.example.com/". A forma curta é curl -x "scheme://host:port" "https://target.example.com/".

Q: Como adiciono um nome de usuário e senha de proxy?

Use --proxy-user "username:password" e mantenha as credenciais fora da URL do proxy. Na automação, injete os valores de um armazenamento secreto protegido.

Q: Qual é a diferença entre socks5:// e socks5h://?

Com socks5://, o cURL resolve o nome do host de destino localmente. Com socks5h://, o proxy SOCKS5 o resolve.

Q: Posso usar um proxy HTTP para um site HTTPS?

Sim. O cURL costuma usar HTTP CONNECT para criar um túnel através do proxy HTTP e, em seguida, realiza TLS com o destino HTTPS.

Q: Como desabilito um proxy para um host?

Use --noproxy "host.example" para um comando ou adicione o host a NO_PROXY. Mantenha a lista restrita e revise as correspondências de sufixos de domínio.