Componente Image do Next.js: sizes, preload e imagens remotas
Guia do componente Image do Next.js
Next.js Image: sizes, preload, remotePatterns e LCP | We.Inc
Como o next/image funciona no Next.js 16: width, height e fill, uma calculadora de sizes, preload substituindo priority, remotePatterns, qualities e as larguras padrão do srcset.
Importe Image de next/image e passe src, alt e, ou width e height, ou fill. Adicione uma string sizes sempre que a largura renderizada mudar conforme a tela, para o navegador baixar um arquivo menor. Na imagem hero que é o seu LCP, defina preload (ele substituiu priority no Next.js 16). Libere hosts externos com images.remotePatterns.
As props que definem a velocidade
Prop
Padrão
Use quando
width / height
A imagem tem tamanho fixo, ou você quer reservar a proporção
A caixa pai define o tamanho (cards, heroes, capas)
o navegador assume 100vw
A imagem é responsiva ou usa fill
A imagem é o elemento de LCP acima da dobra
Defina eager só para imagens que precisam carregar imediatamente
Só valores listados em images.qualities são servidos
Dois erros com imagens são fáceis de cometer no Next.js: uma imagem com fill sem sizes, que faz celulares baixarem arquivos de desktop, e um hero que espera o lazy loading. Esta página explica cada prop em palavras simples, traz uma calculadora que escreve a string sizes para o seu layout e lista os padrões de configuração que o Next.js usa hoje.
Escolha o layout em que a sua imagem fica, como largura total, divisão em duas colunas ou grade de três cards.
Defina os breakpoints que o seu CSS usa. A calculadora escreve o valor de sizes correspondente.
Escolha uma largura de celular e uma densidade de pixels para ver qual largura padrão do srcset o navegador provavelmente buscaria.
Copie o elemento Image pronto e cole no seu componente.
Imports estáticos (import hero from './hero.jpg') preenchem width, height e blurDataURL para você, então prefira-os para imagens que ficam no repositório.
Dê a uma imagem com fill um pai com position: relative e uma altura real, senão ela colapsa e some.
Só uma imagem por viewport deve receber preload. Marcar várias imagens anula o objetivo e faz elas disputarem banda.
Mantenha remotePatterns restrito: informe o protocolo, o hostname exato e um prefixo de pathname em vez de liberar um domínio inteiro.
Quando uma qualidade que você passa não está em images.qualities, o Next.js serve o valor permitido mais próximo e avisa em desenvolvimento.
Perguntas frequentes
A prop priority está obsoleta?
Sim. A partir do Next.js 16, a documentação marca priority como obsoleta em favor de preload, que insere um link de preload no head. A documentação também diz que, na maioria dos casos, loading="eager" ou fetchPriority="high" é a melhor escolha, e que preload não deve ser combinado com nenhuma dessas props.
Por que o next/image diz que o hostname não está configurado?
Imagens externas precisam corresponder a uma entrada em images.remotePatterns no next.config. Adicione um objeto com protocol, hostname e um pathname como /photos/**, depois reinicie o servidor de desenvolvimento. Requisições que não correspondem a nenhum padrão recebem uma resposta 400 do otimizador de imagens.
O que a prop sizes realmente muda?
Ela informa ao navegador qual será a largura da imagem em cada breakpoint antes de o CSS carregar. Com sizes, o Next.js também gera um srcset completo baseado em largura (640w, 750w e assim por diante) em vez de só 1x e 2x, então um celular pode escolher um arquivo bem menor.
Preciso de width e height com fill?
Não. fill e width/height são alternativas. Com fill a imagem se estica até o pai posicionado, e você controla o recorte com object-fit pela prop style ou className.
Por quanto tempo as imagens otimizadas ficam em cache?
O minimumCacheTTL padrão é 14400 segundos, ou seja, quatro horas. A duração real é a maior entre esse valor e o cabeçalho Cache-Control enviado pela imagem original. Imagens importadas estaticamente ganham cache imutável de longa duração porque os nomes dos arquivos têm hash.
Por que o componente existe
Uma tag img simples manda o mesmo arquivo para todo aparelho. O next/image redimensiona a origem sob demanda, converte para um formato moderno que o navegador aceita, faz lazy loading por padrão e reserva o espaço para o layout não pular enquanto ela chega.
O porém é que ele só consegue escolher um arquivo adequado quando sabe qual será a largura da imagem. Esse é o papel de width, height e sizes, e é onde acontece a maioria dos erros na prática.
Acertando o LCP
O Largest Contentful Paint muitas vezes é uma foto hero. Fazer lazy loading dessa foto atrasa a métrica, então marque-a com preload, ou com loading="eager" mais fetchPriority="high", e deixe toda imagem abaixo da dobra no padrão lazy.
Combine isso com um valor de sizes honesto. Um hero que ocupa a largura total no celular, mas só metade da página no desktop, deve dizer isso, senão telas grandes e pequenas recebem o arquivo errado.
Configurações que você vai mexer
remotePatterns lista os hosts externos em que você confia. qualities é uma lista de valores de qualidade permitidos e é obrigatória a partir do Next.js 16, e a documentação define 75 como padrão. formats permite adicionar AVIF antes de WebP, ao custo de guardar as duas versões no cache.
deviceSizes e imageSizes juntos formam as larguras candidatas de todo srcset. Raramente é preciso mudá-los, mas conhecer os padrões ajuda a entender o que o navegador baixou no painel de rede.
Todas as props que você provavelmente vai usar
Props do next/image (referência do Next.js 16)
Prop
Tipo
O que faz
string ou import estático
Caminho local em public, arquivo importado ou URL externa liberada por remotePatterns
Texto alternativo obrigatório; use string vazia só para imagens decorativas
width, height
inteiro (px)
Tamanho intrínseco usado para a proporção; dispensável com imports estáticos ou fill
Estica até o pai posicionado em vez de usar width e height
Condições de mídia e larguras de slot que orientam a escolha no srcset
inteiro de 1 a 100
Qualidade de saída, padrão 75, ajustada à lista images.qualities
Adiciona um link de preload no head para a imagem do LCP
lazy ou eager
O padrão é lazy
empty, blur ou data URL
O que aparece durante o carregamento; blur precisa de blurDataURL, a menos que a imagem seja um import estático
Serve o arquivo de origem como está, sem redimensionar nem mudar o formato
Obsoleta no Next.js 16; use preload no lugar
Padrões da configuração de imagens
Configurações de images no next.config e seus padrões
Configuração
Padrão
Observações
deviceSizes
Larguras para imagens de largura total e com fill
imageSizes
Larguras extra pequenas, usadas só quando a imagem tem a prop sizes
Lista de permissões obrigatória a partir do Next.js 16
minimumCacheTTL
14400 (4 horas)
Vale o maior entre este valor e o Cache-Control de origem
remotePatterns
Cada host externo precisa estar listado
Exemplos para copiar
Imagem hero a partir de um import estático
O import fornece ao Next.js as dimensões reais e um placeholder com blur. O preload inicia o download a partir do head.
Grade de cards com fill e sizes
Cada card ocupa um terço da página no desktop, metade em tablets e a largura total em celulares, e o valor de sizes diz exatamente isso.
next.config.ts para um host de imagens remoto
Só arquivos HTTPS em /uploads/ de um único host são permitidos. Dois valores de qualidade são aceitos.
Largura total
Metade no desktop
Grade de 2 colunas
Grade de 3 cards
Grade de 4 cards
Calculadora de sizes
Escolha um layout e os breakpoints para gerar o atributo sizes e veja qual largura padrão do srcset uma determinada tela provavelmente vai baixar.
Layout
Breakpoint de celular (px)
Breakpoint de tablet (px)
Largura da tela: {n}px
Densidade de pixels
Em {screen}px o espaço da imagem tem cerca de {slot}px de largura ({vw}vw). Com densidade {dpr}x, isso exige {need} pixels do dispositivo, então o navegador provavelmente vai buscar a candidata de {pick}w.
Copiar
Larguras candidatas padrão: {list}. Os navegadores podem escolher de outro jeito, por exemplo quando um arquivo maior já está em cache.