Web Scraping con Node-Unblocker: Guía práctica

Node-unblocker es una biblioteca de servidores proxy para Node.js que expone una API compatible con Express para poner en marcha un proxy personalizado con unas pocas líneas de código. Se creó originalmente para eludir la censura en Internet, pero esa misma primitiva (un proxy HTTP hackeable y en proceso) es lo que hace que una configuración de Node-unblocker para el web scraping resulte interesante para los autores de scrapers.

Lo inusual es la interfaz. En lugar de utilizar el clásico protocolo de proxy HTTP o SOCKS5 en un puerto dedicado, Node-unblocker expone un prefijo de URL de estilo REST. Tú solicitas https://your-proxy/proxy/https://target.com/page, y la biblioteca recupera el objetivo en tu nombre y te lo devuelve en streaming. Ese cambio es lo que abre las puertas al middleware sobre el que construiremos más adelante.

Antes de escribir código, decide si un proxy Node-Unblocker para el scraping web es la herramienta adecuada.

Es adecuado si:

• Estás extrayendo principalmente HTML estático o puntos finales JSON sencillos.
• Quieres centralizar la configuración de las solicitudes (encabezados, autenticación, limpieza de cookies) para varios rastreadores detrás de una sola URL.
• Necesitas eludir restricciones geográficas en unas pocas regiones y puedes ejecutar un servidor en cada una de ellas.
• Quieres una capa de middleware nativa de Node para que tu código de scraping se mantenga en JavaScript.

No lo utilices cuando:

• El objetivo se basa en ventanas emergentes de OAuth, postMessage()o un enrutamiento intensivo del lado del cliente.
• Necesitas IP residenciales rotativas a gran escala o cobertura a nivel de país en docenas de regiones.
• Te enfrentas a CAPTCHAs, Cloudflare u otras soluciones anti-bot.
• Tu equipo no tiene ganas de gestionar y actualizar servidores Node.

Si se dan dos o más de las condiciones para «saltárselo», pasa directamente a la sección sobre alternativas gestionadas.

Necesitas una versión LTS reciente de Node.js y npm en tu máquina. En el momento de escribir este artículo, fíjate a la línea LTS actual; los ejemplos más antiguos apuntan a Node 16, pero compruébalo con las descargas oficiales de Node.js antes de fijar nada package.json. Si alternas entre versiones, instala nvm y ejecuta nvm use --lts.

Inicia un proyecto nuevo:

mkdir node-unblocker-proxy && cd node-unblocker-proxy
npm init -y
npm install unblocker express

Una vez instaladas las dependencias, crea index.js. El servidor minimalista de web scraping y desbloqueo de nodos es lo suficientemente pequeño como para caber en una sola pantalla:

// index.js
const express = require("express");
const Unblocker = require("unblocker");

const app = express();
const unblocker = new Unblocker({ prefix: "/proxy/" });

app.use(unblocker);

app
  .listen(process.env.PORT || 8080, () => {
    console.log("Proxy listening on", process.env.PORT || 8080);
  })
  .on("upgrade", unblocker.onUpgrade);

Hay algunas cosas que vale la pena señalar. new Unblocker({...}) devuelve un middleware compatible con Express, por lo que basta con una sola app.use(unblocker) llamada es suficiente para montar todo el proxy. El puerto predeterminado es 8080, que se puede anular mediante la PORT variable de entorno, de modo que el mismo archivo funciona en Docker, Heroku y otros hosts en contenedores.

La .on("upgrade", unblocker.onUpgrade) línea es la parte que se pasa por alto fácilmente. Sin ella, las conexiones WebSocket redirigidas a través del prefijo de URL nunca completarán el cambio de protocolo, y cualquier sitio de destino que utilice actualizaciones en tiempo real dejará de funcionar. Configúrala aunque creas que no la necesitas hoy, ya que la mayoría de los sitios utilizan WebSockets de forma silenciosa para la telemetría.

La mayor parte del comportamiento de node-unblocker se controla a través del objeto de opciones pasado a su constructor. Hay tres ajustes importantes desde el primer día:

