<Image>

Wissenswert: Wenn Sie eine Version von Next.js vor 13 verwenden, sollten Sie die Dokumentation für next/legacy/image verwenden, da die Komponente umbenannt wurde.

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die verfügbaren Props und Konfigurationsoptionen für die Image-Komponente verwenden. Für Funktionen und Verwendung siehe die Seite Image-Komponente.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Bild des Autors"
    />
  )
}

Props

Hier ist eine Übersicht der verfügbaren Props für die Image-Komponente:

Erforderliche Props

Die Image-Komponente erfordert die folgenden Eigenschaften: src, width, height und alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Bild des Autors"
      />
    </div>
  )
}

src

Muss einer der folgenden sein:

• Eine statisch importierte Bilddatei
• Ein Pfadstring. Dies kann entweder eine absolute externe URL oder ein interner Pfad sein, abhängig von der loader-Prop.

Bei Verwendung einer externen URL müssen Sie diese zu remotePatterns in next.config.js hinzufügen.

width

Die width-Prop repräsentiert die gerenderte Breite in Pixeln und beeinflusst somit, wie groß das Bild erscheint.

Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill-Eigenschaft.

height

Die height-Prop repräsentiert die gerenderte Höhe in Pixeln und beeinflusst somit, wie groß das Bild erscheint.

Erforderlich, außer für statisch importierte Bilder oder Bilder mit der fill-Eigenschaft.

alt

Die alt-Prop wird verwendet, um das Bild für Screenreader und Suchmaschinen zu beschreiben. Sie ist auch der Fallback-Text, wenn Bilder deaktiviert sind oder ein Fehler beim Laden auftritt.

Sie sollte Text enthalten, der das Bild ohne Änderung der Seitenbedeutung ersetzen könnte. Sie ist nicht dazu gedacht, das Bild zu ergänzen, und sollte keine Informationen wiederholen, die bereits in den Bildunterschriften enthalten sind.

Wenn das Bild rein dekorativ oder nicht für den Benutzer bestimmt ist, sollte die alt-Prop ein leerer String sein (alt="").

Mehr erfahren

Optionale Props

Die <Image />-Komponente akzeptiert eine Reihe zusätzlicher Eigenschaften über die erforderlichen hinaus. Dieser Abschnitt beschreibt die am häufigsten verwendeten Props der Image-Komponente. Details zu seltener verwendeten Props finden Sie im Abschnitt Erweiterte Props.

loader

Eine benutzerdefinierte Funktion zur Auflösung von Bild-URLs.

Ein loader ist eine Funktion, die einen URL-String für das Bild zurückgibt, basierend auf folgenden Parametern:

• src
• width
• quality

Hier ist ein Beispiel für die Verwendung eines benutzerdefinierten Loaders:

import Image from 'next/image'

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Bild des Autors"
      width={500}
      height={500}
    />
  )
}

Alternativ können Sie die loaderFile-Konfiguration in next.config.js verwenden, um jede Instanz von next/image in Ihrer Anwendung zu konfigurieren, ohne eine Prop zu übergeben.

fill

fill={true} // {true} | {false}

Ein Boolean, der bewirkt, dass das Bild das Elternelement ausfüllt, was nützlich ist, wenn die width und height unbekannt sind.

Das Elternelement muss den Style position: "relative", position: "fixed" oder position: "absolute" zugewiesen haben.

Standardmäßig erhält das img-Element automatisch den Style position: "absolute".

Wenn keine Styles auf das Bild angewendet werden, wird das Bild gestreckt, um den Container zu füllen. Möglicherweise bevorzugen Sie object-fit: "contain" für ein Bild, das an den Container angepasst wird und das Seitenverhältnis beibehält.

Alternativ bewirkt object-fit: "cover", dass das Bild den gesamten Container ausfüllt und zugeschnitten wird, um das Seitenverhältnis beizubehalten. Damit dies korrekt aussieht, sollte der Style overflow: "hidden" dem Elternelement zugewiesen werden.

Weitere Informationen siehe auch:

• position
• object-fit
• object-position

sizes

