Como utilizar o cURL com um proxy: HTTP, HTTPS, SOCKS, autenticação e soluções

Substitua o espaço reservado para o proxy pelo host e pela porta fornecidos pelo seu serviço de proxy. Primeiro, solicite a um ponto de extremidade de verificação de IP de confiança o endereço público visível sem proxy:

curl "https://api.ipify.org"

Agora, envie a mesma solicitação através do proxy:

curl --proxy "http://proxy.example:8080" "https://api.ipify.org"

-x é a forma abreviada de --proxy, pelo que este comando cURL com proxy é equivalente:

curl -x "http://proxy.example:8080" "https://api.ipify.org"

Um segundo resultado diferente confirma normalmente que a solicitação saiu através de outro endereço. Se não houver alterações, não presuma ainda que o proxy está avariado. Verifique se o ponto de extremidade, o tipo de proxy, a política de rede ou o fornecedor utilizam um IP de saída fixo. É útil consultar uma lista de verificação mais abrangente sobre como testar proxies antes de adicionar o proxy à automação.

Se curl --version falhar, passe para a secção de instalação da plataforma e, em seguida, volte aqui.

Para a autenticação do proxy com o cURL, coloque as credenciais no URL ou passe-as separadamente:

curl -x "http://demo-user:demo-pass@proxy.example:8080" "https://api.ipify.org"

curl -x "http://proxy.example:8080" \
  --proxy-user "demo-user:demo-pass" \
  "https://api.ipify.org"

Utilize espaços reservados fictícios na documentação e coloque entre aspas todos os argumentos que contenham credenciais. --proxy-user mantém as credenciais fora da URL do proxy, mas não torna a linha de comando secreta. No caso de palavras-passe que contenham @, :, %, espaços ou metacaracteres do shell, verifique as regras de escape ou de codificação por por cento para o seu shell e versão do cURL antes de utilizar em produção.

Cada pedido cURL com proxy indica dois pontos finais distintos:

curl --proxy "http://proxy.example:8080" "https://target.example/resource"

O valor após --proxy é a URL do proxy. Indica ao cURL onde se encontra o intermediário e como se ligar a ele. O argumento final é a URL de destino, que identifica a API, a página ou o ficheiro que pretende efetivamente.

Conceitualmente, o cURL envia a solicitação através do proxy, e o proxy reencaminha-a para o destino. Alterar o esquema do proxy altera a forma como o cURL acede a esse intermediário. Alterar o destino altera o recurso que está a ser solicitado. As credenciais do proxy devem constar nas definições do proxy, e não na URL de destino.

Manter essas funções separadas evita um erro comum: alterar o esquema de destino quando a intenção era alterar o protocolo do proxy. Também torna a análise dos registos mais segura, pois permite ocultar o valor do proxy que contém as credenciais sem esconder o alvo que está a ser testado.

Um endereço autenticado segue este formato:

protocol://username:password@host:port

protocol seleciona HTTP, HTTPS ou uma variante SOCKS. host e port localiza o listener do proxy. O nome de utilizador e a palavra-passe opcionais autorizam a utilização desse proxy. Se omitir o esquema, o cURL trata o proxy como HTTP, mas indicá-lo explicitamente torna os scripts mais fáceis de rever.

Os esquemas de destino e de proxy são independentes. Por exemplo, este comando acede a um destino HTTPS através de um proxy HTTP:

curl --proxy "http://proxy.example:8080" "https://target.example/api"

Um https:// URL de proxy significa que a própria ligação cliente-proxy utiliza TLS. Não significa que o destino também tenha de utilizar HTTPS. Se for necessária autenticação, adicione --proxy-user "USER:PASS" em vez de confundir as credenciais do proxy com as do destino. Coloque ambas as URLs entre aspas, especialmente quando estiverem presentes cadeias de consulta ou caracteres sensíveis ao shell.

Esta matriz reúne os principais padrões de utilização do cURL com um proxy num único local:

