O que é o cache de compilação do Hugo e como ele funciona?

O cache de compilação do Hugo armazena conteúdo renderizado e ativos processados para acelerar compilações subsequentes. Ele está localizado no diretório resources/_gen e armazena imagens processadas, CSS, JavaScript e templates renderizados. O Hugo usa automaticamente esse cache para evitar a reprocessamento de conteúdo que não foi alterado, reduzindo significativamente o tempo de compilação para sites grandes.

Como posso habilitar builds incrementais no Hugo?

Use a bandeira --ignoreCache para desativar o cache ou hugo server com --disableFastRender para forçar reconstruções completas. Para builds incrementais, basta executar hugo sem bandeiras — o Hugo usa automaticamente o conteúdo em cache quando os arquivos de origem não foram alterados. A variável de ambiente HUGO_CACHEDIR pode especificar um local de cache personalizado.

Quais cabeçalhos HTTP devo definir para ativos estáticos do Hugo?

Defina um cache agressivo para ativos estáticos (CSS, JS, imagens) - Cache-Control: public, max-age=31536000, immutable (1 ano). Para páginas HTML, utilize tempos de cache mais curtos - Cache-Control: public, max-age=3600 (1 hora) com cabeçalhos ETag ou Last-Modified . Isso permite que os navegadores armazenem ativos por um longo período, mantendo as páginas HTML atualizadas.

Como configuro o cache de CDN para um site Hugo?

Configure seu CDN (CloudFront, Cloudflare, etc.) para armazenar em cache ativos estáticos com TTLs longos (1 ano) e HTML com TTLs mais curtos (1 hora). Configure a invalidação do cache durante as implantações. Para o CloudFront, use o cloudFrontDistributionID na configuração de implantação do Hugo. Ative a compressão (gzip/brotli) e defina comportamentos de cache apropriados com base nas extensões de arquivo.

Devo usar service workers para sites Hugo?

Os service workers podem fornecer funcionalidade offline e melhorar a performance percebida, mas são opcionais para sites estáticos. Eles são mais benéficos para sites que precisam de acesso offline ou desejam implementar estratégias avançadas de cache. Para a maioria dos sites Hugo, o cache do CDN e cabeçalhos HTTP adequados são suficientes. Considere o uso de service workers se precisar de funcionalidade offline-first ou quiser pré-carregar ativos críticos.

Como configuro os caches de arquivos do Hugo?

Configure caches de arquivos no seu config.toml usando a seção [caches] . O Hugo suporta vários tipos de cache: assets , images , getjson , getcsv , getresource , misc e modules . Cada tipo de cache possui as opções dir (caminho do diretório) e maxAge (tempo de expiração). Utilize tokens como :cacheDir , :resourceDir e :project para caminhos dinâmicos. Defina maxAge como -1 para caching permanente, 0 para desativar, ou um número positivo para expiração baseada em tempo. Veja a documentação de configuração de cache do Hugo para mais detalhes.

Estratégias de Cache do Hugo para Desempenho

Otimize o desenvolvimento e a execução de sites Hugo

Conteúdo da página

Estratégias de cache no Hugo são essenciais para maximizar o desempenho do seu gerador de sites estáticos. Embora o Hugo gere arquivos estáticos que são naturalmente rápidos, a implementação de um cache adequado em múltiplas camadas pode melhorar drasticamente os tempos de construção, reduzir a carga do servidor e melhorar a experiência do usuário.

Seja você usando um tema popular do nosso guia Temas mais populares para o Hugo ou um tema personalizado, essas estratégias de cache ajudarão a otimizar o desempenho do seu site.

Este guia abrangente aborda o cache de tempo de construção, builds incrementais, otimização de CDN, cabeçalhos HTTP e estratégias de cache de ativos para ajudá-lo a alcançar o desempenho ideal para seu site baseado no Hugo.

chef-in-a-white com Estratégias de Cache Esta imagem agradável foi gerada pelo modelo AI Flux 1 dev.

Entendendo o Cache de Construção do Hugo

O Hugo mantém um cache interno de construção que armazena conteúdo e ativos processados para acelerar construções subsequentes. Esse cache está localizado no diretório resources/_gen e inclui:

Modelos renderizados: Saída de modelos pré-processados
Imagens processadas: Imagens redimensionadas, otimizadas e convertidas
Ativos compilados: CSS e JavaScript minimificados
Metadados de recursos: Hashes de arquivos e resultados de processamento

Como o Cache de Construção Funciona

Quando você executa hugo, o gerador:

Verifica o cache para recursos processados existentes
Compara os tempos de modificação dos arquivos e hashes de conteúdo
Pula o processamento de arquivos não alterados
Recria apenas o conteúdo modificado ou novo

