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
- Exemplos de middleware no Next.js, atualizados para proxy.ts
- Checklist de SEO para Next.js (App Router)
- Next.js vs Node.js
- Next.js vs React
- Nginx 502 Bad Gateway e os outros erros mais comuns
- Balanceamento de carga no nginx
- Criador de agentes de IA no-code
- Tag noindex
Produto
Para quem é
- Para agências
- Para freelancers
- Para provedores de hospedagem
- Para plataformas SaaS
- Para startups
- Serviços financeiros
- Soluções para saúde
Recursos
Recursos
- Blog
- Central de Ajuda
- Ferramentas gratuitas para empresas
- Free UI Components
- Modelos
- Coleções de modelos
- Exemplos de sites
- Guias
- Comparações
- Alternativas
- Os melhores
- Avaliações
- Guias de preços
- Casos de uso
- Glossário e guias
- Integrações
- Desenvolvedores
- Benchmark
- Windows App