Next.js-Image-Komponente: sizes, preload und externe Bilder
Leitfaden zur Next.js-Image-Komponente
Next.js Image: sizes, preload, remotePatterns und LCP | We.Inc
So funktioniert next/image in Next.js 16: width, height und fill, ein sizes-Rechner, preload als Ersatz für priority, remotePatterns, qualities und die Standardbreiten im srcset.
Importiere Image aus next/image und gib ihm src, alt sowie entweder width und height oder fill. Ergänze einen sizes-String, wann immer sich die gerenderte Breite mit dem Bildschirm ändert, damit der Browser eine kleinere Datei lädt. Setze für das Hero-Bild, das dein LCP ist, preload (es hat in Next.js 16 priority ersetzt). Erlaube externe Hosts mit images.remotePatterns.
Die Props, die über die Geschwindigkeit entscheiden
Prop
Standard
Verwende es, wenn
width / height
Das Bild eine feste Größe hat oder du das Seitenverhältnis reservieren willst
Der Elterncontainer die Größe bestimmt (Karten, Heros, Cover)
Browser nimmt 100vw an
Das Bild responsiv ist oder fill verwendet
Das Bild das LCP-Element im sichtbaren Bereich ist
Setze eager nur für Bilder, die sofort laden müssen
Nur Werte aus images.qualities werden ausgeliefert
Zwei Bildfehler passieren in Next.js leicht: ein fill-Bild ohne sizes, sodass Smartphones Desktop-Dateien laden, und ein Hero, das auf Lazy Loading wartet. Diese Seite erklärt jedes Prop in einfachen Worten, bietet dir einen Rechner, der den sizes-String für dein Layout schreibt, und listet die Konfigurationsstandards auf, die Next.js heute verwendet.
Wähle das Layout, in dem dein Bild sitzt, etwa volle Breite, eine zweispaltige Aufteilung oder ein Raster mit drei Karten.
Lege die Breakpoints fest, die dein CSS verwendet. Der Rechner schreibt den passenden sizes-Wert.
Wähle eine Smartphone-Breite und eine Pixeldichte, um zu sehen, welche Standardbreite aus dem srcset der Browser am wahrscheinlichsten lädt.
Kopiere das fertige Image-Element und füge es in deine Komponente ein.
Statische Importe (import hero from './hero.jpg') füllen width, height und blurDataURL automatisch aus. Bevorzuge sie daher für Bilder, die im Repo liegen.
Gib einem fill-Bild ein Elternelement mit position: relative und einer echten Höhe, sonst fällt es auf null zusammen.
Pro Viewport sollte nur ein Bild preload erhalten. Mehrere markierte Bilder verfehlen den Zweck und konkurrieren um Bandbreite.
Halte remotePatterns eng: Nenne das Protokoll, den genauen Hostnamen und ein Pfadpräfix, statt eine ganze Domain zu erlauben.
Wenn ein übergebener Qualitätswert nicht in images.qualities steht, liefert Next.js den nächstgelegenen erlaubten Wert aus und warnt in der Entwicklung.
Häufige Fragen
Ist das Prop priority veraltet?
Ja. Ab Next.js 16 kennzeichnet die Dokumentation priority als veraltet zugunsten von preload, das einen Preload-Link in den head einfügt. Laut Dokumentation ist in den meisten Fällen loading="eager" oder fetchPriority="high" die bessere Wahl, und preload sollte mit keinem dieser beiden Props kombiniert werden.
Warum meldet next/image, dass der Hostname nicht konfiguriert ist?
Externe Bilder müssen zu einem Eintrag in images.remotePatterns in der next.config passen. Füge ein Objekt mit protocol, hostname und einem pathname wie /photos/** hinzu und starte den Dev-Server neu. Anfragen, die zu keinem Muster passen, erhalten vom Bildoptimierer eine 400-Antwort.
Was ändert das Prop sizes eigentlich?
Es teilt dem Browser mit, wie breit das Bild an jedem Breakpoint sein wird, bevor das CSS geladen ist. Mit sizes erzeugt Next.js außerdem ein vollständiges breitenbasiertes srcset (640w, 750w und so weiter) statt nur 1x und 2x, sodass ein Smartphone eine deutlich kleinere Datei wählen kann.
Brauche ich width und height zusammen mit fill?
Nein. fill und width/height sind Alternativen. Mit fill dehnt sich das Bild auf sein positioniertes Elternelement aus, und den Zuschnitt steuerst du mit object-fit über das Prop style oder className.
Wie lange werden optimierte Bilder gecacht?
Der Standardwert für minimumCacheTTL ist 14400 Sekunden, also vier Stunden. Das tatsächliche Höchstalter ist der größere Wert von beiden: dieser Wert oder der Cache-Control-Header des Originalbildes. Statisch importierte Bilder werden langfristig und unveränderlich gecacht, weil ihre Dateinamen gehasht sind.
Warum es die Komponente gibt
Ein einfaches img-Tag schickt jedem Gerät dieselbe Datei. next/image skaliert die Quelle bei Bedarf, wandelt sie in ein modernes Format um, das der Browser akzeptiert, lädt sie standardmäßig per Lazy Loading und reserviert den Platz, damit das Layout beim Laden nicht springt.
Der Haken: Es kann nur dann eine sinnvolle Datei wählen, wenn es weiß, wie breit das Bild sein wird. Das ist die Aufgabe von width, height und sizes, und genau hier passieren die meisten Fehler in der Praxis.
LCP richtig hinbekommen
Der Largest Contentful Paint ist oft ein Hero-Foto. Lazy Loading für dieses Foto verzögert die Metrik. Markiere es daher mit preload oder mit loading="eager" plus fetchPriority="high", und lass jedes Bild unterhalb des sichtbaren Bereichs beim Standard Lazy Loading.
Kombiniere das mit einem ehrlichen sizes-Wert. Ein Hero, das auf Smartphones die volle Breite, auf dem Desktop aber nur die halbe Seite einnimmt, sollte das auch angeben, sonst bekommen große und kleine Bildschirme beide die falsche Datei.
Konfiguration, die du anfassen wirst
remotePatterns listet die externen Hosts auf, denen du vertraust. qualities ist eine Positivliste von Qualitätswerten, ab Next.js 16 Pflicht, und laut Dokumentation standardmäßig 75. Mit formats kannst du AVIF vor WebP ergänzen, musst dafür aber beide Versionen im Cache speichern.
deviceSizes und imageSizes bilden zusammen die Kandidatenbreiten in jedem srcset. Du musst sie selten ändern, aber wenn du die Standardwerte kennst, kannst du im Netzwerk-Panel besser nachvollziehen, was der Browser geladen hat.
Jedes Prop, das du wahrscheinlich nutzt
next/image-Props (Next.js-16-Referenz)
Prop
Typ
Was es tut
String oder statischer Import
Lokaler Pfad in public, importierte Datei oder eine externe URL, die remotePatterns erlaubt
Pflicht-Alternativtext; einen leeren String nur für dekorative Bilder verwenden
width, height
Ganzzahl (px)
Intrinsische Größe für das Seitenverhältnis; bei statischen Importen oder fill nicht nötig
Auf das positionierte Elternelement dehnen, statt width und height zu verwenden
Media Conditions und Slot-Breiten, die die Auswahl aus dem srcset steuern
Ganzzahl 1 bis 100
Ausgabequalität, Standard 75, auf die Liste images.qualities gerundet
Fügt für das LCP-Bild einen Preload-Link in den head ein
lazy oder eager
Standard ist lazy
empty, blur oder Data-URL
Was beim Laden angezeigt wird; blur braucht blurDataURL, außer das Bild ist statisch importiert
Die Quelldatei unverändert ausliefern, ohne Skalierung oder Formatwechsel
In Next.js 16 veraltet; stattdessen preload verwenden
Standardwerte der Bildkonfiguration
images-Einstellungen in der next.config und ihre Standardwerte
Einstellung
Standard
Hinweise
deviceSizes
Breiten für Bilder in voller Breite und fill-Bilder
imageSizes
Zusätzliche kleine Breiten, nur genutzt, wenn das Bild ein sizes-Prop hat
Pflicht-Positivliste ab Next.js 16
minimumCacheTTL
14400 (4 Stunden)
Der größere Wert von diesem und dem Cache-Control der Quelle gilt
remotePatterns
Jeder externe Host muss aufgeführt sein
Beispiele zum Kopieren
Hero-Bild aus einem statischen Import
Der Import liefert Next.js die echten Abmessungen und einen Blur-Platzhalter. preload startet den Download aus dem head.
Kartenraster mit fill und sizes
Jede Karte nimmt auf dem Desktop ein Drittel der Seite ein, auf Tablets die Hälfte und auf Smartphones die volle Breite, und der sizes-Wert sagt genau das.
next.config.ts für einen externen Bild-Host
Erlaubt sind nur HTTPS-Dateien unter /uploads/ auf einem Host. Zwei Qualitätswerte sind zulässig.
Volle Breite
Halbe Breite auf dem Desktop
Raster mit 2 Spalten
Raster mit 3 Karten
Raster mit 4 Karten
sizes-Rechner
Wähle ein Layout und Breakpoints, um das sizes-Attribut zu erzeugen, und sieh dann, welche Standardbreite aus dem srcset ein bestimmter Bildschirm wahrscheinlich lädt.
Layout
Smartphone-Breakpoint (px)
Tablet-Breakpoint (px)
Bildschirmbreite: {n}px
Pixeldichte
Bei {screen}px ist der Bildplatz etwa {slot}px breit ({vw}vw). Bei {dpr}x Dichte braucht das {need} Gerätepixel, daher lädt der Browser höchstwahrscheinlich den Kandidaten mit {pick}w.
Kopieren
Standard-Kandidatenbreiten: {list}. Browser können anders wählen, zum Beispiel wenn eine größere Datei bereits im Cache liegt.