Ein String, ähnlich einer Media Query, der Informationen darüber liefert, wie breit das Bild bei verschiedenen Breakpoints sein wird. Der Wert von sizes beeinflusst die Leistung stark für Bilder, die fill verwenden oder responsiv gestaltet sind.

Die sizes-Prop dient zwei wichtigen Zwecken in Bezug auf die Bildleistung:

• Erstens verwendet der Browser den Wert von sizes, um zu bestimmen, welche Größe des Bildes aus dem automatisch generierten srcset von next/image heruntergeladen werden soll. Wenn der Browser wählt, kennt er die Größe des Bildes auf der Seite noch nicht und wählt daher ein Bild aus, das genauso groß oder größer als der Viewport ist. Die sizes-Prop ermöglicht es Ihnen, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als die volle Bildschirmbreite sein wird. Wenn Sie keinen sizes-Wert für ein Bild mit der fill-Prop angeben, wird der Standardwert 100vw (volle Bildschirmbreite) verwendet.
• Zweitens ändert die sizes-Prop das Verhalten des automatisch generierten srcset-Werts. Wenn kein sizes-Wert vorhanden ist, wird ein kleiner srcset generiert, der für ein Bild mit fester Größe geeignet ist (1x/2x/etc). Wenn sizes definiert ist, wird ein großer srcset generiert, der für ein responsives Bild geeignet ist (640w/750w/etc). Wenn die sizes-Prop Größen wie 50vw enthält, die einen Prozentsatz der Viewport-Breite darstellen, wird der srcset beschnitten, um keine Werte einzubeziehen, die zu klein sind, um jemals benötigt zu werden.

Wenn Sie beispielsweise wissen, dass Ihr Styling bewirkt, dass ein Bild auf Mobilgeräten die volle Breite einnimmt, auf Tablets in einem 2-Spalten-Layout und auf Desktop-Bildschirmen in einem 3-Spalten-Layout, sollten Sie eine sizes-Prop wie folgt einbeziehen:

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

Dieses sizes-Beispiel könnte eine dramatische Auswirkung auf Leistungsmetriken haben. Ohne die 33vw-Größe wäre das vom Server ausgewählte Bild dreimal so breit wie nötig. Da die Dateigröße proportional zum Quadrat der Breite ist, würde der Benutzer ohne sizes ein Bild herunterladen, das neunmal größer ist als notwendig.

Mehr über srcset und sizes:

• web.dev
• mdn

quality

quality={75} // {number 1-100}

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 darstellt. Standardwert ist 75.

Wenn die qualities-Konfiguration in next.config.js definiert ist, muss die quality-Prop einem der in der Konfiguration definierten Werte entsprechen.

Wissenswert: Wenn das ursprüngliche Quellbild bereits von geringer Qualität war, könnte eine zu hohe quality-Prop dazu führen, dass das resultierende optimierte Bild größer ist als das ursprüngliche Quellbild.

priority

priority={false} // {false} | {true}

Wenn true, wird das Bild als hohe Priorität betrachtet und preload. Lazy Loading wird automatisch für Bilder mit priority deaktiviert.

Sie sollten die priority-Prop für jedes Bild verwenden, das als Largest Contentful Paint (LCP)-Element erkannt wird. Es kann angemessen sein, mehrere Priority-Bilder zu haben, da verschiedene Bilder für verschiedene Viewport-Größen das LCP-Element sein können.

Sollte nur verwendet werden, wenn das Bild oberhalb des Folds sichtbar ist. Standardwert ist false.

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

Ein Platzhalter, der während des Ladens des Bildes verwendet wird. Mögliche Werte sind blur, empty oder data:image/.... Standardwert ist empty.

Bei blur wird die blurDataURL-Prop 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, es sei denn, das Bild wird als animiert erkannt.

Für dynamische Bilder müssen Sie die blurDataURL-Prop bereitstellen. Lösungen wie Plaiceholder können bei der base64-Generierung helfen.

Bei data:image/... wird die Data URL als Platzhalter während des Ladens des Bildes verwendet.