Utilizar -x ou --proxy de forma consistente num script. As opções são equivalentes, mas a forma longa é normalmente mais clara na automação partilhada. Lembre-se de que os parâmetros do cURL distinguem maiúsculas de minúsculas.

Um proxy SOCKS5 do cURL pode utilizar -x, e o cURL também fornece opções SOCKS específicas:

curl -x "socks4://proxy.example:1080" "https://target.example"
curl -x "socks5://proxy.example:1080" "https://target.example"
curl -x "socks5h://proxy.example:1080" "https://target.example"
curl --socks5 "proxy.example:1080" --proxy-user "USER:PASS" "https://target.example"

Para a resolução de nomes de anfitrião, socks5:// e --socks5 normalmente resolvem o nome de destino localmente, enquanto socks5h:// e --socks5-hostname solicitam ao proxy que o resolva. O SOCKS4a adiciona, de forma semelhante, a resolução de nomes de anfitrião do lado do proxy ao SOCKS4. Esta distinção é importante quando o DNS local não consegue resolver o destino ou quando se pretende que as pesquisas de DNS sigam o caminho do proxy.

Consulte o manual oficial da linha de comandos do cURL para comparar com a versão indicada por curl --version antes de confiar no comportamento do SOCKS, que depende da versão, em ambiente de produção.

Ao decidir como configurar o proxy no cURL, escolha o âmbito mais restrito que se adapte à tarefa. Um sinalizador pontual é mais fácil de auditar, enquanto as variáveis de ambiente e os ficheiros de configuração reduzem a repetição.

No macOS, no Linux e noutros shells do tipo POSIX, exporte as variáveis em minúsculas:

export http_proxy="http://USER:PASS@proxy.example:8080"
export https_proxy="http://USER:PASS@proxy.example:8080"

curl "https://target.example"

unset http_proxy
unset https_proxy

O nome da variável segue o esquema do URL de destino. Por conseguinte, https_proxy pode ainda conter um http:// URL de proxy. Estas variáveis de ambiente de proxy do cURL afetam o shell atual e os seus processos filhos, e não todas as aplicações ou utilizadores.

O PowerShell e o Prompt de Comando utilizam uma sintaxe diferente para as variáveis de ambiente. Mantenha os nomes em minúsculas para garantir a portabilidade e verifique a utilização de maiúsculas e minúsculas na versão exata do shell e do cURL que implementar. Variáveis mais abrangentes, como ALL_PROXY e NO_PROXY necessitam de testes específicos para cada versão.

Um ficheiro de configuração do cURL aplica valores predefinidos ao cURL sem redirecionar programas não relacionados. As localizações comuns para os utilizadores são ~/.curlrc no Linux e no macOS e _curlrc no %APPDATA% no Windows:

proxy = "http://USER:PASS@proxy.example:8080"

Trate o ficheiro como confidencial se este contiver credenciais. Em sistemas do tipo Unix, utilize chmod 600 ~/.curlrc; no Windows, limite a sua ACL à conta pretendida. Um --proxy pode substituir o proxy configurado para um comando.

Os locais de pesquisa de configuração e a precedência podem variar consoante a compilação e o contexto de execução; por isso, confirme-os antes de confiar num valor predefinido oculto na CI.

<!-- É necessária investigação adicional: verificar as maiúsculas e a correspondência de ALL_PROXY/NO_PROXY, a pesquisa no ficheiro de configuração e a precedência completa das definições de proxy para as versões do cURL e os sistemas operativos suportados. -->

Para utilizar um proxy diferente para um pedido, indique-o explicitamente:

curl --proxy "http://alternate-proxy.example:8080" "https://target.example"

Para forçar uma ligação direta, independentemente das variáveis de ambiente ou de um ficheiro de configuração do cURL, utilize a contornagem de todos os anfitriões baseada na fonte:

curl --noproxy "*" "https://target.example"

