<Image>
Beispiele
Diese API-Referenz hilft dir dabei, die verfügbaren Props und Konfigurationsoptionen der Image-Komponente zu verstehen. Für Features und Verwendung, siehe die Seite Image Component.
Props
Hier ist eine Übersicht der verfügbaren Props für die Image-Komponente:
Prop | Beispiel | Typ | Status |
---|---|---|---|
src | src="/profile.png" | String | Erforderlich |
width | width={500} | Integer (px) | Erforderlich |
height | height={500} | Integer (px) | Erforderlich |
alt | alt="Bild des Autors" | String | Erforderlich |
loader | loader={imageLoader} | Function | - |
fill | fill={true} | Boolean | - |
sizes | sizes="(max-width: 768px) 100vw, 33vw" | String | - |
quality | quality={80} | Integer (1-100) | - |
priority | priority={true} | Boolean | - |
placeholder | placeholder="blur" | String | - |
style | style={{objectFit: "contain"}} | Object | - |
onLoadingComplete | onLoadingComplete={img => done())} | Function | Deprecated |
onLoad | onLoad={event => done())} | Function | - |
onError | onError(event => fail()} | Function | - |
loading | loading="lazy" | String | - |
blurDataURL | blurDataURL="data:image/jpeg..." | String | - |
overrideSrc | overrideSrc="/seo.png" | String | - |
Erforderliche Props
Die Image-Komponente erfordert die folgenden Eigenschaften: src
, alt
, width
und height
(oder fill
).
src
Muss eines der folgenden sein:
- Eine statisch importierte Bilddatei
- Ein Pfad als String. Dies kann entweder eine absolute externe URL oder ein interner Pfad sein, abhängig von der loader-Prop.
Bei Verwendung des Standard-Loaders beachte zudem folgendes für Quellbilder:
- Wenn src eine externe URL ist, muss zusätzlich remotePatterns konfiguriert werden
- Wenn src animiert ist oder kein bekanntes Format hat (JPEG, PNG, WebP, AVIF, GIF, TIFF), wird das Bild unverändert ausgeliefert
- Wenn src im SVG-Format vorliegt, wird es blockiert, außer
unoptimized
oderdangerouslyAllowSVG
ist aktiviert
width
Die width
-Eigenschaft repräsentiert die intrinsische Bildbreite in Pixeln. Diese Eigenschaft wird verwendet, um das korrekte Seitenverhältnis des Bildes abzuleiten und Layout-Verschiebungen während des Ladens zu vermeiden. Sie bestimmt nicht die gerenderte Größe des Bildes, die durch CSS gesteuert wird, ähnlich wie das width
-Attribut im HTML <img>
-Tag.
Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill
-Eigenschaft.
height
Die height
-Eigenschaft repräsentiert die intrinsische Bildhöhe in Pixeln. Diese Eigenschaft wird verwendet, um das korrekte Seitenverhältnis des Bildes abzuleiten und Layout-Verschiebungen während des Ladens zu vermeiden. Sie bestimmt nicht die gerenderte Größe des Bildes, die durch CSS gesteuert wird, ähnlich wie das height
-Attribut im HTML <img>
-Tag.
Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill
-Eigenschaft.
Hinweis:
- Zusammen werden die
width
- undheight
-Eigenschaften verwendet, um das Seitenverhältnis des Bildes zu bestimmen, das von Browsern genutzt wird, um Platz für das Bild zu reservieren, bevor es geladen wird.- Die intrinsische Größe bedeutet nicht immer die gerenderte Größe im Browser, die durch den übergeordneten Container bestimmt wird. Wenn der übergeordnete Container beispielsweise kleiner ist als die intrinsische Größe, wird das Bild verkleinert, um in den Container zu passen.
- Du kannst die
fill
-Eigenschaft verwenden, wenn die Breite und Höhe unbekannt sind.
alt
Die alt
-Eigenschaft wird verwendet, um das Bild für Screenreader und Suchmaschinen zu beschreiben. Sie dient auch als Fallback-Text, wenn Bilder deaktiviert sind oder ein Fehler beim Laden des Bildes auftritt.
Sie sollte Text enthalten, der das Bild ohne Änderung der Bedeutung der Seite ersetzen könnte. Sie ist nicht dazu gedacht, das Bild zu ergänzen und sollte keine Informationen wiederholen, die bereits in den Bildunterschriften über oder unter dem Bild enthalten sind.
Wenn das Bild rein dekorativ ist oder nicht für den Benutzer bestimmt ist, sollte die alt
-Eigenschaft ein leerer String sein (alt=""
).
Optionale Props
Die <Image />
-Komponente akzeptiert eine Reihe zusätzlicher Eigenschaften neben den erforderlichen. Dieser Abschnitt beschreibt die am häufigsten verwendeten Eigenschaften der Image-Komponente. Details zu selteneren Eigenschaften findest du im Abschnitt Erweiterte Props.
loader
Eine benutzerdefinierte Funktion zur Auflösung von Bild-URLs.
Ein loader
ist eine Funktion, die eine URL-Zeichenkette für das Bild zurückgibt, basierend auf den folgenden Parametern:
Hier ist ein Beispiel für die Verwendung eines benutzerdefinierten Loaders:
Hinweis: Die Verwendung von Props wie
loader
, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.
Alternativ kannst du die loaderFile-Konfiguration in next.config.js
verwenden, um jede Instanz von next/image
in deiner Anwendung zu konfigurieren, ohne eine Prop übergeben zu müssen.
fill
Ein Boolean, der bewirkt, dass das Bild das übergeordnete Element ausfüllt, was nützlich ist, wenn width
und height
unbekannt sind.
Das übergeordnete Element muss den Style position: "relative"
, position: "fixed"
oder position: "absolute"
zugewiesen bekommen.
Standardmäßig wird dem img-Element automatisch der Style position: "absolute"
zugewiesen.
Wenn keine Styles auf das Bild angewendet werden, wird das Bild gedehnt, um in den Container zu passen. Du kannst object-fit: "contain"
für ein Bild festlegen, das letterboxed wird, um in den Container zu passen und das Seitenverhältnis zu bewahren.
Alternativ wird object-fit: "cover"
dazu führen, dass das Bild den gesamten Container ausfüllt und beschnitten wird, um das Seitenverhältnis zu bewahren.
Für weitere Informationen siehe auch:
sizes
Eine Zeichenkette, ähnlich einer Medienabfrage, die Informationen darüber liefert, wie breit das Bild bei verschiedenen Breakpoints sein wird. Der Wert von sizes
wird die Leistung für Bilder stark beeinflussen, die fill
verwenden oder responsive gestylt sind.
Die sizes
-Eigenschaft dient zwei wichtigen Zwecken im Zusammenhang mit der Bildleistung:
- Erstens wird der Wert von
sizes
vom Browser verwendet, um zu bestimmen, welche Größe des Bildes aus dem automatisch generiertensrcset
vonnext/image
heruntergeladen werden soll. Wenn der Browser auswählt, kennt er die Größe des Bildes auf der Seite noch nicht, daher wählt er ein Bild aus, das genauso groß oder größer als der Viewport ist. Diesizes
-Eigenschaft ermöglicht es dir, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als der volle Bildschirm sein wird. Wenn du keinensizes
-Wert in einem Bild mit derfill
-Eigenschaft angibst, wird ein Standardwert von100vw
(volle Bildschirmbreite) verwendet. - Zweitens ändert die
sizes
-Eigenschaft das Verhalten des automatisch generiertensrcset
-Wertes. Wenn keinsizes
-Wert vorhanden ist, wird ein kleinessrcset
generiert, das für ein Bild mit fester Größe (1x/2x/etc.) geeignet ist. Wennsizes
definiert ist, wird ein großessrcset
generiert, das für ein responsives Bild (640w/750w/etc.) geeignet ist. Wenn diesizes
-Eigenschaft Größen wie50vw
enthält, die einen Prozentsatz der Viewport-Breite darstellen, dann wird dassrcset
gekürzt, um keine Werte zu enthalten, die zu klein sind, um jemals benötigt zu werden.
Wenn du beispielsweise weißt, dass dein Styling dazu führt, dass ein Bild auf mobilen Geräten die volle Breite einnimmt, in einem 2-Spalten-Layout auf Tablets und einem 3-Spalten-Layout auf Desktop-Displays, solltest du eine sizes-Eigenschaft wie die folgende einschließen:
Dieses Beispiel von sizes
könnte einen dramatischen Effekt auf die Leistungsmetriken haben. Ohne das 33vw
sizes wäre das vom Server ausgewählte Bild 3-mal so breit wie nötig. Da die Dateigröße proportional zum Quadrat der Breite ist, würde der Benutzer ohne sizes
ein 9-mal größeres Bild herunterladen als nötig.
Mehr über srcset
und sizes
erfahren:
quality
Die Qualität des optimierten Bildes, eine Ganzzahl zwischen 1
und 100
, wobei 100
die beste Qualität und damit die größte Dateigröße ist. Standardwert ist 75
.
priority
Wenn true, wird das Bild als hohe Priorität eingestuft und vorgeladen. Lazy Loading wird automatisch für Bilder deaktiviert, die priority
verwenden. Wenn die loading
-Eigenschaft ebenfalls verwendet wird und auf lazy
gesetzt ist, kann die priority
-Eigenschaft nicht verwendet werden. Die loading
-Eigenschaft ist nur für fortgeschrittene Anwendungsfälle gedacht. Entferne loading
, wenn priority
benötigt wird.
Du solltest die priority
-Eigenschaft für jedes Bild verwenden, das als Largest Contentful Paint (LCP)-Element erkannt wurde. Es kann angemessen sein, mehrere Prioritätsbilder zu haben, da verschiedene Bilder für verschiedene Viewport-Größen das LCP-Element sein können.
Sollte nur verwendet werden, wenn das Bild über der Falz sichtbar ist. Standard ist false
.
placeholder
Ein Platzhalter, der während des Ladens des Bildes verwendet wird. Mögliche Werte sind blur
, empty
oder data:image/...
. Standard ist empty
.
Bei blur
wird die blurDataURL
-Eigenschaft als Platzhalter verwendet. Wenn src
ein Objekt aus einem statischen Import ist und das importierte Bild .jpg
, .png
, .webp
oder .avif
ist, wird blurDataURL
automatisch ausgefüllt, außer wenn das Bild als animiert erkannt wird.
Für dynamische Bilder musst du die blurDataURL
-Eigenschaft bereitstellen. Lösungen wie Plaiceholder können bei der base64
-Generierung helfen.
Bei data:image/...
wird die Data URL als Platzhalter verwendet, während das Bild lädt.
Bei empty
gibt es keinen Platzhalter während des Ladens des Bildes, nur leeren Raum.
Probiere es aus:
- Demo des
blur
-Platzhalters - Demo des Shimmer-Effekts mit der Data URL
placeholder
-Prop - Demo des Farbeffekts mit der
blurDataURL
-Prop
Erweiterte Props
In einigen Fällen benötigst du möglicherweise eine fortgeschrittenere Nutzung. Die <Image />
-Komponente akzeptiert optional die folgenden erweiterten Eigenschaften.
style
Ermöglicht das Übergeben von CSS-Styles an das zugrunde liegende Bildelement.
Denk daran, dass die erforderlichen width- und height-Props mit deinem Styling interagieren können. Wenn du Styling verwendest, um die Breite eines Bildes zu modifizieren, solltest du auch seine Höhe auf auto
setzen, um das intrinsische Seitenverhältnis zu bewahren, sonst wird dein Bild verzerrt.
onLoadingComplete
Achtung: Seit Next.js 14 zugunsten von
onLoad
veraltet.
Eine Callback-Funktion, die aufgerufen wird, sobald das Bild vollständig geladen ist und der Platzhalter entfernt wurde.
Die Callback-Funktion wird mit einem Argument aufgerufen, einer Referenz auf das zugrunde liegende <img>
-Element.
Hinweis: Die Verwendung von Props wie
onLoadingComplete
, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.
onLoad
Eine Callback-Funktion, die aufgerufen wird, sobald das Bild vollständig geladen ist und der Platzhalter entfernt wurde.
Die Callback-Funktion wird mit einem Argument aufgerufen, dem Event, das ein target
hat, das auf das zugrunde liegende <img>
-Element verweist.
Hinweis: Die Verwendung von Props wie
onLoad
, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.
onError
Eine Callback-Funktion, die aufgerufen wird, wenn das Bild nicht geladen werden kann.
Hinweis: Die Verwendung von Props wie
onError
, die eine Funktion akzeptieren, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.
loading
Das Ladeverhalten des Bildes. Standard ist lazy
.
Bei lazy
wird das Laden des Bildes verzögert, bis es einen berechneten Abstand zum Viewport erreicht.
Bei eager
wird das Bild sofort geladen.
Mehr über das loading
-Attribut erfahren.
blurDataURL
Eine Data URL, die als Platzhalterbild verwendet wird, bevor das src
-Bild erfolgreich geladen wird. Wird nur in Kombination mit placeholder="blur"
wirksam.
Muss ein base64-codiertes Bild sein. Es wird vergrößert und unscharf gemacht, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen. Das Einbinden größerer Bilder als Platzhalter kann die Leistung deiner Anwendung beeinträchtigen.
Probiere es aus:
Du kannst auch eine Data URL für eine einfarbige Fläche generieren, die zum Bild passt.
unoptimized
Wenn true, wird das Quellbild unverändert ausgeliefert, ohne Qualität, Größe oder Format zu ändern. Standard ist false
.
Seit Next.js 12.3.0 kann diese Prop allen Bildern zugewiesen werden, indem next.config.js
mit der folgenden Konfiguration aktualisiert wird:
overrideSrc
Beim Bereitstellen der src
-Prop für die <Image>
-Komponente werden sowohl die srcset
- als auch die src
-Attribute automatisch für das resultierende <img>
generiert.
In manchen Fällen ist es nicht erwünscht, dass das src
-Attribut generiert wird, und du möchtest es möglicherweise mit der overrideSrc
-Prop überschreiben.
Zum Beispiel möchtest du beim Upgrade einer bestehenden Website von <img>
auf <Image>
möglicherweise das gleiche src
-Attribut für SEO-Zwecke beibehalten, wie zum Beispiel für das Bild-Ranking oder um ein erneutes Crawling zu vermeiden.
decoding
Ein Hinweis für den Browser, ob er auf die Dekodierung des Bildes warten soll, bevor andere Inhaltsänderungen präsentiert werden oder nicht. Standard ist async
.
Mögliche Werte sind:
async
- Dekodiere das Bild asynchron und erlaube das Rendern anderer Inhalte, bevor es abgeschlossen ist.sync
- Dekodiere das Bild synchron für eine atomare Präsentation mit anderen Inhalten.auto
- Keine Präferenz für den Dekodiermodus; der Browser entscheidet, was am besten ist.
Mehr über das decoding
-Attribut erfahren.
Andere Props
Andere Eigenschaften der <Image />
-Komponente werden an das zugrunde liegende img
-Element weitergegeben, mit Ausnahme der folgenden:
srcSet
. Verwende stattdessen Device Sizes.
Konfigurationsoptionen
Zusätzlich zu Props kannst du die Image-Komponente in next.config.js
konfigurieren. Die folgenden Optionen sind verfügbar:
localPatterns
Du kannst optional localPatterns
in deiner next.config.js
-Datei konfigurieren, um bestimmte Pfade für die Optimierung zuzulassen und alle anderen Pfade zu blockieren.
Hinweis: Das obige Beispiel stellt sicher, dass die
src
-Eigenschaft vonnext/image
mit/assets/images/
beginnen muss und keine Query-String haben darf. Der Versuch, einen anderen Pfad zu optimieren, wird mit 400 Bad Request beantwortet.
remotePatterns
Um deine Anwendung vor böswilligen Benutzern zu schützen, ist eine Konfiguration erforderlich, um externe Bilder zu verwenden. Dies stellt sicher, dass nur externe Bilder von deinem Konto über die Next.js Image Optimization API bereitgestellt werden können. Diese externen Bilder können mit der remotePatterns
-Eigenschaft in deiner next.config.js
-Datei konfiguriert werden, wie unten gezeigt:
Hinweis: Das obige Beispiel stellt sicher, dass die
src
-Eigenschaft vonnext/image
mithttps://example.com/account123/
beginnen muss und keinen Query-String haben darf. Jedes andere Protokoll, jeder andere Hostname, Port oder nicht übereinstimmender Pfad wird mit 400 Bad Request beantwortet.
Hier ist ein Beispiel für die remotePatterns
-Eigenschaft in der next.config.js
-Datei mit einem Platzhalter-Muster im hostname
:
Hinweis: Das obige Beispiel stellt sicher, dass die
src
-Eigenschaft vonnext/image
mithttps://img1.example.com
oderhttps://me.avatar.example.com
oder einer beliebigen Anzahl von Subdomains beginnen muss. Es darf keinen Port oder Query-String haben. Jedes andere Protokoll oder nicht übereinstimmender Hostname wird mit 400 Bad Request beantwortet.
Platzhalter-Muster können sowohl für pathname
als auch für hostname
verwendet werden und haben die folgende Syntax:
*
entspricht einem einzelnen Pfadsegment oder einer Subdomain**
entspricht einer beliebigen Anzahl von Pfadsegmenten am Ende oder Subdomains am Anfang
Die **
-Syntax funktioniert nicht in der Mitte des Musters.
Hinweis: Wenn
protocol
,port
,pathname
odersearch
weggelassen werden, wird der Platzhalter**
impliziert. Dies wird nicht empfohlen, da es böswilligen Akteuren ermöglichen könnte, URLs zu optimieren, die du nicht beabsichtigt hast.
Hier ist ein Beispiel für die remotePatterns
-Eigenschaft in der next.config.js
-Datei mit search
:
Hinweis: Das obige Beispiel stellt sicher, dass die
src
-Eigenschaft vonnext/image
mithttps://assets.example.com
beginnen und den exakten Query-String?v=1727111025337
haben muss. Jedes andere Protokoll oder Query-String wird mit 400 Bad Request beantwortet.
domains
Achtung: Seit Next.js 14 zugunsten von strikten
remotePatterns
veraltet, um deine Anwendung vor böswilligen Benutzern zu schützen. Verwendedomains
nur, wenn du der Eigentümer aller Inhalte bist, die von der Domain bereitgestellt werden.
Ähnlich wie remotePatterns
kann die domains
-Konfiguration verwendet werden, um eine Liste erlaubter Hostnamen für externe Bilder bereitzustellen.
Allerdings unterstützt die domains
-Konfiguration keine Platzhalter-Muster und kann Protokoll, Port oder Pfadname nicht einschränken.
Hier ist ein Beispiel für die domains
-Eigenschaft in der next.config.js
-Datei:
loaderFile
Wenn du einen Cloud-Provider zur Optimierung von Bildern anstelle der eingebauten Next.js Image Optimization API verwenden möchtest, kannst du den loaderFile
in deiner next.config.js
wie folgt konfigurieren:
Dies muss auf eine Datei relativ zum Root deiner Next.js-Anwendung zeigen. Die Datei muss eine Standard-Funktion exportieren, die eine Zeichenkette zurückgibt, zum Beispiel:
Alternativ kannst du die loader
-Prop verwenden, um jede Instanz von next/image
zu konfigurieren.
Beispiele:
Hinweis: Die Anpassung der Image-Loader-Datei, die eine Funktion akzeptiert, erfordert die Verwendung von Client Components, um die bereitgestellte Funktion zu serialisieren.
Fortgeschritten
Die folgende Konfiguration ist für fortgeschrittene Anwendungsfälle und normalerweise nicht erforderlich. Wenn du dich entscheidest, die folgenden Eigenschaften zu konfigurieren, überschreibst du alle Änderungen an den Next.js-Standardeinstellungen in zukünftigen Updates.
deviceSizes
Wenn du die erwarteten Gerätebreiten deiner Benutzer kennst, kannst du eine Liste von Gerätebreiten-Breakpoints mit der deviceSizes
-Eigenschaft in next.config.js
angeben. Diese Breiten werden verwendet, wenn die next/image
-Komponente die sizes
-Prop verwendet, um sicherzustellen, dass das richtige Bild für das Gerät des Benutzers bereitgestellt wird.
Wenn keine Konfiguration bereitgestellt wird, wird der folgende Standard verwendet:
imageSizes
Du kannst eine Liste von Bildbreiten mit der images.imageSizes
-Eigenschaft in deiner next.config.js
-Datei angeben. Diese Breiten werden mit dem Array von Gerätebreiten zusammengefügt, um das vollständige Array von Größen zu bilden, das verwendet wird, um Bild-srcsets zu generieren.
Der Grund dafür, dass es zwei separate Listen gibt, ist, dass imageSizes nur für Bilder verwendet wird, die eine sizes
-Prop bereitstellen, was darauf hinweist, dass das Bild kleiner als die volle Bildschirmbreite ist. Daher sollten alle Größen in imageSizes kleiner sein als die kleinste Größe in deviceSizes.
Wenn keine Konfiguration bereitgestellt wird, wird der folgende Standard verwendet:
formats
Die Standard-Image Optimization API erkennt automatisch die vom Browser unterstützten Bildformate über den Accept
-Header der Anfrage, um das beste Ausgabeformat zu bestimmen.
Wenn der Accept
-Header mit mehr als einem der konfigurierten Formate übereinstimmt, wird die erste Übereinstimmung im Array verwendet. Daher ist die Reihenfolge im Array wichtig. Wenn es keine Übereinstimmung gibt (oder das Quellbild animiert ist), wird die Image Optimization API auf das ursprüngliche Bildformat zurückfallen.
Wenn keine Konfiguration bereitgestellt wird, wird der folgende Standard verwendet:
Du kannst AVIF-Unterstützung aktivieren und trotzdem auf WebP zurückfallen mit der folgenden Konfiguration:
Hinweis:
- AVIF braucht im Allgemeinen 50% länger zum Kodieren, komprimiert aber 20% kleiner als WebP. Das bedeutet, dass die erste Anfrage nach einem Bild typischerweise langsamer sein wird und dann nachfolgende zwischengespeicherte Anfragen schneller sein werden.
- Wenn du selbst hostest mit einem Proxy/CDN vor Next.js, musst du den Proxy konfigurieren, um den
Accept
-Header weiterzuleiten.
Caching-Verhalten
Das Folgende beschreibt den Caching-Algorithmus für den Standard-Loader. Für alle anderen Loader siehe bitte die Dokumentation deines Cloud-Providers.
Bilder werden bei Anfrage dynamisch optimiert und im Verzeichnis <distDir>/cache/images
gespeichert. Die optimierte Bilddatei wird für nachfolgende Anfragen bereitgestellt, bis die Ablaufzeit erreicht ist. Wenn eine Anfrage eingeht, die einer zwischengespeicherten, aber abgelaufenen Datei entspricht, wird das abgelaufene Bild sofort veraltet bereitgestellt. Dann wird das Bild im Hintergrund erneut optimiert (auch Revalidierung genannt) und mit dem neuen Ablaufdatum im Cache gespeichert.
Der Cache-Status eines Bildes kann durch Auslesen des Wertes des x-nextjs-cache
Response-Headers ermittelt werden. Die möglichen Werte sind:
MISS
- der Pfad ist nicht im Cache (tritt höchstens einmal auf, beim ersten Besuch)STALE
- der Pfad ist im Cache, hat aber die Revalidierungszeit überschritten, sodass er im Hintergrund aktualisiert wirdHIT
- der Pfad ist im Cache und hat die Revalidierungszeit nicht überschritten
Die Ablaufzeit (oder besser gesagt die maximale Alter) wird entweder durch die minimumCacheTTL
-Konfiguration oder den Cache-Control
-Header des Quellbildes definiert, je nachdem, welcher Wert größer ist. Speziell wird der max-age
-Wert des Cache-Control
-Headers verwendet. Wenn sowohl s-maxage
als auch max-age
gefunden werden, wird s-maxage
bevorzugt. Der max-age
wird auch an alle nachgelagerten Clients einschließlich CDNs und Browser weitergegeben.
- Du kannst
minimumCacheTTL
konfigurieren, um die Cache-Dauer zu erhöhen, wenn das Quellbild keinenCache-Control
-Header enthält oder der Wert sehr niedrig ist. - Du kannst
deviceSizes
undimageSizes
konfigurieren, um die Gesamtzahl möglicher generierter Bilder zu reduzieren. - Du kannst formats konfigurieren, um mehrere Formate zugunsten eines einzelnen Bildformats zu deaktivieren.
minimumCacheTTL
Du kannst die Time to Live (TTL) in Sekunden für zwischengespeicherte optimierte Bilder konfigurieren. In vielen Fällen ist es besser, einen Statischen Bild-Import zu verwenden, der automatisch den Dateiinhalt hasht und das Bild mit einem Cache-Control
-Header von immutable
auf ewig zwischenspeichert.
Die Ablaufzeit (oder besser gesagt das maximale Alter) des optimierten Bildes wird entweder durch die minimumCacheTTL
oder den Cache-Control
-Header des Quellbildes definiert, je nachdem, welcher Wert größer ist.
Wenn du das Caching-Verhalten pro Bild ändern musst, kannst du headers
konfigurieren, um den Cache-Control
-Header für das Quellbild zu setzen (z.B. /some-asset.jpg
, nicht /_next/image
selbst).
Zurzeit gibt es keinen Mechanismus, um den Cache zu invalidieren, daher ist es am besten, minimumCacheTTL
niedrig zu halten. Andernfalls musst du möglicherweise manuell die src
-Prop ändern oder <distDir>/cache/images
löschen.
disableStaticImages
Das Standardverhalten erlaubt es dir, statische Dateien wie import icon from './icon.png'
zu importieren und dann an die src
-Eigenschaft zu übergeben.
In einigen Fällen möchtest du diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins in Konflikt steht, die erwarten, dass der Import sich anders verhält.
Du kannst statische Bildimporte in deiner next.config.js
deaktivieren:
dangerouslyAllowSVG
Der Standard-Loader optimiert SVG-Bilder aus mehreren Gründen nicht. Erstens ist SVG ein Vektorformat, was bedeutet, dass es verlustfrei skaliert werden kann. Zweitens hat SVG viele der gleichen Funktionen wie HTML/CSS, was ohne angemessene Content Security Policy (CSP) Header zu Sicherheitslücken führen kann.
Daher empfehlen wir die Verwendung der unoptimized
-Prop, wenn die src
-Prop bekanntermaßen SVG ist. Dies geschieht automatisch, wenn src
mit ".svg"
endet.
Wenn du jedoch SVG-Bilder mit der Standard Image Optimization API bereitstellen musst, kannst du dangerouslyAllowSVG
in deiner next.config.js
setzen:
Zusätzlich wird dringend empfohlen, auch contentDispositionType
zu setzen, um den Browser zum Herunterladen des Bildes zu zwingen, sowie contentSecurityPolicy
, um die Ausführung von im Bild eingebetteten Skripten zu verhindern.
contentDispositionType
Der Standard-Loader setzt den Content-Disposition
-Header auf attachment
für zusätzlichen Schutz, da die API beliebige externe Bilder bereitstellen kann.
Der Standardwert ist attachment
, was den Browser zwingt, das Bild beim direkten Besuch herunterzuladen. Dies ist besonders wichtig, wenn dangerouslyAllowSVG
true ist.
Optional kannst du inline
konfigurieren, um dem Browser zu erlauben, das Bild beim direkten Besuch zu rendern, ohne es herunterzuladen.
Animierte Bilder
Der Standard-Loader umgeht automatisch die Bildoptimierung für animierte Bilder und stellt das Bild unverändert bereit.
Die automatische Erkennung für animierte Dateien erfolgt nach bestem Bemühen und unterstützt GIF, APNG und WebP. Wenn du die Bildoptimierung für ein bestimmtes animiertes Bild explizit umgehen möchtest, verwende die unoptimized-Prop.
Responsive Bilder
Das standardmäßig generierte srcset
enthält 1x
und 2x
Bilder, um verschiedene Gerätepixelverhältnisse zu unterstützen. Möglicherweise möchtest du jedoch ein responsives Bild rendern, das sich mit dem Viewport dehnt. In diesem Fall musst du sowohl sizes
als auch style
(oder className
) setzen.
Du kannst ein responsives Bild mit einer der folgenden Methoden rendern.
Responsives Bild mit statischem Import
Wenn das Quellbild nicht dynamisch ist, kannst du es statisch importieren, um ein responsives Bild zu erstellen:
Probiere es aus:
Responsives Bild mit Seitenverhältnis
Wenn das Quellbild eine dynamische oder remote URL ist, musst du auch width
und height
angeben, um das korrekte Seitenverhältnis des responsiven Bildes festzulegen:
Responsives Bild mit fill
Wenn du das Seitenverhältnis nicht kennst, musst du die fill
-Prop setzen und position: relative
auf dem übergeordneten Element festlegen. Optional kannst du den object-fit
-Style je nach gewünschtem Streck- oder Schneide-Verhalten setzen:
Probiere es aus:
Theme Detection CSS
Wenn du ein anderes Bild für den hellen und dunklen Modus anzeigen möchtest, kannst du eine neue Komponente erstellen, die zwei <Image>
-Komponenten umschließt und die richtige basierend auf einer CSS-Medienabfrage anzeigt.
Hinweis: Das Standardverhalten von
loading="lazy"
stellt sicher, dass nur das richtige Bild geladen wird. Du kannst nichtpriority
oderloading="eager"
verwenden, da dies dazu führen würde, dass beide Bilder geladen werden. Stattdessen kannst dufetchPriority="high"
verwenden.
Probiere es aus:
getImageProps
Für fortgeschrittenere Anwendungsfälle kannst du getImageProps()
aufrufen, um die Props zu erhalten, die an das zugrunde liegende <img>
-Element übergeben würden, und sie stattdessen an eine andere Komponente, ein Style, ein Canvas etc. übergeben.
Dies vermeidet auch den Aufruf von React useState()
, was zu besserer Leistung führen kann, aber es kann nicht mit der placeholder
-Prop verwendet werden, da der Platzhalter nie entfernt wird.
Theme Detection Picture
Wenn du ein anderes Bild für den hellen und dunklen Modus anzeigen möchtest, kannst du das <picture>
-Element verwenden, um ein anderes Bild basierend auf dem bevorzugten Farbschema des Benutzers anzuzeigen.
Art Direction
Wenn du ein anderes Bild für mobile und Desktop-Geräte anzeigen möchtest, manchmal auch Art Direction genannt, kannst du verschiedene src
, width
, height
und quality
Props an getImageProps()
übergeben.
Background CSS
Du kannst sogar den srcSet
-String in die image-set()
CSS-Funktion umwandeln, um ein Hintergrundbild zu optimieren.
Bekannte Browser-Bugs
Diese next/image
-Komponente verwendet natives lazy loading des Browsers, das für ältere Browser vor Safari 15.4 auf eager loading zurückfallen kann. Bei Verwendung des Blur-up-Platzhalters fallen ältere Browser vor Safari 12 auf einen leeren Platzhalter zurück. Bei Verwendung von Styles mit width
/height
von auto
ist es möglich, Layout-Verschiebungen auf älteren Browsern vor Safari 15 zu verursachen, die das Seitenverhältnis nicht bewahren. Weitere Details findest du in diesem MDN-Video.
- Safari 15 - 16.3 zeigt während des Ladens einen grauen Rand an. Safari 16.4 hat dieses Problem behoben. Mögliche Lösungen:
- Verwende CSS
@supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
- Verwende
priority
, wenn das Bild above the fold ist
- Verwende CSS
- Firefox 67+ zeigt während des Ladens einen weißen Hintergrund an. Mögliche Lösungen:
- Aktiviere AVIF
formats
- Verwende
placeholder
- Aktiviere AVIF
Versionshistorie
Version | Änderungen |
---|---|
v15.0.0 | decoding -Prop hinzugefügt. contentDispositionType -Konfiguration Standard auf attachment geändert. |
v14.2.0 | overrideSrc -Prop hinzugefügt. |
v14.1.0 | getImageProps() ist stabil. |
v14.0.0 | onLoadingComplete -Prop und domains -Config veraltet. |
v13.4.14 | placeholder -Prop-Unterstützung für data:/image... |
v13.2.0 | contentDispositionType -Konfiguration hinzugefügt. |
v13.0.6 | ref -Prop hinzugefügt. |
v13.0.0 | Der next/image -Import wurde zu next/legacy/image umbenannt. Der next/future/image -Import wurde zu next/image umbenannt. Ein Codemod ist verfügbar, um deine Importe sicher und automatisch umzubenennen. <span> -Wrapper entfernt. layout , objectFit , objectPosition , lazyBoundary , lazyRoot -Props entfernt. alt ist erforderlich. onLoadingComplete erhält Referenz zum img -Element. Eingebaute Loader-Konfiguration entfernt. |
v12.3.0 | remotePatterns und unoptimized -Konfiguration ist stabil. |
v12.2.0 | Experimentelles remotePatterns und experimentelle unoptimized -Konfiguration hinzugefügt. layout="raw" entfernt. |
v12.1.1 | style -Prop hinzugefügt. Experimentelle Unterstützung für layout="raw" hinzugefügt. |
v12.1.0 | dangerouslyAllowSVG und contentSecurityPolicy -Konfiguration hinzugefügt. |
v12.0.9 | lazyRoot -Prop hinzugefügt. |
v12.0.0 | formats -Konfiguration hinzugefügt.AVIF-Unterstützung hinzugefügt. Wrapper <div> zu <span> geändert. |
v11.1.0 | onLoadingComplete und lazyBoundary -Props hinzugefügt. |
v11.0.0 | src -Prop-Unterstützung für statischen Import.placeholder -Prop hinzugefügt.blurDataURL -Prop hinzugefügt. |
v10.0.5 | loader -Prop hinzugefügt. |
v10.0.1 | layout -Prop hinzugefügt. |
v10.0.0 | next/image eingeführt. |