• prefix establece la ruta URL bajo la cual se monta el proxy. Con prefix: "/proxy/", cada solicitud a /proxy/<encoded-url> se recupera en nombre del solicitante.
• onUpgrade es el controlador que se vincula al evento upgrade para que el tráfico de WebSocket se reenvíe correctamente.
• DEBUG=unblocker:* es una variable de entorno, no un campo de configuración, pero es la forma más rápida de ver qué está haciendo realmente la biblioteca ante una solicitud que no funciona correctamente.

Hay más opciones en el README de GitHub del proyecto, pero estas tres cubren casi todos los casos de uso de Node Unblocker para el web scraping antes de empezar a añadir middlewares.

Inicia el servidor:

node index.js

A continuación, accédelo desde un shell independiente o desde tu navegador:

curl -i http://localhost:8080/proxy/https://example.com/

Deberías ver un HTTP 200 y el cuerpo HTML reescrito. En el navegador, abre DevTools y observa la pestaña Red: las solicitudes de subrecursos también deberían pasar por /proxy/. Si algo parece incorrecto, reinicia el servidor con registro detallado:

DEBUG=unblocker:* node index.js

Señales comunes: ECONNRESET en el protocolo de enlace TLS suele significar que el servidor de origen ha bloqueado tu IP, mientras que una página en blanco con un código de estado 200 casi siempre se debe a que node-unblocker no ha podido reescribir el JavaScript. Ambos son modos de fallo normales en una configuración de node-unblocker para el scraping web.

Los middlewares son donde un proxy de Node Unblocker para web scraping empieza a parecer una capa de abstracción en lugar de solo un redireccionamiento. Le pasas al constructor una requestMiddleware matriz y una responseMiddleware matriz, y cada función puede modificar el data antes de que se reenvíe.

Aquí hay un par que inyecta un encabezado de autenticación interno y elimina los encabezados de terceros Set-Cookie de terceros de la respuesta:

function injectAuth(data) {
  data.headers["x-internal-auth"] = process.env.SCRAPER_TOKEN;
  data.headers["user-agent"] = "MyCompanyScraper/1.0 (+https://mycompany.example/bot)";
}

function stripCookies(data) {
  delete data.headers["set-cookie"];
}

const unblocker = new Unblocker({
  prefix: "/proxy/",
  requestMiddleware: [injectAuth],
  responseMiddleware: [stripCookies],
});

Aquí hay dos patrones que valen la pena. Todo lo que de otro modo tendrías que repetir en cada scraper (rotar los user agents, adjuntar tokens internos, normalizar Accept-Language) debe ir en requestMiddleware. Todo lo que quieras depurar antes de analizar (cookies de terceros, encabezados de rastreadores, cuerpos de gran tamaño) va en responseMiddleware. Centralizar eso detrás de una URL significa que cada scraper posterior, en cualquier lenguaje, recibe el mismo tratamiento sin copiar y pegar, y las auditorías se convierten en un simple grep de un solo archivo cuando el departamento legal te pregunte cómo identificas tu bot. Para obtener ayudantes de recuperación más avanzados que tengan en cuenta los proxies, nuestras guías sobre el uso de un proxy con node-fetch y sobre la configuración de proxies en Axios combinan bien con este patrón.

Una instancia de node-unblocker es una IP. Para distribuir la carga y eludir los límites de velocidad por IP, implementa varias instancias (idealmente en diferentes regiones) y elige una al azar para cada llamada. Un ayudante mínimo tiene este aspecto:

const PROXIES = [
  "https://proxy-us-1.example.com/proxy/",
  "https://proxy-us-2.example.com/proxy/",
  "https://proxy-eu-1.example.com/proxy/",
];

function pickProxy() {
  return PROXIES[Math.floor(Math.random() * PROXIES.length)];
}

async function scrape(targetUrl) {
  const proxy = pickProxy();
  const res = await fetch(proxy + encodeURI(targetUrl));
  return res.text();
}

Esto es suficiente para unos pocos miles de solicitudes al día. Añade un mecanismo de reintento con un proxy diferente para las respuestas 4xx y 5xx, además de un disyuntor que retira un host PROXIES tras N fallos consecutivos. Para un rendimiento serio, estás reinventando la gestión de proxies, y ese es el punto en el que las herramientas dedicadas a la gestión de proxies y los proxies residenciales rotativos empiezan a amortizarse.

