¿Qué es el caché de compilación de Hugo y cómo funciona?

La caché de construcción de Hugo almacena contenido renderizado y activos procesados para acelerar las construcciones posteriores. Se encuentra en el directorio resources/_gen y almacena imágenes procesadas, CSS, JavaScript y plantillas renderizadas. Hugo utiliza automáticamente esta caché para evitar el reprocesamiento del contenido no modificado, reduciendo significativamente los tiempos de construcción en sitios grandes.

¿Cómo activo las construcciones incrementales en Hugo?

Use la bandera --ignoreCache para deshabilitar la caché o hugo server con --disableFastRender para forzar reconstrucciones completas. Para construcciones incrementales, simplemente ejecute hugo sin banderas—Hugo usa automáticamente el contenido en caché cuando los archivos de origen no han cambiado. La variable de entorno HUGO_CACHEDIR puede especificar una ubicación personalizada para la caché.

¿Qué encabezados HTTP debo configurar para los activos estáticos de Hugo?

Establezca un caché agresivo para activos estáticos (CSS, JS, imágenes) con Cache-Control: public, max-age=31536000, immutable (1 año). Para las páginas HTML, utilice tiempos de caché más cortos: Cache-Control: public, max-age=3600 (1 hora) junto con los encabezados ETag o Last-Modified . Esto permite que los navegadores almacenen en caché los activos a largo plazo, manteniendo al mismo tiempo las páginas HTML actualizadas.

¿Cómo configuro el almacenamiento en caché de CDN para un sitio de Hugo?

Configure su CDN (CloudFront, Cloudflare, etc.) para almacenar en caché activos estáticos con TTL largos (1 año) y HTML con TTL más cortos (1 hora). Configure la invalidación de caché en las implementaciones. Para CloudFront, utilice el cloudFrontDistributionID en la configuración de implementación de Hugo. Active la compresión (gzip/brotli) y configure los comportamientos de caché adecuados según las extensiones de archivo.

¿Debería usar workers de servicio para sitios de Hugo?

Los trabajadores de servicio pueden proporcionar funcionalidad sin conexión y mejorar la percepción del rendimiento, pero son opcionales para sitios estáticos. Son más beneficiosos para sitios que necesitan acceso sin conexión o desean implementar estrategias avanzadas de almacenamiento en caché. Para la mayoría de los sitios de Hugo, el almacenamiento en caché de CDN y los encabezados HTTP adecuados son suficientes. Considere utilizar trabajadores de servicio si necesita funcionalidad centrada en la conexión sin conexión o quiere pre-cachear activos críticos.

¿Cómo configuro las cachés de archivos de Hugo?

Configure los cachés de archivos en su config.toml utilizando la sección [caches] . Hugo admite varios tipos de caché: assets , images , getjson , getcsv , getresource , misc y modules . Cada tipo de caché tiene las opciones dir (ruta del directorio) y maxAge (tiempo de expiración). Utilice tokens como :cacheDir , :resourceDir y :project para rutas dinámicas. Establezca maxAge en -1 para un almacenamiento permanente, en 0 para deshabilitarlo, o en un número positivo para una expiración basada en el tiempo. Consulte la documentación de configuración de caché de Hugo para obtener más detalles.

Estrategias de caché de Hugo para el rendimiento

Optimizar el desarrollo y ejecución de sitios Hugo

Índice

Estrategias de caché en Hugo son esenciales para maximizar el rendimiento de tu generador de sitios estáticos. Aunque Hugo genera archivos estáticos que son inherentemente rápidos, implementar un caché adecuado en múltiples capas puede mejorar drásticamente los tiempos de construcción, reducir la carga del servidor y mejorar la experiencia del usuario.

Ya sea que estés usando un tema popular de nuestro Temas más populares para Hugo o un tema personalizado, estas estrategias de caché ayudarán a optimizar el rendimiento de tu sitio.

Esta guía completa cubre el caché en tiempo de construcción, construcciones incrementales, optimización de CDN, encabezados HTTP y estrategias de caché de activos para ayudarte a lograr un rendimiento óptimo para tu sitio basado en Hugo.