Bei empty gibt es während des Ladens des Bildes keinen Platzhalter, nur leeren Raum.

Ausprobieren:

• Demo des blur-Platzhalters
• Demo des Schimmer-Effekts mit data URL placeholder-Prop
• Demo des Farbeffekts mit blurDataURL-Prop

Erweiterte Props

In einigen Fällen benötigen Sie möglicherweise eine erweiterte Nutzung. Die <Image />-Komponente akzeptiert optional die folgenden erweiterten Eigenschaften.

style

Ermöglicht die Übergabe von CSS-Styles an das zugrunde liegende Bild-Element.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

Denken Sie daran, dass die erforderlichen width- und height-Props mit Ihrem Styling interagieren können. Wenn Sie Styling verwenden, um die Breite eines Bildes zu ändern, sollten Sie auch seine Höhe auf auto setzen, um das intrinsische Seitenverhältnis beizubehalten, da das Bild sonst verzerrt wird.

onLoadingComplete

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

Warnung: Seit Next.js 14 veraltet zugunsten von 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, einer Referenz auf das zugrunde liegende <img>-Element.

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

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 enthält, das auf das zugrunde liegende <img>-Element verweist.

onError

<Image onError={(e) => console.error(e.target.id)} />

Eine Callback-Funktion, die aufgerufen wird, wenn das Bild nicht geladen werden kann.

loading

Empfehlung: Diese Eigenschaft ist nur für fortgeschrittene Anwendungsfälle gedacht. Das Umschalten eines Bildes auf eager wird normalerweise die Leistung beeinträchtigen. Wir empfehlen stattdessen die Verwendung der Eigenschaft priority, die das Bild vorab eifrig lädt.

loading = 'lazy' // {lazy} | {eager}

Das Ladeverhalten des Bildes. Standardmäßig 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. Wirkt nur in Kombination mit placeholder="blur".

Muss ein base64-kodiertes Bild sein. Es wird vergrößert und unscharf gemacht, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen. Größere Bilder als Platzhalter können die Leistung Ihrer Anwendung beeinträchtigen.

Ausprobieren:

• Demo der Standard-blurDataURL-Eigenschaft
• Demo des Farbeffekts mit blurDataURL-Eigenschaft

Sie können auch eine einfarbige Data URL generieren, die zum Bild passt.

unoptimized

unoptimized = {false} // {false} | {true}

Wenn true, wird das Quellbild unverändert ausgeliefert, ohne Qualität, Größe oder Format zu ändern. Standardmäßig false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Seit Next.js 12.3.0 kann diese Eigenschaft für alle Bilder festgelegt werden, indem next.config.js mit folgender Konfiguration aktualisiert wird:

module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

Wenn Sie die src-Eigenschaft der <Image>-Komponente angeben, werden sowohl das srcset- als auch das src-Attribut automatisch für das resultierende <img>-Element generiert.

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

In einigen Fällen ist es nicht erwünscht, dass das src-Attribut generiert wird, und Sie möchten es möglicherweise mit der overrideSrc-Eigenschaft überschreiben.

Zum Beispiel, wenn Sie eine bestehende Website von <img> auf <Image> umstellen, möchten Sie möglicherweise das gleiche src-Attribut aus SEO-Gründen wie Bildranking oder Vermeidung von Neu-Crawling beibehalten.

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

Ein Hinweis an den Browser, ob er warten soll, bis das Bild decodiert ist, bevor andere Inhaltsaktualisierungen angezeigt werden. Standardmäßig async.

Mögliche Werte sind:

• async - Decodiert das Bild asynchron und erlaubt die Anzeige anderer Inhalte, bevor der Vorgang abgeschlossen ist.
• sync - Decodiert das Bild synchron für eine atomare Darstellung mit anderen Inhalten.
• auto - Keine Präferenz für den Decodierungsmodus; der Browser entscheidet, was am besten ist.

Mehr über das decoding-Attribut erfahren.

Andere Eigenschaften

Andere Eigenschaften der <Image />-Komponente werden an das zugrunde liegende img-Element weitergegeben, mit Ausnahme der folgenden:

• srcSet. Verwenden Sie stattdessen Gerätegrößen.

Konfigurationsoptionen

Zusätzlich zu den Eigenschaften können Sie die Image-Komponente in next.config.js konfigurieren. Folgende Optionen sind verfügbar:

localPatterns

Sie können optional localPatterns in Ihrer next.config.js-Datei konfigurieren, um bestimmte Pfade für die Optimierung zuzulassen und alle anderen Pfade zu blockieren.

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit /assets/images/ beginnen muss und keine Abfragezeichenfolge enthalten darf. Der Versuch, einen anderen Pfad zu optimieren, führt zu einer 400 Bad Request-Antwort.

remotePatterns

Um Ihre Anwendung vor böswilligen Nutzern zu schützen, ist eine Konfiguration erforderlich, um externe Bilder zu verwenden. Dadurch wird sichergestellt, dass nur externe Bilder von Ihrem Konto über die Next.js Image Optimization API bereitgestellt werden können. Diese externen Bilder können mit der Eigenschaft remotePatterns in Ihrer next.config.js-Datei konfiguriert werden, wie unten gezeigt:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://example.com/account123/ beginnen muss und keine Abfragezeichenfolge enthalten darf. Jedes andere Protokoll, Hostname, Port oder nicht übereinstimmender Pfad führt zu einer 400 Bad Request-Antwort.

Unten ist ein Beispiel für die remotePatterns-Eigenschaft in der next.config.js-Datei mit einem Wildcard-Muster im hostname:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://img1.example.com oder https://me.avatar.example.com oder einer beliebigen Anzahl von Subdomains beginnen muss. Es darf keinen Port oder Abfragezeichenfolge enthalten. Jedes andere Protokoll oder nicht übereinstimmender Hostname führt zu einer 400 Bad Request-Antwort.

Wildcard-Muster können sowohl für pathname als auch für hostname verwendet werden und haben folgende Syntax:

• * passt auf ein einzelnes Pfadsegment oder eine Subdomain
• ** passt auf eine beliebige Anzahl von Pfadsegmenten am Ende oder Subdomains am Anfang

Die **-Syntax funktioniert nicht in der Mitte des Musters.

Gut zu wissen: Wenn protocol, port, pathname oder search weggelassen werden, wird das Wildcard ** impliziert. Dies wird nicht empfohlen, da es böswilligen Akteuren ermöglichen könnte, URLs zu optimieren, die Sie nicht beabsichtigt haben.

Unten ist ein Beispiel für die remotePatterns-Eigenschaft in der next.config.js-Datei mit search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

Gut zu wissen: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/image mit https://assets.example.com beginnen muss und die exakte Abfragezeichenfolge ?v=1727111025337 enthalten muss. Jedes andere Protokoll oder Abfragezeichenfolge führt zu einer 400 Bad Request-Antwort.

domains

Warnung: Seit Next.js 14 veraltet zugunsten der strengeren remotePatterns, um Ihre Anwendung vor böswilligen Nutzern zu schützen. Verwenden Sie domains nur, wenn Sie alle Inhalte besitzen, die von der Domain bereitgestellt werden.

Ähnlich wie remotePatterns kann die domains-Konfiguration verwendet werden, um eine Liste zulässiger Hostnamen für externe Bilder bereitzustellen.

Allerdings unterstützt die domains-Konfiguration keine Wildcard-Muster und kann Protokoll, Port oder Pfad nicht einschränken.

Unten ist ein Beispiel für die domains-Eigenschaft in der next.config.js-Datei:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

loaderFile

Wenn Sie einen Cloud-Anbieter zur Bildoptimierung verwenden möchten, anstatt die integrierte Next.js Image Optimization API zu nutzen, können Sie loaderFile in Ihrer next.config.js wie folgt konfigurieren:

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

Dies muss auf eine Datei relativ zum Stammverzeichnis Ihrer Next.js-Anwendung verweisen. Die Datei muss eine Standardfunktion exportieren, die einen String zurückgibt, zum Beispiel:

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