Hay dos vías de implementación fiables para un proxy desbloqueador de nodos de web scraping.

Docker se ejecuta en cualquier lugar donde lo haga un contenedor y es la apuesta más segura a largo plazo. Un Dockerfile mínimo:

FROM node:lts-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 8080
CMD ["node", "index.js"]

Compila con docker build -t my-unblocker . y envía la imagen a Fly.io, Render, AWS ECS, GCP Cloud Run o cualquier otro host de contenedores. Fija la etiqueta Node explícitamente en producción.

Heroku es más rápido para prototipos si ya tienes una cuenta. Añade un engines bloque y un start script a package.json (utiliza la versión principal LTS actual; no copies ciegamente fragmentos más antiguos "16.x" ), y luego:

heroku login
heroku apps:create my-unblocker
git init && heroku git:remote -a my-unblocker
git add . && git commit -am "Initial commit"
git push heroku main

Una vez finalizada la compilación, tu proxy estará activo en https://my-unblocker.herokuapp.com/proxy/<url>. El plan gratuito de Heroku ya no existe, así que ten en cuenta el coste del dyno; si los precios o las políticas cambian, tu imagen de Docker se traslada a otro host sin cambios en el código.

Ejecutar un proxy público en la infraestructura de otra persona es un campo minado en cuanto a políticas. La Política de Uso Aceptable de Heroku, por ejemplo, ha restringido históricamente los proxies públicos y el scraping agresivo; comprueba la AUP actual antes de implementar, ya que la redacción cambia. En cualquier caso, establece un user-agent único e identificable, respeta robots.txt según el RFC 9309, limita la velocidad de tu rastreador y omite los objetivos que prohíban explícitamente la automatización en sus condiciones de servicio.

Las advertencias sinceras ahorran tiempo de depuración. Un proxy desbloqueador de nodos de scraping web probablemente tendrá dificultades en estos casos:

• OAuth y postMessage() . Las ventanas emergentes que intercambian tokens a través de window.postMessage rara vez sobreviven a la reescritura de la URL. Síntoma: ventana emergente de inicio de sesión en blanco que nunca se cierra.
• SPA con mucho JS. Los informes públicos señalan que sitios como YouTube, Twitter/X, Discord e Instagram burlan el desbloqueador de nodos; compruébalo con los issues de GitHub del proyecto, ya que la lista cambia. Síntoma: página en blanco con estado 200.
• Interfaces de usuario basadas en WebSocket cuando onUpgrade falta. Síntoma: actualización fallida en DevTools.
• No hay rotación de IP integrada, resolución de CAPTCHA ni bypass de Cloudflare. Cada uno requiere un sistema externo.
• Sobrecarga operativa. Aplicar parches a Node, rotar instancias y cumplir con las políticas de los proveedores de nube supone un coste real continuo.

En cuanto se dé cualquiera de las siguientes situaciones, la balanza se inclina hacia una API de scraping gestionada:

• Los objetivos se encuentran detrás de Cloudflare, DataDome o PerimeterX.
• Necesitas IP residenciales reales en muchos países, no tres instancias de centro de datos.
• Tu scraper tiene que renderizar JavaScript, desplazarse, hacer clic o resolver CAPTCHAs.
• El volumen supera los pocos miles de solicitudes al día y empiezan a activarse las páginas de guardia.

En ese momento, cambiar la URL del proxy en tu fetch helper por un punto final de scraper gestionado mantiene intacto el resto del código: el mismo análisis del lado de Node, el mismo flujo de trabajo posterior, solo una URL que se encarga del desbloqueo, la rotación y la ejecución por ti.

• Node-unblocker es un middleware de Express modificable, no un proxy de red.
• Wire onUpgrade y un prefix, y luego superpone middlewares para la lógica compartida.
• Rotar instancias para la diversidad de IP; Docker para la portabilidad, Heroku para prototipos.
• Respeta robots.txt, las políticas de uso aceptable (AUP) del host y un agente de usuario único.
• Cambia a una API gestionada en cuanto entren en juego medidas antibot o el renderizado de JS.