chef-in-a-white con Estrategias de Caché Esta imagen agradable fue generada por modelo AI Flux 1 dev.

Entendiendo el caché de construcción de Hugo

Hugo mantiene un caché interno de construcción que almacena contenido y activos procesados para acelerar las construcciones posteriores. Este caché se encuentra en el directorio resources/_gen e incluye:

Plantillas renderizadas: Salida de plantilla preprocesada
Imágenes procesadas: Imágenes redimensionadas, optimizadas y convertidas
Activos compilados: CSS y JavaScript minimizados
Metadatos de recursos: Hashes de archivos y resultados de procesamiento

Cómo funciona el caché de construcción

Cuando ejecutas hugo, el generador:

Verifica el caché para recursos procesados existentes
Compara los tiempos de modificación de archivos y hashes de contenido
Omite el procesamiento de archivos sin cambios
Solo reconstruye contenido modificado o nuevo

Esto significa que para un sitio con 1000 publicaciones, editar una sola publicación solo requiere que Hugo procese esa publicación y regenere las páginas afectadas, no toda la web.

Administrando el caché de construcción

Puedes controlar el comportamiento del caché de Hugo usando varias banderas de línea de comandos. Para una referencia completa de los comandos de Hugo, consulta la Hoja de trucos de Hugo:

# Limpiar el caché y reconstruir todo
hugo --ignoreCache

# Usar un directorio de caché personalizado
export HUGO_CACHEDIR=/ruta/hacia/caché
hugo

# Deshabilitar el modo de renderizado rápido (fuerza una reconstrucción completa)
hugo server --disableFastRender

Para pipelines de CI/CD, considera persistir el directorio de caché entre construcciones para acelerar las implementaciones. Si estás usando Gitea Actions para la implementación, consulta nuestra guía sobre Usar Gitea Actions para implementar un sitio web de Hugo en AWS S3 para un conjunto completo de configuración de CI/CD:

# Ejemplo de flujo de trabajo de GitHub Actions
- name: Caché de recursos de Hugo
  uses: actions/cache@v3
  with:
    path: resources/_gen
    key: ${{ runner.os }}-hugo-${{ hashFiles('**/content/**') }}

Configuración de cachés de archivos

Hugo ofrece un control detallado sobre diferentes tipos de caché a través de la sección de configuración [caches]. Según la documentación de Hugo, puedes configurar varios tipos de caché:

[caches]
  [caches.assets]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.getcsv]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getjson]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getresource]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.images]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.misc]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.modules]
    dir = ':cacheDir/modules'
    maxAge = -1

Explicación de tipos de caché

assets: Caché de CSS, JavaScript y otros activos procesados por Hugo Pipes
getcsv: Caché de archivos CSV parseados cargados mediante la función getCSV
getjson: Caché de archivos JSON parseados cargados mediante la función getJSON
getresource: Caché de recursos remotos obtenidos mediante la función getResource
images: Caché de imágenes procesadas (redimensionadas, optimizadas, convertidas)
misc: Caché general para operaciones misceláneas
modules: Caché de módulos de Hugo y sus dependencias

Opciones de configuración

Cada tipo de caché admite dos opciones de configuración:

dir: La ruta absoluta del sistema de archivos donde se almacenan los archivos en caché. Puedes usar tokens:
- :cacheDir - Reemplazado por el directorio de caché configurado
- :resourceDir - Reemplazado por el directorio de recursos (normalmente resources/_gen)
- :project - Reemplazado por el nombre de la carpeta base del proyecto actual de Hugo
maxAge: La duración durante la cual una entrada en caché permanece válida antes de ser eliminada:
- 0 - Desactiva el caché
- -1 - La entrada en caché nunca expira (valor predeterminado)
- Número positivo - La entrada en caché expira después de la duración especificada (por ejemplo, 3600 para 1 hora)

Ejemplo de configuración de caché personalizada

Puedes personalizar la configuración de caché para casos de uso específicos:

[caches]
  # Mantener imágenes procesadas en caché de forma indefinida
  [caches.images]
    dir = ':resourceDir/_gen/images'
    maxAge = -1
  
  # Caché de respuestas de API JSON por 1 hora
  [caches.getjson]
    dir = ':cacheDir/:project/json'
    maxAge = 3600
  
  # Caché de recursos remotos por 24 horas
  [caches.getresource]
    dir = ':cacheDir/:project/resources'
    maxAge = 86400

Esta configuración te permite:

Mantener imágenes procesadas en caché permanentemente (ya que son deterministas)
Refrescar datos JSON cada hora (para contenido dinámico)
Cachear recursos remotos durante 24 horas (equilibrio entre frescura y rendimiento)

El token :project asegura que cada proyecto de Hugo tenga cachés aislados, por lo que al ejecutar hugo --gc (recolección de basura) solo afecta el caché del proyecto actual.

Construcciones Incrementales

El sistema de construcción incremental de Hugo es una de sus características más poderosas. Rastrea los cambios a nivel de archivo y solo reconstruye lo necesario.

Habilitando construcciones incrementales

Las construcciones incrementales están habilitadas por defecto. Hugo automáticamente:

Rastrea dependencias de archivos
Reconstruye solo las páginas cambiadas y sus dependencias
Mantiene gráficos de dependencias para actualizaciones eficientes

Consejos para el rendimiento de construcción

Usa hugo server para el desarrollo: El servidor de desarrollo usa construcciones incrementales automáticamente
Usa --minify solo en producción: La minimización agrega sobrecarga; úsala solo para construcciones finales
Optimiza el procesamiento de imágenes: Usa eficientemente las características de procesamiento de imágenes de Hugo:

[imaging]
  bgColor = '#ffffff'
  hint = 'photo'
  quality = 75
  resampleFilter = 'box'

Limita el procesamiento de recursos: Solo procesa imágenes y activos que se usan realmente

Estrategias de Caché en CDN

Las redes de entrega de contenido (CDN) son cruciales para el rendimiento global. Al desplegar sitios de Hugo en CDN como CloudFront, Cloudflare o Netlify, configura el caché adecuadamente. Para instrucciones detalladas sobre cómo desplegar tu sitio de Hugo en AWS S3 con CloudFront, consulta nuestra guía sobre Desplegar un sitio web generado por Hugo en AWS S3.

Configuración de CloudFront

Para despliegues en AWS CloudFront, configura los comportamientos de caché:

# config.toml
[[deployment.targets]]
name = "production"
URL = "s3://tu-bucket?region=us-east-1"
cloudFrontDistributionID = "E1XIDGUJGD9BU9"

Crea comportamientos de caché de CloudFront:

Activos estáticos (.css, .js, .jpg, .png, etc.):
- TTL: 1 año (31536000 segundos)
- Política de caché: CachingOptimized
- Comprimir: Sí
Páginas HTML (.html):
- TTL: 1 hora (3600 segundos)
- Política de caché: CachingDisabled (con encabezados de origen)
- Comprimir: Sí

Invalidación de caché

Automatiza la invalidación de caché en despliegues:

# Invalidar caché de CloudFront después del despliegue
aws cloudfront create-invalidation \
  --distribution-id E1XIDGUJGD9BU9 \
  --paths "/*"

O usa la función de despliegue de Hugo:

[[deployment.targets]]
name = "production"
URL = "s3://tu-bucket"
cloudFrontDistributionID = "E1XIDGUJGD9BU9"

Hugo invalidará automáticamente el caché al desplegar.

Optimización y Caché de Activos

Hugo proporciona un procesamiento de activos integrado que se combina con el caché.

Hashing de Recursos

Hugo puede agregar automáticamente hashes de contenido a los nombres de archivos:

{{ $css := resources.Get "css/main.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}">

Esto genera nombres de archivos como main.min.abc123def456.css, permitiendo un caché a largo plazo ya que el hash cambia cuando cambia el contenido.

Procesamiento y Caché de Imágenes

Procesa imágenes de forma eficiente usando el procesamiento de imágenes integrado de Hugo. Hugo almacena en caché imágenes procesadas, por lo que redimensionar la misma imagen múltiples veces solo la procesa una vez. Para un manejo de imágenes más avanzado, incluyendo la generación de metadatos de imágenes de OpenGraph, consulta nuestra guía sobre Metadatos de imágenes de OpenGraph en el generador de sitios estáticos Hugo:

{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x600" }}
<img src="{{ $resized.RelPermalink }}" alt="Foto">

Empaquetado de Activos

Empaqueta y minimiza activos:

{{ $css := slice 
    (resources.Get "css/reset.css")
    (resources.Get "css/main.css")
    (resources.Get "css/components.css")
  | resources.Concat "css/bundle.css"
  | minify
  | fingerprint
}}
<link rel="stylesheet" href="{{ $css.RelPermalink }}">

Esto crea un solo archivo CSS cachéado, minimizado y con huella digital.

Caché de Service Worker (Opcional)

Para estrategias de caché avanzadas, considera implementar service workers:

Service Worker Básico

// sw.js
const CACHE_NAME = 'hugo-site-v1';
const urlsToCache = [
  '/',
  '/css/main.css',
  '/js/main.js',
  '/images/logo.png'
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then((cache) => cache.addAll(urlsToCache))
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then((response) => response || fetch(event.request))
  );
});

Registrar Service Worker

<!-- En tu plantilla de Hugo -->
<script>
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
</script>

Monitoreo y Optimización

Monitoreo del Tiempo de Construcción

Rastrea el rendimiento de la construcción:

# Tima tus construcciones
time hugo

# Usa salida detallada para ver qué se está procesando
hugo --verbose

Tasa de aciertos en caché

Monitorea las tasas de aciertos en caché de CDN a través del panel de análisis de tu CDN. Busca:

Activos estáticos: >95% de tasa de acierto en caché
Páginas HTML: 60-80% de tasa de acierto en caché (dependiendo de la frecuencia de actualización)

Pruebas de Rendimiento

Usa herramientas como:

Lighthouse: Prueba la efectividad del caché
WebPageTest: Analiza los encabezados de caché
GTmetrix: Monitorea métricas de rendimiento

Resumen de Buenas Prácticas

Habilita el caché de construcción de Hugo: Deja que Hugo cachee recursos procesados
Usa construcciones incrementales: Solo reconstruye lo que cambia
Configura CDN adecuadamente: TTL largo para activos, más corto para páginas HTML
Establece encabezados HTTP adecuados: Usa immutable para activos con huella digital
Huella digital de activos: Añade hashes de contenido a los nombres de archivos
Invalida el caché en despliegues: Asegúrate de que los usuarios vean las actualizaciones
Monitorea el rendimiento: Rastrea tiempos de construcción y tasas de acierto en caché
Optimiza imágenes: Usa eficientemente las características de procesamiento de imágenes de Hugo
Empaqueta activos: Reduce las solicitudes HTTP con CSS/JS empaquetados
Considera service workers: Para necesidades de caché avanzadas o offline-first

Conclusión

Estrategias efectivas de caché para sitios de Hugo involucran múltiples capas: caché en tiempo de construcción para un desarrollo más rápido, caché en CDN para un rendimiento global y encabezados HTTP adecuados para el caché del navegador. Al implementar estas estrategias, puedes lograr:

Construcciones más rápidas: Las construcciones incrementales y el caché de construcción reducen los tiempos de construcción
Mejor rendimiento: El caché de CDN y del navegador mejoran los tiempos de carga
Menor carga del servidor: Los activos estáticos se cachéan en el borde
Mejora de la experiencia del usuario: Cargas más rápidas y capacidades de funcionamiento sin conexión

Recuerda que el caché es un equilibrio entre rendimiento y frescura. Los activos estáticos pueden cachéarse agresivamente, mientras que las páginas HTML deben tener tiempos de caché más cortos para garantizar que las actualizaciones de contenido sean visibles rápidamente.