Alternativ können Sie die loader-Eigenschaft verwenden, um jede Instanz von next/image zu konfigurieren.

Beispiele:

• Benutzerdefinierte Image Loader-Konfiguration

Fortgeschritten

Die folgende Konfiguration ist für fortgeschrittene Anwendungsfälle gedacht und ist normalerweise nicht notwendig. Wenn Sie die folgenden Eigenschaften konfigurieren, überschreiben Sie alle Änderungen an den Next.js-Standardeinstellungen in zukünftigen Updates.

deviceSizes

Wenn Sie die erwarteten Gerätebreiten Ihrer Nutzer kennen, können Sie eine Liste von Breakpoints für Gerätebreiten mit der Eigenschaft deviceSizes in next.config.js angeben. Diese Breiten werden verwendet, wenn die next/image-Komponente die sizes-Eigenschaft verwendet, um sicherzustellen, dass das richtige Bild für das Gerät des Nutzers bereitgestellt wird.

Wenn keine Konfiguration bereitgestellt wird, wird die folgende Standardeinstellung verwendet.

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

imageSizes

Sie können eine Liste von Bildbreiten mit der Eigenschaft images.imageSizes in Ihrer next.config.js-Datei angeben. Diese Breiten werden mit dem Array der Gerätegrößen verkettet, um das vollständige Array der Größen zu bilden, das zur Generierung von Bild-srcsets verwendet wird.

Der Grund für die beiden separaten Listen ist, dass imageSizes nur für Bilder verwendet wird, die eine sizes-Eigenschaft 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 die folgende Standardeinstellung verwendet.

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

qualities

Die standardmäßige Image Optimization API erlaubt automatisch alle Qualitäten von 1 bis 100. Wenn Sie die zulässigen Qualitäten einschränken möchten, können Sie next.config.js eine Konfiguration hinzufügen.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

In diesem Beispiel oben sind nur drei Qualitäten erlaubt: 25, 50 und 75. Wenn die quality-Eigenschaft nicht mit einem Wert in diesem Array übereinstimmt, schlägt das Bild mit 400 Bad Request fehl.

formats

Die standardmäßige Image Optimization API erkennt automatisch die vom Browser unterstützten Bildformate über den Accept-Header der Anfrage.

Wenn der Accept-Header mit mehr als einem der konfigurierten Formate übereinstimmt, wird das erste übereinstimmende Format im Array verwendet. Daher ist die Reihenfolge des Arrays wichtig. Wenn keine Übereinstimmung vorliegt (oder das Quellbild animiert ist), fällt die Image Optimization API auf das ursprüngliche Format des Bildes zurück.

Wenn keine Konfiguration bereitgestellt wird, wird die folgende Standardeinstellung verwendet.

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

Sie können die AVIF-Unterstützung mit der folgenden Konfiguration aktivieren.

module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

Gut zu wissen:

• AVIF benötigt im Allgemeinen 20% mehr Zeit für die Kodierung, komprimiert aber 20% kleiner im Vergleich zu WebP. Das bedeutet, dass die erste Anforderung eines Bildes normalerweise langsamer ist und nachfolgende Anfragen, die zwischengespeichert werden, schneller sind.
• Wenn Sie Next.js mit einem Proxy/CDN selbst hosten, müssen Sie den Proxy so konfigurieren, dass er den Accept-Header weiterleitet.

Caching-Verhalten

Das Folgende beschreibt den Caching-Algorithmus für den Standard-Loader. Für alle anderen Loader lesen Sie bitte die Dokumentation Ihres Cloud-Anbieters.

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 gestellt wird, die auf eine zwischengespeicherte, aber abgelaufene Datei passt, wird das abgelaufene Bild sofort als "stale" bereitgestellt. Dann wird das Bild im Hintergrund neu optimiert (auch Revalidierung genannt) und mit dem neuen Ablaufdatum im Cache gespeichert.

Der Cache-Status eines Bildes kann durch Lesen des Werts des x-nextjs-cache-Antwortheaders bestimmt werden. Die möglichen Werte sind:

• MISS - der Pfad ist nicht im Cache (tritt höchstens einmal beim ersten Besuch auf)
• STALE - der Pfad ist im Cache, hat aber die Revalidierungszeit überschritten und wird im Hintergrund aktualisiert
• HIT - der Pfad ist im Cache und hat die Revalidierungszeit nicht überschritten

Die Ablaufzeit (oder eher Max Age) wird entweder durch die minimumCacheTTL-Konfiguration oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher größer ist. Speziell wird der max-age-Wert des Cache-Control-Headers verwendet. Wenn sowohl s-maxage als auch max-age vorhanden sind, wird s-maxage bevorzugt. Der max-age wird auch an alle nachgelagerten Clients, einschließlich CDNs und Browser, weitergegeben.

• Sie können minimumCacheTTL konfigurieren, um die Cache-Dauer zu erhöhen, wenn der Upstream Cache-Control-Header fehlt oder der Wert sehr niedrig ist.
• Sie können deviceSizes und imageSizes konfigurieren, um die Gesamtzahl der möglichen generierten Bilder zu reduzieren.
• Sie können Formate konfigurieren, um mehrere Formate zugunsten eines einzelnen Bildformats zu deaktivieren.

minimumCacheTTL

Sie können die Time to Live (TTL) in Sekunden für zwischengespeicherte optimierte Bilder konfigurieren. In vielen Fällen ist es besser, einen statischen Bildimport zu verwenden, der den Dateiinhalt automatisch hasht und das Bild mit einem Cache-Control-Header von immutable dauerhaft zwischenspeichert.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

Die Ablaufzeit (oder eher Max Age) des optimierten Bildes wird entweder durch minimumCacheTTL oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher größer ist.

Wenn Sie das Caching-Verhalten pro Bild ändern müssen, können Sie headers konfigurieren, um den Cache-Control-Header auf dem Upstream-Bild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Es gibt derzeit keinen Mechanismus zum Ungültigmachen des Caches, daher ist es am besten, minimumCacheTTL niedrig zu halten. Andernfalls müssen Sie möglicherweise die src-Eigenschaft manuell ändern oder <distDir>/cache/images löschen.

disableStaticImages

Das Standardverhalten ermöglicht es Ihnen, statische Dateien wie import icon from './icon.png' zu importieren und dann an die src-Eigenschaft zu übergeben.

In einigen Fällen möchten Sie diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins kollidiert, die erwarten, dass der Import sich anders verhält.

Sie können statische Bildimporte in Ihrer next.config.js deaktivieren:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

Der standardmäßige Loader optimiert SVG-Bilder aus mehreren Gründen nicht. Erstens ist SVG ein Vektorformat, was bedeutet, dass es verlustfrei skaliert werden kann. Zweitens bietet SVG viele der gleichen Funktionen wie HTML/CSS, was ohne ordnungsgemäße Content Security Policy (CSP) Headers zu Sicherheitslücken führen kann.

Daher empfehlen wir die Verwendung der unoptimized-Prop, wenn bekannt ist, dass die src-Prop eine SVG-Datei ist. Dies geschieht automatisch, wenn src mit ".svg" endet.

Falls Sie dennoch SVG-Bilder mit der standardmäßigen Image Optimization API bereitstellen müssen, können Sie dangerouslyAllowSVG in Ihrer next.config.js festlegen:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

Zusätzlich wird dringend empfohlen, contentDispositionType zu setzen, um den Browser zum Herunterladen des Bildes zu zwingen, sowie contentSecurityPolicy, um die Ausführung von Skripten im Bild zu verhindern.

Animierte Bilder

Der standardmäßige Loader umgeht die Bildoptimierung automatisch für animierte Bilder und liefert das Bild unverändert.

Die automatische Erkennung animierter Dateien ist bestmöglich und unterstützt GIF, APNG und WebP. Wenn Sie die Bildoptimierung für ein bestimmtes animiertes Bild explizit umgehen möchten, verwenden Sie die unoptimized-Prop.

Responsive Bilder