Isso significa que, para um site com 1000 posts, editar um único post só exige que o Hugo processe esse único post e regenere as páginas afetadas, não o site inteiro.

Gerenciando o Cache de Construção

Você pode controlar o comportamento do cache do Hugo usando várias opções de linha de comando. Para uma referência abrangente dos comandos do Hugo, veja a Folha de Dicas do Hugo:

# Limpar o cache e reconstruir tudo
hugo --ignoreCache

# Usar um diretório de cache personalizado
export HUGO_CACHEDIR=/caminho/para/cache
hugo

# Desativar o modo de renderização rápida (força reconstrução completa)
hugo server --disableFastRender

Para pipelines CI/CD, considere persistir o diretório de cache entre as construções para acelerar os deploys. Se você estiver usando Gitea Actions para o deploy, veja nosso guia sobre Usar Gitea Actions para implantar um site Hugo no AWS S3 para uma configuração completa de CI/CD:

# Exemplo de fluxo de trabalho do GitHub Actions
- name: Cache de recursos do Hugo
  uses: actions/cache@v3
  with:
    path: resources/_gen
    key: ${{ runner.os }}-hugo-${{ hashFiles('**/content/**') }}

Configurando Caches de Arquivos

O Hugo oferece controle granular sobre diferentes tipos de cache através da seção de configuração [caches]. De acordo com a documentação do Hugo, você pode configurar vários tipos de cache:

[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

Explicação dos Tipos de Cache

assets: Cacha ativos processados como CSS, JavaScript e outros ativos do Hugo Pipes
getcsv: Cacha arquivos CSV parseados carregados via função getCSV
getjson: Cacha arquivos JSON parseados carregados via função getJSON
getresource: Cacha recursos remotos carregados via função getResource
images: Cacha imagens processadas (redimensionadas, otimizadas, convertidas)
misc: Cache geral para operações diversas
modules: Cacha módulos do Hugo e suas dependências

Opções de Configuração

Cada tipo de cache suporta duas opções de configuração:

dir: O caminho absoluto no sistema de arquivos onde os arquivos cacheados são armazenados. Você pode usar tokens:
- :cacheDir - Substituído pelo diretório de cache configurado
- :resourceDir - Substituído pelo diretório de recursos (normalmente resources/_gen)
- :project - Substituído pelo nome da pasta base do projeto atual do Hugo
maxAge: A duração que uma entrada cacheada permanece válida antes de ser expirada:
- 0 - Desativa o cache
- -1 - A entrada cacheada nunca expira (padrão)
- Número positivo - O cache expira após a duração especificada (ex: 3600 para 1 hora)

Exemplo de Configuração de Cache Personalizado

Você pode personalizar as configurações de cache para casos específicos:

[caches]
  # Mantenha imagens processadas cacheadas indefinidamente
  [caches.images]
    dir = ':resourceDir/_gen/images'
    maxAge = -1
  
  # Cache respostas de API JSON por 1 hora
  [caches.getjson]
    dir = ':cacheDir/:project/json'
    maxAge = 3600
  
  # Cache recursos remotos por 24 horas
  [caches.getresource]
    dir = ':cacheDir/:project/resources'
    maxAge = 86400

Essa configuração permite que você:

Mantenha imagens processadas cacheadas permanentemente (já que são determinísticas)
Atualize dados JSON a cada hora (para conteúdo dinâmico)
Cache recursos remotos por 24 horas (equilíbrio entre frescor e desempenho)

O token :project garante que cada projeto do Hugo tenha caches isolados, então ao executar hugo --gc (coleta de lixo), apenas o cache do projeto atual é afetado.

Builds Incrementais

O sistema de build incremental do Hugo é uma das suas funcionalidades mais poderosas. Ele rastreia alterações no nível de arquivo e só reconstrói o que for necessário.

Habilitando Builds Incrementais

Builds incrementais estão habilitados por padrão. O Hugo automaticamente:

Rastreia dependências de arquivos
Reconstrói apenas páginas alteradas e suas dependências
Mantém gráficos de dependência para atualizações eficientes

Dicas de Desempenho de Build

Use hugo server para desenvolvimento: O servidor de desenvolvimento usa builds incrementais automaticamente
Use --minify apenas em produção: A minificação adiciona sobrecarga; use-a apenas para builds finais
Otimize o processamento de imagens: Use as funcionalidades de processamento de imagem do Hugo de forma eficiente:

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

Limite o processamento de recursos: Apenas processe imagens e ativos que realmente são usados

Estratégias de Cache em CDN

Redes de Entrega de Conteúdo (CDN) são cruciais para o desempenho global. Ao implantar sites do Hugo em CDNs como CloudFront, Cloudflare ou Netlify, configure o cache apropriadamente. Para instruções detalhadas sobre como implantar seu site do Hugo no AWS S3 com CloudFront, veja nosso guia sobre Implantar um site gerado pelo Hugo no AWS S3.

Configuração do CloudFront

Para implantações no AWS CloudFront, configure comportamentos de cache:

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

Crie comportamentos de cache do CloudFront:

Ativos estáticos (.css, .js, .jpg, .png, etc.):
- TTL: 1 ano (31536000 segundos)
- Política de cache: CachingOptimized
- Comprimir: Sim
Páginas HTML (.html):
- TTL: 1 hora (3600 segundos)
- Política de cache: CachingDisabled (com cabeçalhos de origem)
- Comprimir: Sim

Invalidação de Cache

Automatize a invalidação de cache durante as implantações:

# Invalidar cache do CloudFront após a implantação
aws cloudfront create-invalidation \
  --distribution-id E1XIDGUJGD9BU9 \
  --paths "/*"

Ou use a funcionalidade de implantação do Hugo:

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

O Hugo invalidará automaticamente o cache ao implantar.

Otimização e Cache de Ativos

O Hugo oferece processamento de ativos integrado que se combina com o cache.

Hash de Recursos

O Hugo pode adicionar automaticamente hashes de conteúdo aos nomes de arquivos:

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

Isso gera nomes de arquivos como main.min.abc123def456.css, permitindo cache de longo prazo, pois o hash muda quando o conteúdo muda.

Processamento e Cache de Imagens

Processe imagens de forma eficiente usando o processamento de imagem integrado do Hugo. O Hugo cacheia imagens processadas, então redimensionar a mesma imagem várias vezes só processa uma vez. Para um tratamento mais avançado de imagens, incluindo geração de metadados de imagem OpenGraph, veja nosso guia sobre Metadados de imagem OpenGraph no gerador de sites estáticos Hugo:

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

Empacotamento de Ativos

Empacote e minimize ativos:

{{ $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 }}">

Isso cria um único arquivo CSS cacheado, minimizado e com hash de conteúdo.

Cache de Service Worker (Opcional)

Para estratégias de cache avançadas, considere a implementação de 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

<!-- Em seu modelo do Hugo -->
<script>
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
</script>

Monitoramento e Otimização

Monitoramento de Tempo de Construção

Monitore o desempenho das construções:

# Meça o tempo das construções
time hugo

# Use saída detalhada para ver o que está sendo processado
hugo --verbose

Taxas de Acerto de Cache

Monitore as taxas de acerto de cache do CDN através do painel de análise do seu CDN. Almeje:

Ativos estáticos: >95% taxa de acerto de cache
Páginas HTML: 60-80% taxa de acerto de cache (dependendo da frequência de atualização)

Testes de Desempenho

Use ferramentas como:

Lighthouse: Teste a eficácia do cache
WebPageTest: Analise os cabeçalhos de cache
GTmetrix: Monitore métricas de desempenho

Resumo das Boas Práticas

Ative o cache de construção do Hugo: Permita que o Hugo cacheie recursos processados
Use builds incrementais: Apenas reconstrua o que foi alterado
Configure o CDN corretamente: TTL longo para ativos, mais curto para páginas HTML
Defina cabeçalhos HTTP apropriados: Use immutable para ativos com hash
Fingerprint os ativos: Adicione hashes de conteúdo aos nomes dos arquivos
Invalidar o cache durante as implantações: Garanta que os usuários vejam as atualizações
Monitore o desempenho: Rastreie tempos de construção e taxas de acerto de cache
Otimize as imagens: Use o processamento de imagem do Hugo de forma eficiente
Empacote os ativos: Reduza as solicitações HTTP com CSS/JS empacotados
Considere service workers: Para necessidades de cache offline ou avançadas

Conclusão

Estratégias eficazes de cache para sites do Hugo envolvem múltiplas camadas: cache de tempo de construção para desenvolvimento mais rápido, cache de CDN para desempenho global e cabeçalhos HTTP apropriados para cache do navegador. Ao implementar essas estratégias, você pode alcançar:

Construções mais rápidas: Builds incrementais e cache de construção reduzem os tempos de construção
Melhor desempenho: Cache de CDN e navegador melhoram os tempos de carregamento
Redução da carga do servidor: Ativos estáticos cacheados na borda
Experiência do usuário melhorada: Carregamento mais rápido das páginas e capacidade offline

Lembre-se de que o cache é um equilíbrio entre desempenho e frescor. Ativos estáticos podem ser cacheados de forma agressiva, enquanto páginas HTML devem ter tempos de cache mais curtos para garantir que as atualizações de conteúdo sejam visíveis rapidamente.