Cómo usar cURL con un proxy: ejemplos de HTTP, HTTPS y SOCKS5

TL;DR:

• Usa -x o --proxy para dirigir una solicitud cURL a través de un proxy HTTP, HTTPS o SOCKS. Mantén la URL de destino separada de la dirección del proxy.
• Una URL de destino HTTPS no requiere un proxy HTTPS. Un proxy HTTP comúnmente crea un túnel CONNECT hacia un destino HTTPS; una URL de proxy https:// además cifra el salto del cliente al proxy.
• Usa socks5h:// cuando el proxy deba resolver el nombre de host de destino. El socks5:// plano lo resuelve localmente, lo que puede exponer el comportamiento DNS o fallar en un nombre de host que sea solo para proxy.
• Mantén las credenciales fuera de las URLs y archivos fuente. Cita variables de shell, protege archivos de configuración y nunca publiques nombres de usuario, contraseñas o tokens de puerta de enlace reales.
• Verifica más que la IP de salida. Comprueba el estado, contenido esperado, ubicación, comportamiento DNS y una solicitud de control no proxy en un objetivo autorizado.

El soporte para proxies en cURL está integrado en el comando que la mayoría de los desarrolladores ya utilizan para diagnósticos HTTP. Una sola opción puede dirigir una solicitud a través de una puerta de enlace HTTP, un proxy HTTPS o un servidor SOCKS5, con reglas de autenticación y exclusión de host cuando sea necesario.

La sintaxis es simple. El comportamiento de la red no lo es. Los destinos HTTPS utilizan túneles, los esquemas SOCKS deciden dónde ocurre la resolución DNS, las variables de entorno difieren por caso, y las credenciales pueden filtrarse a través del historial de comandos descuidado.

Esta guía comienza con un comando mínimo y construye una configuración que funcione en macOS, Linux y Windows.

Ejemplo Rápido de Proxy cURL

Usa un objetivo público de prueba autorizado y un proxy que controles o que tengas permiso para usar:

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

La opción larga --proxy y la opción corta -x son equivalentes. La referencia de línea de comandos de cURL documenta los esquemas de proxy soportados, opciones de autenticación y comportamiento de exclusión.

Agrega --verbose durante el diagnóstico para ver la secuencia de conexión. Elimina la salida detallada de los registros normales porque los encabezados y detalles de conexión pueden ser sensibles.

Cómo Funcionan las URLs de Proxy cURL

La opción de proxy acepta un esquema, host y puerto:

scheme://proxy-host:port

Los esquemas comunes son:

• http:// para un proxy HTTP;
• https:// para TLS entre cURL y el proxy;
• socks4:// y socks4a:// para variantes SOCKS4;
• socks5:// para SOCKS5 con resolución de nombre de destino local;
• socks5h:// para SOCKS5 con resolución de nombre de destino del lado del proxy.

La URL de destino permanece como el último argumento. No combines el destino y el proxy en una sola URL.

Usa un Proxy HTTP con cURL

Para un destino HTTP plano, cURL envía la solicitud a través del proxy. Para un destino HTTPS, normalmente le pide al proxy que abra un túnel con el método HTTP CONNECT y luego realiza TLS con el destino a través de ese 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/"

El segundo comando aún protege la solicitud y respuesta HTTP con TLS de destino. La conexión cliente-proxy en sí no se cifra por separado antes de que se establezca el túnel, por lo que los observadores de la red local pueden ver la conexión proxy y los metadatos del destino del túnel.

La especificación de Semánticas HTTP define el método CONNECT utilizado para establecer un túnel.

Usa un Proxy HTTPS con cURL

Un proxy HTTPS cifra el salto de cURL al proxy. Prefija la URL del proxy con https://:

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

--proxy-cacert proporciona un paquete CA para verificar el certificado del proxy cuando el almacén de confianza predeterminado no contiene la CA emisora. No uses --proxy-insecure como solución permanente; desactiva la verificación del certificado del proxy.

No todos los puntos finales de proxy aceptan TLS. Asegúrate de que el esquema de URL y el puerto coincidan con la documentación del proveedor.