Das standardmäßig generierte srcset enthält 1x- und 2x-Bilder, um verschiedene Gerätepixeldichten zu unterstützen. Möglicherweise möchten Sie jedoch ein responsives Bild rendern, das sich mit dem Viewport streckt. In diesem Fall müssen Sie sizes sowie style (oder className) setzen.

Sie können ein responsives Bild mit einer der folgenden Methoden rendern.

Responsives Bild mit statischem Import

Wenn das Quellbild nicht dynamisch ist, können Sie es statisch importieren, um ein responsives Bild zu erstellen:

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="Bild des Autors"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

Ausprobieren:

• Demo des viewport-responsiven Bildes

Responsives Bild mit Seitenverhältnis

Wenn das Quellbild dynamisch ist oder eine Remote-URL hat, müssen Sie auch width und height angeben, um das korrekte Seitenverhältnis des responsiven Bildes festzulegen:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Bild des Autors"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Ausprobieren:

• Demo des viewport-responsiven Bildes

Responsives Bild mit fill

Wenn Sie das Seitenverhältnis nicht kennen, müssen Sie die fill-Prop setzen und position: relative auf dem übergeordneten Element festlegen. Optional können Sie den object-fit-Style je nach gewünschtem Streck- oder Zuschneideverhalten setzen:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="Bild des Autors"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

Ausprobieren:

• Demo der fill-Prop

Theme Detection CSS

Wenn Sie ein anderes Bild für den Hell- und Dunkelmodus anzeigen möchten, können Sie eine neue Komponente erstellen, die zwei <Image>-Komponenten umschließt und die richtige basierend auf einer CSS-Media-Query anzeigt.

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

Gut zu wissen: Das Standardverhalten von loading="lazy" stellt sicher, dass nur das korrekte Bild geladen wird. Sie können priority oder loading="eager" nicht verwenden, da dies dazu führen würde, dass beide Bilder geladen werden. Stattdessen können Sie fetchPriority="high" verwenden.

Ausprobieren:

• Demo der Hell/Dunkelmodus-Theme-Erkennung

getImageProps

Für fortgeschrittene Anwendungsfälle können Sie getImageProps() aufrufen, um die Props zu erhalten, die an das zugrunde liegende <img>-Element übergeben würden, und diese stattdessen an eine andere Komponente, einen Style, ein Canvas usw. weitergeben.

Dadurch wird auch der Aufruf von React useState() vermieden, was zu einer besseren Leistung führen kann, aber es kann nicht mit der placeholder-Prop verwendet werden, da der Platzhalter niemals entfernt wird.

Theme Detection Picture

Wenn Sie ein anderes Bild für den Hell- und Dunkelmodus anzeigen möchten, können Sie das <picture>-Element verwenden, um basierend auf dem bevorzugten Farbschema des Benutzers ein anderes Bild anzuzeigen.

import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: 'Theme-Beispiel', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })

  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

Art Direction

Wenn Sie ein anderes Bild für Mobilgeräte und Desktop anzeigen möchten, manchmal auch als Art Direction bezeichnet, können Sie verschiedene src, width, height und quality-Props an getImageProps() übergeben.

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'Art Direction-Beispiel', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

Hintergrund-CSS

Sie können die srcSet-Zeichenkette sogar in die image-set()-CSS-Funktion umwandeln, um ein Hintergrundbild zu optimieren.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hallo Welt</h1>
    </main>
  )
}

Bekannte Browser-Bugs

Diese next/image-Komponente verwendet das native 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 kann es auf älteren Browsern vor Safari 15 zu Layout Shift kommen, die das Seitenverhältnis nicht beibehalten. Weitere Details finden Sie in diesem MDN-Video.

• Safari 15 - 16.3 zeigt einen grauen Rand während des Ladens an. Safari 16.4 hat dieses Problem behoben. Mögliche Lösungen:
  • Verwenden Sie CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Verwenden Sie priority, wenn das Bild oberhalb des Folds liegt
• Firefox 67+ zeigt einen weißen Hintergrund während des Ladens an. Mögliche Lösungen:
  • Aktivieren Sie AVIF formats
  • Verwenden Sie placeholder

Versionsverlauf