Esse cURL com contornamento de proxy é mais seguro do que eliminar temporariamente uma configuração que se possa esquecer de restaurar. O cURL também suporta regras de contornamento seletivas através de opções de comando e definições de ambiente, mas a correspondência de nomes de anfitrião, domínios e endereços pode ser subtil. Teste-as com a versão do cURL utilizada em produção, em vez de assumir que o comportamento de um shell NO_PROXY se aplica em todos os casos.

Um gateway de proxy rotativo mantém um endereço de ligação enquanto seleciona um IP de saída de um conjunto para cada pedido ou de acordo com uma política definida pelo fornecedor:

curl -x "http://USER:PASS@gateway.example:8000" "https://target.example/page/1"
curl -x "http://USER:PASS@gateway.example:8000" "https://target.example/page/2"

Isto torna mais fácil criar scripts para um fluxo de trabalho de proxy rotativo com o cURL, uma vez que a rotação ocorre por trás do gateway. Não garante o acesso, não impede a limitação de tráfego nem torna aceitável um scraper agressivo. Continua a ser necessário ter em conta a concorrência razoável, as tentativas de repetição, o ritmo das solicitações, sessões estáveis quando necessário e o respeito pelas regras do destino. Para uma discussão mais aprofundada sobre o design, os proxies rotativos para scraping na Web são um próximo tópico útil.

Quando um proxy cURL não estiver a funcionar, comece pela solicitação com falha mais pequena e utilize diagnósticos detalhados:

curl --verbose --proxy "http://proxy.example:8080" "https://target.example"

Limpe a saída detalhada antes de a partilhar, pois pode expor nomes de anfitrião, cabeçalhos ou detalhes de autenticação. Em seguida, trabalhe com base nos sintomas, em vez de alterar várias opções de uma só vez.

Compare as verificações de IP diretas e via proxy e, em seguida, tente um destino conhecido e acessível. curl -I "URL" Cabeçalhos de pedidos; cabeçalhos de resposta HTTP mais completos no fluxo de trabalho do cURL podem revelar redirecionamentos, desafios de autenticação e metadados de limitação de taxa. Uma referência a erros de estado do proxy ajuda quando um intermediário devolve a sua própria resposta.

Não faça o diagnóstico com base apenas num único código de estado ou de saída. Podem surgir sintomas semelhantes em diferentes saltos. Consulte o manual instalado ou o manual oficial do cURL para conhecer os significados exatos dos códigos de saída e os indicadores de diagnóstico na sua compilação.

Nunca publique nomes de utilizador, palavras-passe ou tokens de proxy ativos. Utilize substitutos nos exemplos, coloque os argumentos entre aspas e lembre-se de que o histórico de comandos, a inspeção de processos, os registos de CI, os dumps de ambiente e as cópias de segurança de configuração podem expor segredos. --proxy-user melhora a legibilidade, não a confidencialidade. Dê preferência a um gestor de segredos, a uma variável de tempo de execução protegida ou a um prompt interativo, sempre que o seu fluxo de trabalho o permitir.

Se um pedido cURL com proxy falhar na validação do certificado, corrija a cadeia de confiança ou forneça o material correto da CA de confiança. O -k opção «ou» --insecure desativa a verificação do certificado, pelo que deve reservá-la para diagnósticos curtos e controlados. Não deve tornar-se a solução de rotina em produção. Com um proxy HTTPS, identifique qual a ligação TLS que falhou antes de escolher a correção, uma vez que o proxy e o destino são contextos de validação de certificados separados.

Execute curl --version primeiro; todos os comandos do cURL com proxy necessitam de um executável funcional. O Windows disponibiliza frequentemente curl.exe, mas a disponibilidade e a resolução no PowerShell variam consoante a compilação e o perfil. Utilize Get-Command curl e curl.exe --version; se não estiver presente, utilize os downloads oficiais do cURL para Windows.

