Crear un pipeline de optimización de imágenes con una CDN
Crea un Worker que convierta una imagen pública integrada en tres recursos WebP y sirva el HTML que selecciona entre ellos. Puedes inspeccionar las imágenes decodificadas localmente y luego llevar el mismo código a producción con Workers Cache habilitado para comprobar si las solicitudes repetidas realmente obtienen respuestas de la caché.
Cómo funcionan las CDN de imágenes
Un pipeline de imágenes necesita tanto transformación como entrega. Aquí, la
vinculación Images redimensiona los bytes sin procesar de una imagen
dentro de un Worker. Workers Cache puede servir la respuesta HTTP
resultante sin ejecutar de nuevo ese Worker. Debe habilitarse explícitamente; devolver solo un
encabezado Cache-Control no lo habilita.
Este ejemplo fija WebP como formato de salida y expone solo tres rutas de imágenes. La fuente es una imagen PNG sintética de 1.280 × 640 con cuatro paneles de colores. Esto hace que el ejemplo sea autónomo y fácil de verificar; no demuestra calidad fotográfica ni una reducción del tamaño de archivo. No hay subidas, imágenes privadas ni URL de origen arbitrarias.
Prepara el proyecto
Los comandos siguientes usan Bash en Linux. Las versiones probadas son
Node.js 26.12.1, Corepack, Yarn 4.12.0 y
Wrangler 4.154.0. Node 26 es una línea de versiones con mantenimiento activo; estas versiones
están fijadas para reproducir el ejemplo, sin afirmar que otros parches sean incompatibles.
Corepack es un requisito previo independiente en Node 26: sigue sus
instrucciones de instalación si corepack
no está disponible. También necesitas cURL para verificar la caché tras el despliegue y un
navegador compatible con WebP.
Para el despliegue, usa una cuenta de Cloudflare con Workers y la vinculación Images disponibles,
un subdominio workers.dev existente y autenticación de Wrangler para esa cuenta.
El desarrollo local que se explica a continuación no requiere un despliegue en la nube. Consulta
las opciones de autenticación de Cloudflare antes del despliegue;
las transformaciones de imágenes y las solicitudes a Workers pueden generar cargos.
Desde un directorio con permisos de escritura, pega este bloque. Se niega a reemplazar un
directorio image-pipeline existente y mantiene tu shell en su directorio original:
(
for tool in node corepack; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
mkdir image-pipeline &&
cd image-pipeline &&
mkdir src &&
cat > package.json <<'JSON' &&
{
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"start": "wrangler dev --ip 127.0.0.1 --port 8787",
"build": "wrangler deploy --dry-run --outdir dist",
"deploy": "wrangler deploy"
},
"devDependencies": { "wrangler": "4.154.0" }
}
JSON
printf 'nodeLinker: node-modules\nignorePath: true\nenableScripts: true\nnpmMinimalAgeGate: 0\n' > .yarnrc.yml &&
touch yarn.lock
)
El archivo de bloqueo local delimita un proyecto Yarn propio para este ejemplo. Su
configuración de Yarn selecciona node_modules
y conserva el ejecutable de Yarn fijado en lugar de heredar el yarnPath
de un proyecto superior. También permite los scripts de instalación de las dependencias nativas.
npmMinimalAgeGate: 0 hace que este ejemplo aislado instale su versión fijada sin el
plazo de espera por antigüedad de paquetes de un proyecto superior; conserva la política de tu
organización al integrarlo en una aplicación existente. Desde ese mismo directorio superior,
instala y verifica la CLI real:
(cd image-pipeline && corepack yarn install && corepack yarn exec wrangler --version)
El resultado esperado es 4.154.0. Si la instalación falla, resuelve la
causa indicada y repite este bloque de instalación en el mismo directorio superior. Conserva
package.json y el directorio del proyecto; volver a ejecutar el bloque de
creación rechazaría correctamente el directorio existente. Si la creación se interrumpió antes
de completarse, inspecciona ese directorio antes de continuar o elige una nueva ubicación vacía.
Configura la optimización de imágenes
Guarda esto como image-pipeline/wrangler.jsonc. Al desplegar, elige un nombre de Worker que te
pertenezca y que no hayas usado antes, para que el ejemplo no reemplace una aplicación existente:
{
"name": "image-pipeline-example",
"main": "src/index.ts",
"workers_dev": true,
"compatibility_date": "2026-10-28",
"images": { "binding": "IMAGES" },
"cache": { "enabled": true, "cross_version_cache": false }
}
La entrada images proporciona env.IMAGES. La entrada
independiente cache habilita
Workers Cache para este Worker. Las respuestas de imágenes que
se muestran a continuación son públicas y se pueden almacenar en caché durante 3.600 segundos;
el HTML y las respuestas de error usan no-store.
Guarda el Worker completo como image-pipeline/src/index.ts:
interface ImagesBinding {
input(stream: ReadableStream<Uint8Array>): {
transform(options: { width: number }): {
output(options: { format: 'image/webp' }): Promise<{
response(options?: { headers?: Record<string, string> }): Response
}>
}
}
}
const sourceBase64 =
'iVBORw0KGgoAAAANSUhEUgAABQAAAAKAAgMAAAC+nT0yAAAADFBMVEXIPCgoyGQoPMjctCj/cAxvAAADMUlEQVR42u3TQQ0AIAADsQWPmMQkiOAzQk9CsyXlzfJGdBVAgAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAnymVd4uzwJdGCBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIEKAAAgQIUAABAgQogAABAhRAgAA/6QB65UPMTK7o+gAAAABJRU5ErkJggg=='
const source = Uint8Array.from(atob(sourceBase64), (value) => value.charCodeAt(0))
const page = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Responsive image pipeline</title>
<style>body{margin:0}img{display:block;width:100%;max-width:640px;height:auto}</style>
</head>
<body>
<h1>Responsive image pipeline</h1>
<img src="/image/1280.webp"
srcset="/image/320.webp 320w, /image/640.webp 640w, /image/1280.webp 1280w"
sizes="(max-width: 640px) 100vw, 640px" width="1280" height="640"
alt="Four colored panels used to check image resizing">
</body>
</html>`
const widths: Record<string, number> = {
'/image/320.webp': 320,
'/image/640.webp': 640,
'/image/1280.webp': 1280,
}
export default {
async fetch(request: Request, env: { IMAGES: ImagesBinding }): Promise<Response> {
const url = new URL(request.url)
const notFound = () =>
new Response('Not found', { status: 404, headers: { 'Cache-Control': 'no-store' } })
if (request.method !== 'GET' || url.search !== '') return notFound()
if (url.pathname === '/') {
return new Response(page, {
headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
})
}
if (!Object.hasOwn(widths, url.pathname)) return notFound()
const width = widths[url.pathname]
try {
return (
await env.IMAGES.input(new Blob([source]).stream())
.transform({ width })
.output({ format: 'image/webp' })
).response({
headers: {
'Cache-Control': 'public, max-age=3600',
'X-Image-Run': crypto.randomUUID(),
},
})
} catch {
return new Response('Image transformation unavailable', {
status: 503,
headers: { 'Cache-Control': 'no-store' },
})
}
},
}
Solo /image/320.webp, /image/640.webp y
/image/1280.webp seleccionan una transformación. Sus dimensiones decodificadas
deberían ser de 320 × 160, 640 × 320 y 1.280 × 640, respectivamente, con paneles rojo y verde
sobre paneles azul y amarillo. La vinculación establece el tipo de contenido de la respuesta
según el formato de salida solicitado. Cambiar el nombre de los bytes PNG o establecer un
encabezado WebP no convertiría una imagen.
Implementa imágenes adaptables
Inicia el servidor local desde el directorio superior:
(cd image-pipeline && corepack yarn start)
Abre http://127.0.0.1:8787/. Deberías ver los cuatro paneles, ajustados al área de
visualización hasta un ancho de presentación de 640 píxeles. Abre cada ruta de imagen directamente
para inspeccionar su contenido y sus dimensiones. Detén el servidor en primer plano con Ctrl+C
antes del siguiente paso. Si el puerto 8787 está ocupado, detén el otro proceso que escucha en
ese puerto o elige otro puerto en el script start antes de iniciar este
ejemplo.
El sizes del HTML coincide con ese diseño CSS:
100vw hasta 640 píxeles y, después, 640px.
Sus descriptores 320w, 640w y
1280w describen los anchos reales de los recursos, en lugar de sus
anchos de presentación. Los atributos width y
height reservan una relación de aspecto de 2:1, mientras que
src proporciona la imagen predeterminada.
Consulta las reglas de selección de imágenes en HTML.
Inspecciona la solicitud de la imagen elegida en el panel de red de tu navegador. Un área de visualización de 320 píxeles con DPR 1, una de 800 píxeles con DPR 1 y una de 640 píxeles con DPR 2 ponen a prueba distintas necesidades de recursos. Usa contextos nuevos del navegador al compararlas: la selección puede depender del navegador, de la relación de píxeles del dispositivo y de los recursos almacenados en caché. El marcado ofrece candidatos al navegador; no obliga a todos los navegadores a elegir siempre el mismo.
Wrangler en modo local usa una implementación limitada de Images sin conexión que admite el redimensionamiento y el formato explícito de este ejemplo. Comprueba la página y las transformaciones, pero no demuestra un acierto en la caché de Cloudflare tras el despliegue. Cloudflare documenta estas limitaciones de la vinculación local.
Despliega y observa la caché
Primero, compila. Una ejecución de prueba exitosa escribe el Worker empaquetado en
image-pipeline/dist/index.js sin subirlo. Repetir la compilación actualiza ese directorio de
salida desechable:
(cd image-pipeline && corepack yarn build)
Tras confirmar tu cuenta, la autenticación y el nombre de Worker sin usar, despliega desde el mismo directorio superior:
(cd image-pipeline && corepack yarn deploy)
Abre la URL workers.dev que imprime Wrangler y vuelve a verificar la página
y las tres URL de imágenes. Sustituye el origen en ambos comandos siguientes por ese origen.
Son solicitudes GET completas que descartan el cuerpo e imprimen los encabezados; cURL no usa
la caché de imágenes de un navegador:
(
command -v curl >/dev/null 2>&1 || { printf 'Install cURL first\n' >&2; exit 1; }
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp' &&
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp'
)
Busca CF-Cache-Status: HIT en una solicitud repetida y compara
X-Image-Run con la respuesta anterior. Un acierto debería conservar el
marcador generado cuando el Worker produjo esa respuesta. Un encabezado
Cache-Control, unos bytes de imagen idénticos o un marcador estable por sí
solos no demuestran un acierto. Si el estado no aparece, revisa la configuración
cache.enabled desplegada; los fallos de caché repetidos requieren revisar la
política de respuesta y la clave de caché. La
guía de depuración de caché de Cloudflare explica estos estados.
No consideres que una vista previa local constituye una prueba equivalente.
Esto permite observar el comportamiento de la caché, pero no constituye una prueba de rendimiento de velocidad o ancho de banda. Mide los bytes reales y las métricas de página con imágenes representativas antes de afirmar que hay una mejora de rendimiento.
Mantén acotado el ejemplo público
Todas las imágenes de este ejemplo son públicas y el Worker acepta un conjunto fijo de rutas. Mantén ese límite al experimentar: aceptar URL arbitrarias añadiría un problema distinto de obtención de fuentes y control de acceso. No sustituyas las imágenes por imágenes confidenciales en esta ruta de respuestas públicas que se pueden almacenar en caché. La entrega privada necesita su propio diseño de autorización y caché.
Para una biblioteca de imágenes real, reemplaza la fuente sintética solo después de elegir cómo
se almacenan los originales y se autoriza el acceso a ellos; luego verifica los anchos de salida
decodificados antes de declararlos en srcset. El procesamiento y la
entrega gestionados son otra opción; consulta Smart CDN de Transloadit.
¿Prefieres no ejecutarlo por tu cuenta?
Smart CDN de Transloadit transforma y entrega archivos sobre la marcha.
