<Image> (Legacy)

Ab Next.js 13 wurde die next/image-Komponente überarbeitet, um sowohl die Leistung als auch die Entwicklererfahrung zu verbessern. Um eine abwärtskompatible Upgrade-Lösung bereitzustellen, wurde die alte next/image-Komponente in next/legacy/image umbenannt.

Siehe die neue next/image-API-Referenz

Vergleich

Im Vergleich zu next/legacy/image weist die neue next/image-Komponente folgende Änderungen auf:

• Entfernt das <span>-Wrapper um <img> zugunsten von nativ berechnetem Seitenverhältnis
• Fügt Unterstützung für den kanonischen style-Prop hinzu
  • Entfernt den layout-Prop zugunsten von style oder className
  • Entfernt den objectFit-Prop zugunsten von style oder className
  • Entfernt den objectPosition-Prop zugunsten von style oder className
• Entfernt die IntersectionObserver-Implementierung zugunsten von nativem Lazy Loading
  • Entfernt den lazyBoundary-Prop, da es keine native Entsprechung gibt
  • Entfernt den lazyRoot-Prop, da es keine native Entsprechung gibt
• Entfernt die loader-Konfiguration zugunsten des loader-Props
• Ändert den alt-Prop von optional zu erforderlich
• Ändert den onLoadingComplete-Callback, um eine Referenz auf das <img>-Element zu erhalten

Erforderliche Props

Die <Image />-Komponente erfordert die folgenden Eigenschaften.

src

Muss eines der folgenden sein:

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

Bei Verwendung einer externen URL muss diese zu remotePatterns in next.config.js hinzugefügt werden.

width

Die width-Eigenschaft kann entweder die gerenderte Breite oder die ursprüngliche Breite in Pixeln darstellen, abhängig von den Eigenschaften layout und sizes.

Bei Verwendung von layout="intrinsic" oder layout="fixed" stellt die width-Eigenschaft die gerenderte Breite in Pixeln dar und beeinflusst somit die Darstellungsgröße des Bildes.

Bei Verwendung von layout="responsive" oder layout="fill" stellt die width-Eigenschaft die ursprüngliche Breite in Pixeln dar und beeinflusst nur das Seitenverhältnis.

Die width-Eigenschaft ist erforderlich, außer für statisch importierte Bilder oder solche mit layout="fill".

height

Die height-Eigenschaft kann entweder die gerenderte Höhe oder die ursprüngliche Höhe in Pixeln darstellen, abhängig von den Eigenschaften layout und sizes.

Bei Verwendung von layout="intrinsic" oder layout="fixed" stellt die height-Eigenschaft die gerenderte Höhe in Pixeln dar und beeinflusst somit die Darstellungsgröße des Bildes.

Bei Verwendung von layout="responsive" oder layout="fill" stellt die height-Eigenschaft die ursprüngliche Höhe in Pixeln dar und beeinflusst nur das Seitenverhältnis.

Die height-Eigenschaft ist erforderlich, außer für statisch importierte Bilder oder solche mit layout="fill".

Optionale Props

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

layout

Das Layoutverhalten des Bildes bei Änderung der Viewport-Größe.

• Demo des intrinsic-Layouts (Standard)
  • Bei intrinsic skaliert das Bild die Abmessungen für kleinere Viewports herunter, behält aber die ursprünglichen Abmessungen für größere Viewports bei.
• Demo des fixed-Layouts
  • Bei fixed ändern sich die Bildabmessungen nicht mit der Viewport-Größe (keine Responsiveness), ähnlich dem nativen img-Element.
• Demo des responsive-Layouts
  • Bei responsive skaliert das Bild die Abmessungen für kleinere Viewports herunter und für größere Viewports hoch.
  • Stellen Sie sicher, dass das Elternelement display: block in seinem Stylesheet verwendet.