Usa un Proxy SOCKS5 con cURL

Los proxies SOCKS operan por debajo de HTTP y pueden llevar varios protocolos de aplicación. Para solicitudes web, la elección importante es dónde se resuelve el nombre de host de destino.

# 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/"

Usa socks5h:// cuando el nombre de host de destino no deba ser resuelto por el resolvedor local, cuando el nombre de host solo sea visible desde la red proxy, o cuando el DNS local dé el resultado regional incorrecto.

La guía de SOCKS de Everything cURL explica la distinción entre resolución de nombre local y de proxy. El protocolo en sí está definido en RFC 1928.

Autenticar a un Proxy de Manera Segura

Usa --proxy-user o -U en lugar de incrustar credenciales en la URL del 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 evita que espacios, signos de dólar, signos de exclamación y otros caracteres de shell sean reinterpretados. No escribas una contraseña real directamente en un comando de shell compartido, ticket, captura de pantalla o repositorio.
Los argumentos de línea de comandos pueden ser visibles para la inspección de procesos locales. Para la automatización, prefiera un administrador de secretos que inyecte un valor de corta duración en un trabajo aislado. Si utiliza un archivo de configuración de cURL, restrinja sus permisos y manténgalo fuera del control de versiones:

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

En macOS o Linux, establezca los permisos con chmod 600 proxy.conf, luego ejecute curl --config proxy.conf https://example.com/. Elimine o rote la credencial si el archivo se expone.

Establecer Variables de Entorno de Proxy

cURL reconoce variables de entorno para aplicaciones que deben compartir el enrutamiento de 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/"

La forma en minúsculas http_proxy es intencionada. cURL acepta solo minúsculas para esa variable como una medida de seguridad, mientras que otras variables de proxy pueden estar en mayúsculas. ALL_PROXY actúa como una opción de reserva; las variables específicas de protocolo tienen prioridad.

La guía de variables de entorno de Everything cURL documenta las reglas de caso y la coincidencia de NO_PROXY.

Utilice variables de entorno para trabajos controlados, no como una configuración de escritorio global que olvide que está activa. Inspecciónelas cuando una solicitud utilice inesperadamente un proxy.

Excluir Hosts Seleccionados del Enrutamiento de Proxy

Utilice --noproxy para un comando:

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

Un nombre de host exacto coincide con ese host. Un dominio que comienza con un punto coincide con el dominio y sus subdominios. Un asterisco desactiva el proxy para todos los hosts, lo cual es útil solo para diagnóstico.

Trate las listas de exclusión como política. Un sufijo amplio puede enrutear destinos sensibles o internos fuera de la puerta de enlace prevista.

Configurar cURL Proxy en Windows

Las opciones de cURL son multiplataforma. Solo cambian las variables de entorno y la sintaxis de comillas.

En 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

Utilice curl.exe en entornos de PowerShell de Windows donde curl puede resolverse en otro comando. En el Símbolo del sistema, las variables utilizan %NAME%; para automatización repetible, prefiera PowerShell o un archivo de configuración de cURL protegido.

Verificar la IP de Salida del Proxy

Primero, registre una respuesta de control directo, luego realice la misma solicitud a través del proxy:

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

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

Diferentes valores de IP muestran que el enrutamiento ha cambiado. No prueban el país solicitado, el comportamiento de la sesión, el nivel de anonimato o el éxito de la página de destino.

Para una prueba de aceptación real, verifique todos los siguientes:

• cURL sale con éxito;
• el estado HTTP es el esperado;
• el cuerpo contiene un marcador requerido;
• la IP de salida o la región cumplen con la política de la tarea;
• la resolución DNS ocurre en el lado previsto;
• no aparece ningún host no aprobado en la salida de conexión detallada.

Puede imprimir el estado y la dirección del par remoto sin guardar el cuerpo:

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/"

Errores Comunes de Proxy en cURL

407 Proxy Authentication Required

El proxy no aceptó las credenciales proporcionadas o la cuenta/canal no puede servir la solicitud. Confirme el formato del nombre de usuario, la contraseña, el estado del canal y el método de autenticación permitido. Mantenga los errores de 401 del sitio de destino separados de los errores de 407 del proxy.

