Componente Image di Next.js: sizes, preload e immagini remote
Guida al componente Image di Next.js
Next.js Image: sizes, preload, remotePatterns e LCP | We.Inc
Come funziona next/image in Next.js 16: width, height e fill, un calcolatore di sizes, preload al posto di priority, remotePatterns, qualities e le larghezze srcset predefinite.
Importa Image da next/image e passagli src, alt e width e height oppure fill. Aggiungi una stringa sizes ogni volta che la larghezza visualizzata cambia con lo schermo, così il browser scarica un file più piccolo. Per l'immagine hero che costituisce il tuo LCP, imposta preload (ha sostituito priority in Next.js 16). Consenti gli host esterni con images.remotePatterns.
Le prop che decidono la velocità
Prop
Predefinito
Usala quando
width / height
L'immagine ha una dimensione fissa, o vuoi riservare le proporzioni
È il contenitore genitore a decidere la dimensione (card, hero, copertine)
il browser presume 100vw
L'immagine è responsive o usa fill
L'immagine è l'elemento LCP above the fold
Imposta eager solo per le immagini che devono caricarsi subito
Vengono serviti solo i valori elencati in images.qualities
In Next.js è facile fare due errori con le immagini: un'immagine fill senza sizes, così i telefoni scaricano file da desktop, e una hero che aspetta il caricamento lazy. Questa pagina spiega ogni prop in parole semplici, ti offre un calcolatore che scrive la stringa sizes per il tuo layout ed elenca i valori predefiniti di configurazione che Next.js usa oggi.
Scegli il layout in cui si trova l'immagine, per esempio a tutta larghezza, diviso in due colonne o una griglia di tre card.
Imposta i breakpoint usati dal tuo CSS. Il calcolatore scrive il valore sizes corrispondente.
Scegli una larghezza del telefono e una densità di pixel per vedere quale larghezza srcset predefinita il browser scaricherebbe con più probabilità.
Copia l'elemento Image finito e incollalo nel tuo componente.
Gli import statici (import hero from './hero.jpg') compilano per te width, height e blurDataURL, quindi preferiscili per le immagini che stanno nel repo.
Dai a un'immagine fill un genitore con position: relative e un'altezza reale, altrimenti si riduce a zero.
Solo un'immagine per viewport dovrebbe avere preload. Contrassegnarne diverse vanifica lo scopo e le mette in competizione per la banda.
Mantieni remotePatterns ristretto: indica il protocollo, l'hostname esatto e un prefisso di pathname invece di consentire un intero dominio.
Quando una qualità che passi non è in images.qualities, Next.js serve il valore consentito più vicino e mostra un avviso in sviluppo.
Domande frequenti
La prop priority è deprecata?
Sì. Da Next.js 16 la documentazione segna priority come deprecata a favore di preload, che inserisce un link di preload nella head. La documentazione dice anche che nella maggior parte dei casi loading="eager" o fetchPriority="high" sono la scelta migliore, e preload non va combinato con nessuna delle due.
Perché next/image dice che l'hostname non è configurato?
Le immagini esterne devono corrispondere a una voce di images.remotePatterns in next.config. Aggiungi un oggetto con protocol, hostname e un pathname come /photos/**, poi riavvia il server di sviluppo. Le richieste che non corrispondono a nessun pattern ricevono una risposta 400 dall'ottimizzatore di immagini.
Che cosa cambia davvero la prop sizes?
Dice al browser quanto sarà larga l'immagine a ogni breakpoint prima che il CSS si carichi. Con sizes, Next.js genera anche un srcset completo basato sulle larghezze (640w, 750w e così via) invece di solo 1x e 2x, così un telefono può scegliere un file molto più piccolo.
Servono width e height con fill?
No. fill e width/height sono alternative. Con fill l'immagine si estende fino al genitore posizionato, e controlli il ritaglio con object-fit tramite la prop style o className.
Per quanto tempo restano in cache le immagini ottimizzate?
Il minimumCacheTTL predefinito è 14400 secondi, cioè quattro ore. La durata massima reale è il valore più alto tra questo e l'header Cache-Control inviato dall'immagine originale. Le immagini importate staticamente ricevono una cache immutabile di lunga durata perché i nomi dei file contengono un hash.
Perché esiste il componente
Un semplice tag img invia lo stesso file a ogni dispositivo. next/image ridimensiona la sorgente su richiesta, la converte in un formato moderno accettato dal browser, la carica in modo lazy per impostazione predefinita e riserva lo spazio così il layout non salta mentre arriva.
Il problema è che può scegliere un file sensato solo quando sa quanto sarà larga l'immagine. Questo è il compito di width, height e sizes, ed è lì che avviene la maggior parte degli errori reali.
Ottenere un buon LCP
Il Largest Contentful Paint è spesso una foto hero. Caricare quella foto in modo lazy ritarda la metrica, quindi contrassegnala con preload, oppure con loading="eager" più fetchPriority="high", e lascia ogni immagine sotto la piega con il caricamento lazy predefinito.
Abbinalo a un valore sizes onesto. Una hero che occupa tutta la larghezza sui telefoni ma solo metà pagina su desktop deve dirlo, altrimenti sia gli schermi grandi sia quelli piccoli ricevono il file sbagliato.
La configurazione che toccherai
remotePatterns elenca gli host esterni di cui ti fidi. qualities è una lista consentita di valori di qualità ed è obbligatoria da Next.js 16, e la documentazione la imposta di default a 75. formats ti permette di aggiungere AVIF prima di WebP, al costo di conservare entrambe le versioni in cache.
deviceSizes e imageSizes insieme formano le larghezze candidate di ogni srcset. Raramente devi cambiarle, ma conoscere i valori predefiniti ti aiuta a capire cosa ha scaricato il browser nel pannello di rete.
Ogni prop che probabilmente userai
Prop di next/image (riferimento Next.js 16)
Prop
Tipo
Cosa fa
stringa o import statico
Percorso locale in public, file importato o URL esterno consentito da remotePatterns
Testo alternativo obbligatorio; usa una stringa vuota solo per immagini decorative
width, height
intero (px)
Dimensione intrinseca usata per le proporzioni; non serve per import statici o fill
Si estende fino al genitore posizionato invece di usare width e height
Condizioni media e larghezze degli slot che guidano la scelta dello srcset
intero da 1 a 100
Qualità di output, predefinita 75, allineata alla lista images.qualities
Aggiunge un link di preload nella head per l'immagine LCP
lazy o eager
Predefinito lazy
empty, blur o data URL
Cosa appare durante il caricamento; blur richiede blurDataURL a meno che l'immagine sia un import statico
Serve il file sorgente così com'è, senza ridimensionamento né cambio di formato
Deprecata in Next.js 16; usa preload
Valori predefiniti della configurazione delle immagini
Impostazioni images in next.config e i loro valori predefiniti
Impostazione
Predefinito
Note
deviceSizes
Larghezze per immagini a tutta larghezza e fill
imageSizes
Larghezze extra piccole, usate solo quando l'immagine ha una prop sizes
Lista consentita obbligatoria da Next.js 16
minimumCacheTTL
14400 (4 ore)
Vince il più alto tra questo e il Cache-Control dell'origine
remotePatterns
Ogni host esterno deve essere elencato
Esempi da copiare
Immagine hero da un import statico
L'import fornisce a Next.js le dimensioni reali e un placeholder sfocato. preload avvia il download dalla head.
Griglia di card con fill e sizes
Ogni card occupa un terzo della pagina su desktop, metà sui tablet e tutta la larghezza sui telefoni, e il valore sizes dice esattamente questo.
next.config.ts per un host di immagini remoto
Sono consentiti solo i file HTTPS sotto /uploads/ su un unico host. Sono ammessi due valori di qualità.
Tutta larghezza
Metà su desktop
Griglia a 2 colonne
Griglia di 3 card
Griglia di 4 card
Calcolatore di sizes
Scegli un layout e i breakpoint per generare l'attributo sizes, poi guarda quale larghezza srcset predefinita uno schermo probabilmente scaricherà.
Layout
Breakpoint telefono (px)
Breakpoint tablet (px)
Larghezza schermo: {n}px
Densità di pixel
A {screen}px lo slot dell'immagine è largo circa {slot}px ({vw}vw). Con densità {dpr}x servono {need} pixel del dispositivo, quindi il browser scaricherà con ogni probabilità il candidato {pick}w.
Copia
Larghezze candidate predefinite: {list}. I browser possono scegliere diversamente, per esempio quando un file più grande è già in cache.