No macOS, instale com brew install curl. No Ubuntu ou Debian, utilize sudo apt install curl.

Utilize esta referência de comandos do cURL para proxy, substituindo cada marcador em maiúsculas.

• Inicie cada comando cURL com uma configuração de proxy, comparando os resultados dos IP públicos diretos e dos que passam pelo proxy. Isto permite distinguir os problemas de encaminhamento das falhas específicas do destino.
• Trate o URL do proxy e o URL de destino como valores independentes. O esquema de cada um controla uma decisão de ligação diferente.
• Utilize --proxy para pedidos isolados, variáveis de ambiente do shell para fluxos de trabalho temporários e um ficheiro de configuração cURL protegido para predefinições estáveis ao nível do utilizador.
• Opte socks5h:// quando for necessária a resolução do nome de host do lado do proxy e verifique o comportamento em relação à versão do cURL implementada em produção.
• Diagnostique a autenticação, a conectividade, o DNS, o TLS e as respostas de destino como etapas separadas. Não faça -k uma correção permanente do certificado.

Não. Um proxy HTTP pode encaminhar um pedido para um destino HTTPS. O esquema de URL do proxy descreve como o cURL se liga ao proxy, enquanto o esquema de destino descreve o recurso solicitado. Escolha um proxy HTTPS quando precisar especificamente de TLS na ligação cliente-proxy, e não simplesmente porque a URL de destino começa por https://.

Sim. -x é a forma abreviada de --proxy, e ambas fornecem o endereço do proxy para essa solicitação. A opção longa é mais fácil de ler em scripts e na configuração de CI, enquanto a opção curta é mais prática no terminal. As opções distinguem maiúsculas de minúsculas, pelo que -x não deve ser substituído por uma variante em maiúsculas.

Utilize curl --noproxy "*" "https://target.example". O asterisco entre aspas indica ao cURL para ignorar a utilização do proxy para todos os destinos nesse comando, mesmo quando um proxy está definido através de variáveis de ambiente ou de um ficheiro de configuração. As aspas também impedem que o shell expanda * para nomes de ficheiros locais.

O cURL costuma ler .curlrc a partir do diretório pessoal do utilizador no Linux e no macOS e _curlrc de um local de configuração do utilizador do Windows, como %APPDATA%. Os caminhos de pesquisa exatos podem variar consoante a compilação e o contexto de execução. Consulte o manual da versão instalada e proteja qualquer ficheiro que armazene credenciais de proxy.

A forma fiável de utilizar o cURL com um proxy é manter a configuração explícita e testar cada camada de forma independente. Comece por curl --version, execute uma verificação direta do IP público, repita-a com --proxye só então adicione credenciais ou persistência. Mantenha o URL do proxy separado do destino, escolha o protocolo com base na forma como precisa de aceder ao proxy e utilize SOCKS5h quando a resolução do nome de host de destino tiver de ocorrer no lado do proxy.

Para trabalhos repetíveis, adapte o âmbito da configuração à tarefa. Os sinalizadores de comando são mais seguros para operações pontuais, as variáveis de ambiente adequam-se a fluxos de trabalho temporários no shell e um ficheiro de configuração bloqueado pode eliminar a repetição das predefinições exclusivas do cURL. Quando um pedido falhar, isole a autenticação, a acessibilidade, o DNS, o TLS e as respostas de destino, em vez de experimentar sinalizadores aleatórios. Em particular, trate -k como uma exceção de diagnóstico controlada, e não como um padrão de produção.

Se um pipeline de scraping gasta mais tempo de engenharia na rotação de proxies, CAPTCHAs e pedidos bloqueados do que na análise do HTML devolvido, a WebScrapingAPI fornece uma API de Scraper que lida com essas preocupações ao nível da camada de pedidos e devolve HTML bruto, com a faturação vinculada à extração bem-sucedida. Esse é o próximo passo prático quando uma configuração de proxy cURL gerida manualmente deixa de ser a opção mais leve.