• Demo des fill-Layouts
  • Bei fill streckt sich das Bild in Breite und Höhe auf die Abmessungen des Elternelements, vorausgesetzt das Elternelement ist relativ positioniert.
  • Dies wird normalerweise mit der objectFit-Eigenschaft kombiniert.
  • Stellen Sie sicher, dass das Elternelement position: relative in seinem Stylesheet hat.
• Demo des Hintergrundbildes

loader

Eine benutzerdefinierte Funktion zur Auflösung von URLs. Das Setzen des Loaders als Prop auf der Image-Komponente überschreibt den Standard-Loader, der im images-Abschnitt von next.config.js definiert ist.

Ein loader ist eine Funktion, die eine URL-Zeichenkette 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/legacy/image'

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

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

Eine Zeichenkette, die Informationen darüber liefert, wie breit das Bild bei verschiedenen Breakpoints sein wird. Der Wert von sizes beeinflusst die Leistung für Bilder mit layout="responsive" oder layout="fill" erheblich. Er wird für Bilder mit layout="intrinsic" oder layout="fixed" ignoriert.

Die sizes-Eigenschaft 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 Source-Set von next/legacy/image heruntergeladen werden soll. Wenn der Browser die Auswahl trifft, 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-Eigenschaft ermöglicht es Ihnen, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als die volle Bildschirmbreite sein wird. Wenn Sie keinen sizes-Wert angeben, wird der Standardwert 100vw (volle Bildschirmbreite) verwendet.

Zweitens wird der sizes-Wert analysiert und verwendet, um die Werte im automatisch erstellten Source-Set zu kürzen. Wenn die sizes-Eigenschaft Größen wie 50vw enthält, die einen Prozentsatz der Viewport-Breite darstellen, wird das Source-Set so gekürzt, dass keine Werte enthalten sind, die zu klein sind, um jemals benötigt zu werden.

Wenn Sie beispielsweise wissen, dass Ihr Styling dazu führt, dass ein Bild auf Mobilgeräten vollständig breit ist, in einem 2-Spalten-Layout auf Tablets und in einem 3-Spalten-Layout auf Desktop-Displays, sollten Sie eine sizes-Eigenschaft wie die folgende einfügen:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

Dieses sizes-Beispiel könnte sich dramatisch auf Leistungskennzahlen auswirken. 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 9-mal größer ist als notwendig.

Mehr über srcset und sizes erfahren:

• web.dev
• mdn

quality

Die Qualität des optimierten Bildes, eine ganze Zahl zwischen 1 und 100, wobei 100 die beste Qualität ist. Standardwert ist 75.

priority

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

Sie sollten die priority-Eigenschaft 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

Ein Platzhalter, der während des Ladens des Bildes verwendet wird. Mögliche Werte sind blur oder empty. Standardwert 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.

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

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

Probieren Sie es aus:

• Demo des blur-Placeholders
• Demo des Schimmer-Effekts mit blurDataURL-Prop
• Demo des Farb-Effekts 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 das Übergeben von CSS-Styles an das zugrunde liegende Bildelement.

Beachten Sie, dass alle layout-Modi ihre eigenen Styles auf das Bildelement anwenden und diese automatischen Styles Vorrang vor dem style-Prop haben.

Beachten Sie auch, dass die erforderlichen width- und height-Props mit Ihrem Styling interagieren können. Wenn Sie das Styling verwenden, um die width eines Bildes zu ändern, müssen Sie auch den Style height="auto" setzen, da das Bild sonst verzerrt wird.

objectFit

Definiert, wie das Bild in seinen Elterncontainer passt, wenn layout="fill" verwendet wird.

Dieser Wert wird an die object-fit CSS-Eigenschaft für das src-Bild übergeben.

objectPosition

Definiert, wie das Bild innerhalb seines Elternelements positioniert wird, wenn layout="fill" verwendet wird.

Dieser Wert wird an die object-position CSS-Eigenschaft übergeben, die auf das Bild angewendet wird.

onLoadingComplete

Eine Callback-Funktion, die aufgerufen wird, sobald das Bild vollständig geladen ist und der Platzhalter entfernt wurde.