La conexión ha agotado el tiempo de espera

Verifique el nombre del host del proxy, el puerto, el firewall, los conflictos de VPN y si el punto final espera HTTP, HTTPS o SOCKS. Utilice --connect-timeout para limitar la configuración de conexión y --max-time para limitar toda la operación.

Error de certificado del proxy

Para un proxy HTTPS, asegúrese de que el nombre del host del proxy coincida con su certificado y se confíe en la CA correcta. Una opción de CA de destino y una opción de CA de proxy protegen diferentes conexiones TLS.

Could not resolve host

Si el mensaje nombra el objetivo mientras usa socks5://, cambie a socks5h:// cuando se pretenda DNS del lado del proxy. Si nombra el proxy, corrija DNS local o el nombre del host del proxy.

La solicitud directa funciona pero la solicitud del proxy falla

Compare la salida detallada, la política objetivo, la ubicación del proxy, el protocolo y el marcador del cuerpo. Un punto final de IP de salida puede funcionar mientras que el objetivo real rechaza el tráfico, así que siempre pruebe el nombre de host de producción permitido por separado.

Utilizar cURL con Proxies Sin Scrapeless

La página de productos de Scrapeless Proxy Solutions cubre opciones residenciales, de centro de datos, ISP estáticos y IPv6. Cree un canal en el panel de Scrapeless, luego copie la puerta de enlace generada, el nombre de usuario y la contraseña. No invente el formato del nombre de usuario; puede incluir el tipo de proxy, la ubicación y los parámetros de sesión seleccionados para ese canal.

Establezca los valores generados como variables 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

La puerta de enlace anterior es un punto final de EE. UU. actual documentado; elija el punto final más cercano a su aplicación del panel o documentación actual. La geografía de salida se controla por separado a través de los parámetros de nombre de usuario generados.
Sigue la guía de configuración del proxy Scrapeless para crear un canal, luego utiliza la referencia de características del proxy para los campos actuales de gateway y ubicación.

Si estás eligiendo entre tipos de direcciones, la guía de proxy datacenter vs. residencial explica las compensaciones operativas. Revisa los precios de Scrapeless para los términos actuales.

Lista de verificación del proxy cURL

• Confirma que el objetivo y el proxy estén autorizados para la tarea.
• Haz coincidir el esquema de URL del proxy con el endpoint del proveedor.
• Usa socks5h:// cuando se requiera DNS del lado del proxy.
• Mantén las credenciales fuera de las URL, indicaciones, registros y repositorios.
• Cita cada variable que pueda contener caracteres especiales.
• Conecta el tiempo de conexión y el tiempo total.
• Establece NO_PROXY o --noproxy de manera precisa.
• Compara un control directo con la respuesta a través del proxy.
• Valida el contenido esperado, no solo la IP de salida.
• Elimina diagnósticos verbosos de los registros normales.

Crear un canal de proxy Scrapeless y pruébalo primero contra un endpoint público al que tengas acceso.

FAQ

Q: ¿Cuál es la sintaxis del proxy cURL?

Usa curl --proxy "scheme://host:port" "https://target.example.com/". La forma corta es curl -x "scheme://host:port" "https://target.example.com/".

Q: ¿Cómo añado un nombre de usuario y contraseña de proxy?

Usa --proxy-user "username:password" y mantén las credenciales fuera de la URL del proxy. En automatización, inyecta los valores desde un almacén de secretos protegido.

Q: ¿Cuál es la diferencia entre socks5:// y socks5h://?

Con socks5://, cURL resuelve el nombre del host objetivo localmente. Con socks5h://, el proxy SOCKS5 lo resuelve.

Q: ¿Puedo usar un proxy HTTP para un sitio web HTTPS?

Sí. cURL comúnmente utiliza HTTP CONNECT para crear un túnel a través del proxy HTTP, luego realiza TLS con el destino HTTPS.

Q: ¿Cómo desactivo un proxy para un host?

Usa --noproxy "host.example" para un comando o añade el host a NO_PROXY. Mantén la lista restringida y revisa las coincidencias de sufijos de dominio.