Caché y cabeceras: immutable, hashes y Cache-Control

Servir un archivo desde la ciudad más cercana al usuario ya es rápido; no volver a servirlo cuando no ha cambiado es gratis e instantáneo. Ahí entra la caché, la capa que decide cuánto tiempo un asset puede reutilizarse sin volver a pedirlo, y que separa un sitio meramente global de uno verdaderamente veloz. Cloudflare cachea tus assets en el edge y en el navegador de forma automática, pero el control fino —qué se cachea para siempre, qué se revalida en cada visita— lo gobiernas tú con dos herramientas: los hashes de contenido en los nombres de archivo y la cabecera Cache-Control. Esta lección explica la estrategia de dos niveles que hace que un despliegue nuevo sea a la vez instantáneo para el que vuelve y siempre fresco.

Cómo se cachea un asset

Cuando el edge sirve un asset, no lo trata como bytes anónimos: le calcula un identificador basado en su contenido y lo expone como cabecera ETag. En la siguiente visita, el navegador reenvía ese identificador en una cabecera condicional, y si el archivo no ha cambiado el edge responde un 304 Not Modified —una respuesta minúscula, sin cuerpo, que le dice al navegador “usa el que ya tienes”—. Así se evita reenviar bytes idénticos: la validación cuesta un ida y vuelta diminuto en lugar de la descarga completa.

Sobre esa base actúa Cache-Control, la cabecera que decide cuánto tiempo puede el navegador —y las cachés intermedias— reutilizar un asset sin siquiera preguntar. Un max-age alto significa “no vuelvas a pedirlo en este tiempo”; un no-cache significa “puedes guardarlo, pero valida siempre antes de usarlo”. La diferencia entre revalidar y no preguntar es la diferencia entre una petición de red y ninguna, y aplicarla bien a cada tipo de archivo es el arte de esta lección.

El hash de contenido: la clave de lo inmutable

La pregunta incómoda de toda caché agresiva es: si le digo al navegador que guarde un archivo un año, ¿cómo le entrego una versión nueva antes de que pase ese año? La respuesta elegante es no cambiar nunca un archivo, sino publicar uno con otro nombre. Los empaquetadores modernos incrustan un hash del contenido en el nombre del archivo —app.4f3a2b1c.js—, de modo que cualquier cambio en el código produce un nombre distinto. El archivo con un nombre dado es, por construcción, inmutable: ese nombre solo puede referirse a ese contenido, para siempre.

Eso habilita la directiva más potente de Cache-Control: immutable. Declarar un archivo con hash como public, max-age=31536000, immutable le promete al navegador que ese archivo jamás cambiará, y el navegador deja de revalidarlo por completo —ni siquiera envía la petición condicional 304—. Es la máxima velocidad posible: el recurso se sirve desde el disco local sin tocar la red.

flowchart TD
D[Nuevo despliegue] --> H[El empaquetador pone un hash en el nombre]
H --> A[app.4f3a2b.js es inmutable por construccion]
A --> C[Cache-Control immutable un ano sin revalidar]
D --> I[index.html conserva su nombre]
I --> R[Cache-Control no-cache revalida en cada visita]
R --> N[El HTML apunta al nuevo hash y el navegador lo baja]
style A fill:#a6e3a1,color:#11111b
style R fill:#f9e2af,color:#11111b

La estrategia de dos niveles

De aquí sale el patrón que usan todos los sitios rápidos, y que combina las dos ideas anteriores. Los recursos con hash en el nombre —JavaScript, CSS, tipografías— se cachean para siempre y como inmutables, porque un cambio nunca reescribe un nombre existente sino que crea uno nuevo. En cambio, los puntos de entrada sin hash —el index.html y demás HTML— se revalidan en cada visita con no-cache, porque son ellos los que contienen las referencias a los nombres con hash. El HTML es el índice mutable que apunta a un mar de recursos inmutables.

El mecanismo encaja como un reloj: cuando despliegas una versión nueva, el HTML —que siempre se revalida— llega fresco y trae dentro los nuevos nombres con hash; el navegador ve que esos nombres son distintos de los que tenía y baja solo los que cambiaron, reutilizando de su caché local todos los que no. El que vuelve a tu sitio obtiene la versión nueva al instante y descarga el mínimo indispensable. Fresco y rápido a la vez, sin elegir entre ambos.

Fijar Cache-Control con _headers

Para aplicar esa estrategia colocas un archivo llamado _headers en la raíz de tu directorio de assets. Cada bloque asocia un patrón de ruta con las cabeceras que Cloudflare añadirá a esas respuestas; es la misma sintaxis que heredó de Pages, otra pieza de la paridad de 2026:

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: no-cache

/
  Cache-Control: no-cache

Ese _headers cachea para siempre todo lo que cuelga de /assets/ —donde tu empaquetador deja los archivos con hash— y obliga a revalidar cada HTML y la raíz. El archivo no se sirve como contenido; wrangler lo interpreta al desplegar y aplica las reglas a las respuestas correspondientes. Si necesitas cabeceras calculadas en tiempo real —una política que dependa del usuario— siempre puedes servir el asset desde el Worker con env.ASSETS.fetch y reescribir las cabeceras de la respuesta antes de devolverla.