Die onLoadingComplete-Funktion akzeptiert einen Parameter, ein Objekt mit den folgenden Eigenschaften:

• naturalWidth
• naturalHeight

loading

Hinweis: Diese Eigenschaft ist nur für erweiterte Nutzung gedacht. Das Umschalten eines Bildes auf eager-Laden wird normalerweise die Leistung beeinträchtigen.

Wir empfehlen stattdessen die Verwendung der priority-Eigenschaft, die das Bild für fast alle Anwendungsfälle korrekt eager lädt.

Das Ladeverhalten des Bildes. Standardwert 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 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. Das Einbeziehen größerer Bilder als Platzhalter kann die Leistung Ihrer Anwendung beeinträchtigen.

Probieren Sie es aus:

• Demo des Standard-blurDataURL-Props
• Demo des Schimmer-Effekts mit blurDataURL-Prop
• Demo des Farb-Effekts mit blurDataURL-Prop

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

lazyBoundary

Eine Zeichenkette (mit ähnlicher Syntax wie die margin-Eigenschaft), die als Begrenzungsrahmen dient, um die Überschneidung des Viewports mit dem Bild zu erkennen und das Lazy Loading auszulösen. Standardwert ist "200px".

Wenn das Bild in einem scrollbaren Elternelement außerhalb des Root-Dokuments verschachtelt ist, müssen Sie auch das lazyRoot-Prop zuweisen.

Mehr erfahren

lazyRoot

Ein React Ref, der auf das scrollbare Elternelement zeigt. Standardwert ist null (der Dokument-Viewport).

Der Ref muss auf ein DOM-Element oder eine React-Komponente zeigen, die den Ref weiterleitet an das zugrunde liegende DOM-Element.

Beispiel für ein DOM-Element

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Beispiel für eine React-Komponente

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

Mehr erfahren

unoptimized

Wenn true, wird das Quellbild unverändert ausgeliefert, ohne Qualität, Größe oder Format anzupassen. Standardwert ist 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 die next.config.js wie folgt aktualisiert wird:

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

Weitere 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.
• ref. Verwenden Sie stattdessen onLoadingComplete.
• decoding. Ist immer "async".

Konfigurationsoptionen

Remote Patterns

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. 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/legacy/image mit https://example.com/account123/ beginnen muss und keine Abfragezeichenkette enthalten darf. Jedes andere Protokoll, Hostname, Port oder nicht übereinstimmender Pfad führt zu einer 400 Bad Request-Antwort.

Unten sehen Sie ein Beispiel für die remotePatterns-Eigenschaft in der next.config.js-Datei mit einem Wildcard-Pattern 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/legacy/image mit https://img1.example.com, https://me.avatar.example.com oder einer beliebigen Anzahl von Subdomains beginnen muss. Es darf keinen Port oder Abfragezeichenkette enthalten. Jedes andere Protokoll oder nicht übereinstimmender Hostname führt zu einer 400 Bad Request-Antwort.

Wildcard-Patterns 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 Patterns.

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

Unten sehen Sie 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/legacy/image mit https://assets.example.com beginnen und die exakte Abfragezeichenkette ?v=1727111025337 enthalten muss. Jedes andere Protokoll oder Abfragezeichenkette 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 der Domain besitzen.

Ä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 Wildcard-Pattern-Matching und kann Protokoll, Port oder Pfad nicht einschränken.

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

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

Loader-Konfiguration

Wenn Sie einen Cloud-Anbieter zur Bildoptimierung verwenden möchten, anstatt die integrierte Next.js Image Optimization API zu nutzen, können Sie den loader und das path-Präfix in Ihrer next.config.js-Datei konfigurieren. Dies ermöglicht die Verwendung relativer URLs für die Image-src und generiert automatisch die korrekte absolute URL für Ihren Anbieter.

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

Integrierte Loader

Folgende Image Optimization Cloud-Anbieter sind enthalten:

• Standard: Funktioniert automatisch mit next dev, next start oder einem benutzerdefinierten Server
• Vercel: Funktioniert automatisch bei der Bereitstellung auf Vercel, keine Konfiguration erforderlich. Mehr erfahren
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Benutzerdefiniert: loader: 'custom' verwendet einen benutzerdefinierten Cloud-Anbieter durch Implementierung der loader-Eigenschaft in der next/legacy/image-Komponente

Falls Sie einen anderen Anbieter benötigen, können Sie die loader-Eigenschaft mit next/legacy/image verwenden.

Bilder können nicht zur Build-Zeit mit output: 'export' optimiert werden, sondern nur bei Bedarf. Um next/legacy/image mit output: 'export' zu verwenden, müssen Sie einen anderen Loader als den Standard verwenden. Mehr in der Diskussion.

Der Standard-Loader der next/legacy/image-Komponente verwendet squoosh, da es schnell installiert ist und für eine Entwicklungsumgebung geeignet ist. Wenn Sie next start in Ihrer Produktionsumgebung verwenden, wird dringend empfohlen, sharp durch Ausführen von npm i sharp in Ihrem Projektverzeichnis zu installieren. Dies ist für Vercel-Bereitstellungen nicht erforderlich, da sharp automatisch installiert wird.

Fortgeschritten

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

Gerätegrößen

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/legacy/image-Komponente layout="responsive" oder layout="fill" verwendet, um sicherzustellen, dass das richtige Bild für das Gerät des Nutzers bereitgestellt wird.

Wenn keine Konfiguration angegeben wird, wird der folgende Standard verwendet.

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

Bildgrößen

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 kombiniert, um das vollständige Array der Größen zu bilden, das zur Generierung der 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 angegeben wird, wird der folgende Standard verwendet.

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

Akzeptierte Formate

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 gefunden wird (oder das Quellbild animiert ist), greift die Image Optimization API auf das ursprüngliche Format des Bildes zurück.

Wenn keine Konfiguration angegeben wird, wird der folgende Standard 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 jedoch 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.

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. Das optimierte Bild wird für nachfolgende Anfragen bereitgestellt, bis die Gültigkeitsdauer abläuft. 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 Wertes des x-nextjs-cache-Headers (x-vercel-cache bei Bereitstellung auf Vercel) 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, aber die Revalidierungszeit wurde überschritten und wird im Hintergrund aktualisiert
• HIT - Der Pfad ist im Cache und die Revalidierungszeit wurde nicht überschritten

Die Gültigkeitsdauer (oder eher Max Age) wird entweder durch die minimumCacheTTL-Konfiguration oder den Cache-Control-Header des Upstream-Bildes 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 vorhanden sind, wird s-maxage bevorzugt. Der max-age wird auch an alle nachgeschalteten Clients, einschließlich CDNs und Browser, weitergegeben.

• Sie können minimumCacheTTL konfigurieren, um die Cache-Dauer zu erhöhen, wenn der Upstream-Header Cache-Control nicht vorhanden ist 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.

Minimum Cache TTL

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 automatisch den Dateiinhalt hashed und das Bild mit einem Cache-Control-Header von immutable für immer zwischenspeichert.

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

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

Wenn Sie das Caching-Verhalten pro Bild ändern müssen, können Sie headers konfigurieren, um den Cache-Control-Header für das 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 manuell die src-Eigenschaft ändern oder <distDir>/cache/images löschen.

Statische Imports deaktivieren

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 anders funktioniert.

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

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

Gefährlich SVG erlauben

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 Funktionen, die HTML/CSS ähneln, was ohne korrekte Content Security Policy (CSP) headers zu Sicherheitslücken führen kann.

Daher empfehlen wir, die unoptimized-Eigenschaft zu verwenden, wenn die src-Eigenschaft als SVG bekannt ist. Dies geschieht automatisch, wenn src mit ".svg" endet.

Falls Sie jedoch 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, die in das Bild eingebettet sind, zu verhindern.

Animierte Bilder

Der Standard-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-Eigenschaft.

Versionsverlauf