Hospedagem eficiente de imagens: CDNs e processamento

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Entrega estática e transformação de imagens resolvem problemas diferentes. Uma CDN estática armazena em cache arquivos que já existem; ela não redimensiona um JPEG só porque você acrescentou ?width=800. Este guia combina variantes pré-geradas, armazenamento privado na origem e entrega pública pela CDN.

Introdução à hospedagem de imagens com CDNs estáticas

Gere as variantes de que suas páginas precisam durante a publicação, envie-as com nomes de arquivo imutáveis e deixe a CDN entregá-las. Uma origem de transformação separada é útil quando as dimensões não podem ser conhecidas com antecedência, mas ela exige validação, limites de recursos e um cache que leve as variantes em conta.

Por que usar CDNs estáticas para hospedar imagens?

O cache pode reduzir o tráfego repetido até a origem e melhorar a entrega para usuários distribuídos geograficamente. A pré-geração evita o trabalho de decodificação em tempo de execução a cada nova requisição de imagem. Em contrapartida, você gasta armazenamento e tempo de publicação com variantes que talvez nunca sejam requisitadas.

Principais benefícios das CDNs estáticas para desenvolvedores

Variantes imutáveis tornam a depuração concreta: uma URL identifica um arquivo real com dimensões, formato e conteúdo conhecidos. Elas também evitam confundir falhas na geração de imagens com falhas na entrega.

Configurar uma CDN de hospedagem de imagens: guia passo a passo

Para S3 e CloudFront, siga a configuração atual de origem privada da AWS:

Crie um bucket S3 com Block Public Access ativado e com a propriedade de objetos atribuída obrigatoriamente ao proprietário do bucket.
Adicione o endpoint regular do bucket S3 como origem do CloudFront, e não o endpoint de site.
Associe um controle de acesso à origem (OAC) que sempre assine as requisições.
Conceda acesso de leitura à entidade principal de serviço do CloudFront por meio de uma política de bucket restrita ao ARN da sua distribuição.
Exija HTTPS para os visitantes. Teste primeiro o hostname do CloudFront; um hostname personalizado também precisa do seu certificado e do alias da distribuição, e não apenas de um registro DNS.
Envie as variantes públicas aprovadas e depois verifique se o CloudFront consegue lê-las enquanto o acesso anônimo ao S3 continua negado.

O OAC protege a conexão com a origem. Ele não autentica as pessoas que visitam uma URL pública do CloudFront.

Integrar processamento de imagens sob demanda: economize tempo e banda

Escolha conscientemente entre variantes pré-geradas e um serviço de transformação. Se você precisa de redimensionamento arbitrário, use uma origem de processamento ou um serviço como o Smart CDN da Transloadit. Verifique o contrato de parâmetros e de assinatura desse serviço; objetos estáticos do S3/CloudFront não interpretam parâmetros de consulta de transformação.

Exemplo: imagens responsivas pré-geradas

Para este exemplo, prepare uma imagem de entrada opaca com pelo menos 1280 pixels de largura após a orientação. O script abaixo cria três arquivos WebP no momento da publicação. São arquivos reais, e não URLs dinâmicas imaginárias de CDN:

<picture>
  <source
    type="image/webp"
    srcset="/images/photo-320-v1.webp 320w, /images/photo-640-v1.webp 640w, /images/photo-1280-v1.webp 1280w"
    sizes="(max-width: 640px) 100vw, 640px"
  >
  <img
    id="hero"
    src="/images/photo-640-v1.jpg"
    alt="A description of your photograph"
    width="640"
    height="360"
    style="max-width: 100%; height: auto"
  >
</picture>

Substitua as URLs de exemplo pelo hostname da sua CDN e defina width e height com as dimensões reais do fallback exibidas pelo script. O valor de sizes precisa corresponder ao layout da imagem. O JPEG é o fallback para navegadores que não selecionam WebP.

Ferramentas e bibliotecas para processamento de imagens

Sharp (Node.js)

Instale sharp@0.35.4 com Node.js 24 ou mais recente. Coloque isto em build-images.mjs, forneça seu próprio photo.jpg e execute node build-images.mjs. Este é um script de publicação confiável, e não um endpoint de upload:

import { mkdir, open, writeFile } from 'node:fs/promises'
import sharp from 'sharp'

async function main() {
  const file = await open('photo.jpg', 'r')
  let source
  try {
    const stat = await file.stat()
    if (!stat.isFile() || stat.size < 1 || stat.size > 8 * 1024 * 1024) {
      throw new Error('Use a regular source image no larger than 8 MiB.')
    }
    source = Buffer.alloc(stat.size)
    let offset = 0
    while (offset < source.length) {
      const { bytesRead } = await file.read(source, offset, source.length - offset, null)
      if (bytesRead === 0) throw new Error('Source changed during publishing.')
      offset += bytesRead
    }
  } finally {
    await file.close()
  }
  const options = { limitInputPixels: 12_000_000, failOn: 'warning' }
  const metadata = await sharp(source, options).metadata()
  if (!['jpeg', 'png'].includes(metadata.format) || (metadata.pages ?? 1) !== 1) {
    throw new Error('Use a single-frame JPEG or PNG.')
  }
  const orientedWidth = metadata.autoOrient?.width ?? metadata.width
  if (!orientedWidth || orientedWidth < 1280) throw new Error('Source must be at least 1280px wide.')
  await mkdir('images', { recursive: true })
  for (const width of [320, 640, 1280]) {
    const result = await sharp(source, options).rotate().resize({ width }).webp({ quality: 80 })
      .toBuffer({ resolveWithObject: true })
    await writeFile('images/photo-' + width + '-v1.webp', result.data, { flag: 'wx' })
  }
  const fallback = await sharp(source, options).rotate().resize({ width: 640 })
    .flatten({ background: 'white' }).jpeg({ quality: 80 }).toBuffer({ resolveWithObject: true })
  await writeFile('images/photo-640-v1.jpg', fallback.data, { flag: 'wx' })
  console.log(JSON.stringify({ width: fallback.info.width, height: fallback.info.height }))
}
main().catch(() => {
  console.error('Image publishing failed. Review the input and output directory.')
  process.exitCode = 1
})