Sí. Node-unblocker es de código abierto y tiene una licencia permisiva, por lo que se permite el uso comercial de la biblioteca en sí. El coste reside en otros aspectos: tu factura de alojamiento, la situación legal de los sitios que extraes y las políticas de uso aceptable del proveedor de nube que ejecute tus instancias. Lee siempre el archivo de licencia en el repositorio de GitHub y los términos de servicio del sitio de destino antes de implementar a gran escala.

No. Un único proceso de Node-unblocker siempre muestra la IP pública del host en el que se ejecuta. Si quieres rotación, tienes que implementar varias instancias (idealmente en diferentes regiones o proveedores) y elegir entre ellas en el lado del cliente, tal y como hace el ayudante de rotación de pool que se menciona anteriormente en esta guía. La rotación integrada es una de las razones más claras por las que la gente da el salto a un servicio de proxy gestionado.

No. Node-unblocker es un proxy HTTP transparente con reescritura de encabezados, no una pila de evasión de sistemas anti-bot. No resuelve CAPTCHAs, no genera huellas TLS del navegador y no gestiona el desafío de JavaScript de Cloudflare. Si tu destino utiliza alguna de esas defensas, necesitas un navegador sin interfaz gráfica, un conjunto de direcciones IP residenciales y una lógica de resolución de desafíos, lo cual queda fuera del alcance de la biblioteca.

Un proxy HTTP o SOCKS5 tradicional escucha en un puerto y acepta conexiones que siguen el protocolo de proxy. En cambio, Node-unblocker expone un punto final HTTP donde la URL de destino se codifica en la ruta, como /proxy/https://example.com/. Eso significa que cualquier cliente HTTP puede utilizarlo sin necesidad de una configuración específica para el proxy, y puedes añadir middleware de JavaScript a cada solicitud y respuesta.

Ambos dependen de funciones del navegador que la capa de reescritura de URL no puede reproducir por completo. Las ventanas emergentes de OAuth intercambian tokens con una ventana principal a través de window.postMessage(), y el origen reescrito ya no coincide con lo que espera el sitio de destino, por lo que el establecimiento de la conexión falla silenciosamente. Lo mismo ocurre con cualquier widget incrustado que utilice mensajería entre orígenes. Los inicios de sesión estándar basados en formularios y la mayoría de los puntos finales AJAX simples siguen funcionando con normalidad.

Un proxy de desbloqueo de nodos para web scraping es una de las herramientas más infravaloradas de la caja de herramientas de scraping de Node.js. Te permite crear un proxy HTTP programable en una docena de líneas de código, añadir middleware que convierte la lógica dispersa del scraper en una capa de abstracción limpia, y enviarlo todo como una imagen de Docker a cualquier host que se ajuste a tu presupuesto este año. Para sitios estáticos, el simple bypass geográfico y el modelado compartido de solicitudes, eso es realmente todo lo que necesitas.

También tiene un límite claro. En el momento en que tus objetivos se sitúen detrás de Cloudflare, exijan IP residenciales o envíen sus datos importantes a través de postMessage() y SPAs renderizadas con JavaScript, ya estás fuera del ámbito de node-unblocker. Lo más sensato no es ir acumulando trucos sobre trucos, sino mantener tu código de análisis y cambiar la capa de red que hay debajo.

Si tus rastreadores están empezando a toparse con esos obstáculos, nuestro equipo ha creado WebScrapingAPI precisamente para ese traspaso: un único punto de conexión que gestiona la rotación de proxies, el renderizado de JavaScript, el bypass anti-bot y la resolución de CAPTCHA, mientras tus ayudantes de recuperación existentes siguen funcionando. Considera a Node-Unblocker como la respuesta adecuada para la parte sencilla del problema y recurre a una API gestionada cuando surja la parte difícil. En cualquier caso, ahora dispones de un plan de trabajo, una ruta de implementación y una lista de señales de alerta a las que prestar atención, que es todo lo que necesita una estrategia de proxy autohospedada para empezar.