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.

Crie seu site grátis · Grátis para criar, sem cartão

Relacionados: Guias

Produto

Para quem é

Recursos

Recursos

Empresa

Mapa do site