Não modifique a entrada durante uma execução. As gravações exclusivas impedem que uma versão existente seja sobrescrita. Uma execução com falha pode deixar arquivos parciais: inspecione-os antes de tentar novamente. Use uma nova versão tanto nos nomes de arquivo quanto no HTML em publicações posteriores, ou adicione nomes de arquivo com hash do conteúdo no seu pipeline de build. Por padrão, o Sharp remove os metadados da origem; verifique se a orientação e o comportamento de cor ficam como você deseja.

ImageMagick

O ImageMagick 7 oferece uma alternativa de linha de comando para uma origem confiável:

magick photo.jpg -auto-orient -resize '640x640>' -strip -quality 80 photo-small.webp

Isso encaixa a imagem dentro de um quadrado sem ampliá-la, então sua geometria difere das variantes do Sharp, que só definem a largura. Confira as dimensões de saída antes de usá-la em srcset. Para arquivos não confiáveis, isole o processo e configure políticas de decodificadores e de recursos.

Cloudinary

Serviços de transformação hospedados definem a própria gramática de URL e os locais de origem permitidos. Siga a referência de transformações do Cloudinary ou a documentação equivalente do seu provedor. Uma URL de um provedor não pode ser usada como contrato genérico de redimensionamento em outra CDN.

Boas práticas para otimizar a entrega de imagens via CDN

Use tempos de cache longos apenas para objetos imutáveis e versionados. Defina os tipos de conteúdo corretos e reserve as dimensões de layout da imagem. Mantenha suas candidatas responsivas consistentes com as dimensões reais de saída. Não envie originais privados para o prefixo público de publicação.

Envie os arquivos gerados do diretório images/ para um prefixo aprovado de conteúdo público no seu bucket de origem privada. Defina os metadados de cache-control intencionalmente e depois inspecione os cabeçalhos de resposta da CDN. Alterar os metadados na origem não substitui instantaneamente as respostas que já estão em cache.

Considerações de segurança ao usar CDNs

Origens privadas e entrega privada são controles separados. Para acesso privado de visitantes, configure URLs ou cookies assinados do CloudFront e o grupo de chaves confiáveis associado. Uma URL pré-assinada do S3 não assina automaticamente o CloudFront.

Mantenha as chaves de assinatura no servidor, autorize o objeto solicitado antes de conceder acesso e evite registrar em log query strings assinadas. Não publique respostas privadas com uma política de cache público compartilhado.

Solucionar desafios comuns na hospedagem de imagens em CDN

Invalidação de cache

Prefira um novo nome de arquivo imutável para uma nova imagem. Quando a invalidação for necessária, restrinja-a apenas à distribuição e aos caminhos pretendidos. Uma invalidação é uma operação real na conta e pode ter custo; não a execute como comando genérico de depuração contra a produção.

Tratamento de erros de carregamento de imagem

Remova os elementos source com falha dentro de picture antes de usar um fallback; caso contrário, o navegador pode continuar selecionando a candidata quebrada. Tente o fallback apenas uma vez:

function installImageFallback(image, fallbackUrl) {
  image.addEventListener('error', () => {
    for (const source of image.closest('picture')?.querySelectorAll('source') ?? []) {
      source.remove()
    }
    image.removeAttribute('srcset')
    image.removeAttribute('sizes')
    image.src = fallbackUrl
  }, { once: true })
}

const hero = document.getElementById('hero')
if (hero instanceof HTMLImageElement) installImageFallback(hero, '/images/placeholder.png')

Disponibilize um placeholder real nesse caminho e registre o handler antes de carregar as imagens quando a falha puder acontecer imediatamente. Se o placeholder também falhar, o navegador mantém o texto alternativo acessível; o handler não entra em loop.

Monitoramento de desempenho

Só instale um observador de Largest Contentful Paint quando o navegador oferecer suporte:

if (typeof PerformanceObserver !== 'undefined' &&
    PerformanceObserver.supportedEntryTypes.includes('largest-contentful-paint')) {
  const observer = new PerformanceObserver((list) => {
    const latest = list.getEntries().at(-1)
    if (latest) console.log('Observed LCP candidate in milliseconds:', latest.startTime)
  })
  observer.observe({ type: 'largest-contentful-paint', buffered: true })
  window.addEventListener('pagehide', () => observer.disconnect(), { once: true })
}

Este é um diagnóstico local, e não uma implementação completa de relatórios de Web Vitals. Ele intencionalmente não registra URLs de imagem, que podem conter tokens de acesso. Compare dispositivos, condições de rede e estados de cache representativos antes de tirar conclusões sobre desempenho.