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 den <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 kein natives Äquivalent gibt
  • Entfernt den lazyRoot-Prop, da es kein natives Äquivalent 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 des Standard-loaders sind folgende Punkte für Quellbilder zu beachten:

• Wenn src eine externe URL ist, müssen Sie auch remotePatterns konfigurieren
• Wenn src animiert ist oder kein bekanntes Format (JPEG, PNG, WebP, AVIF, GIF, TIFF) hat, wird das Bild unverändert bereitgestellt
• Wenn src das SVG-Format hat, wird es blockiert, es sei denn, unoptimized oder dangerouslyAllowSVG ist aktiviert

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 wie beim 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 übergeordnete Element display: block in seinem Stylesheet verwendet.
• Demo des fill-Layouts
  • Bei fill dehnt sich das Bild in Breite und Höhe auf die Abmessungen des übergeordneten Elements aus, vorausgesetzt, das übergeordnete Element ist relativ positioniert.
  • Dies wird oft mit der objectFit-Eigenschaft kombiniert.
  • Stellen Sie sicher, dass das übergeordnete Element 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-String für das Bild zurückgibt, basierend auf den 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

Ein String, der 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 geparst 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 bewirkt, 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 verwenden:

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 neunmal größer ist als notwendig.

Weitere Informationen zu srcset und sizes:

• web.dev
• mdn

quality

Die Qualität des optimierten Bildes, eine Ganzzahl 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 unterschiedliche 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-Platzhalters
• 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 übergeordneten Container 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 übergeordneten Elements positioniert wird, wenn layout="fill" verwendet wird.

Dieser Wert wird an die object-position CSS-Eigenschaft angewendet, 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

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.

Weitere Informationen

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. Die Verwendung 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 Data URL mit einfarbigem Hintergrund generieren, um dem Bild zu entsprechen.

lazyBoundary

Ein String (mit ähnlicher Syntax wie die margin-Eigenschaft), der 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 übergeordneten Element außerhalb des Root-Dokuments verschachtelt ist, müssen Sie auch den lazyRoot-Prop zuweisen.

Weitere Informationen

lazyRoot

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

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

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>
  )
}

Weitere Informationen

unoptimized

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

Dies ist nützlich für Bilder, die nicht von einer Optimierung profitieren, wie kleine Bilder (weniger als 1 KB), Vektorgrafiken (SVG) oder animierte Bilder (GIF).

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 der folgenden Konfiguration aktualisiert wird:

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

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.
• 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 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/legacy/image mit https://example.com/account123/ beginnen muss und keine Abfragezeichenfolge enthalten darf. Jedes andere Protokoll, Hostname, Port oder nicht übereinstimmender Pfad wird mit 400 Bad Request antworten.

Unten ist 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 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 wird mit 400 Bad Request antworten.

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 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/legacy/image mit https://assets.example.com beginnen und die exakte Abfragezeichenfolge ?v=1727111025337 enthalten muss. Jedes andere Protokoll oder Abfragezeichenfolge wird mit 400 Bad Request antworten.

Domains

Warnung: Seit Next.js 14 veraltet zugunsten von strikten 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 erlaubter Hostnamen für externe Bilder bereitzustellen.

Die domains-Konfiguration unterstützt jedoch keine Wildcard-Pattern-Matching 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'],
  },
}

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 das Bild-src und generiert automatisch die korrekte absolute URL für Ihren Anbieter.

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

Integrierte Loader

Die folgenden 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 der next/legacy/image-Komponente

Wenn 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, 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.

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-Standardeinstellungen 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 bereitgestellt wird, wird die folgende Standardeinstellung 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 verkettet, 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 bereitgestellt wird, wird die folgende Standardeinstellung verwendet.

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

Akzeptable Formate

Die standardmäßige 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 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 aktivieren, die auf das ursprüngliche Format des src-Bildes zurückfällt, wenn der Browser AVIF nicht unterstützt:

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

Gut zu wissen:

• Wir empfehlen dennoch, WebP für die meisten Anwendungsfälle zu verwenden.
• AVIF benötigt im Allgemeinen 50 % mehr Zeit für die Kodierung, komprimiert jedoch 20 % kleiner im Vergleich zu WebP. Das bedeutet, dass die erste Anforderung eines Bildes in der Regel langsamer ist und nachfolgende Anfragen, die zwischengespeichert werden, schneller sind.
• Wenn Sie Next.js selbst hosten mit einem Proxy/CDN davor, 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 Bedarf 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 gemacht wird, die auf eine zwischengespeicherte, aber abgelaufene Datei passt, wird das abgelaufene Bild sofort als "stale" 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 Lesen des Werts 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, 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 vielmehr Max Age) wird entweder durch die minimumCacheTTL-Konfiguration oder den Cache-Control-Header des Upstream-Bildes definiert, je nachdem, welcher größer ist. Insbesondere 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 nachgeschaltete Clients, einschließlich CDNs und Browser, weitergegeben.

• Sie können minimumCacheTTL konfigurieren, um die Cache-Dauer zu erhöhen, wenn das Upstream-Bild keinen Cache-Control-Header enthält 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 den Dateiinhalt automatisch hashed und das Bild für immer mit einem Cache-Control-Header von immutable zwischenspeichert.

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

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 Minute
  },
}

Sie können die TTL erhöhen, um die Anzahl der Revalidierungen und potenziell die Kosten zu senken:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 Tage
  },
}

Die Ablaufzeit (oder vielmehr 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 für das Upstream-Bild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Es gibt derzeit keinen Mechanismus zur Invalidierung 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 ein anderes Importverhalten erwarten.

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 einigen 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 ordnungsgemäße Content Security Policy (CSP) Headers zu Sicherheitslücken führen kann.

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

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

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.

contentDispositionType

Der Standard-Loader setzt den Content-Disposition-Header auf attachment für zusätzlichen Schutz, da die API beliebige Remote-Bilder bereitstellen kann.

Der Standardwert ist attachment, was den Browser zwingt, das Bild beim direkten Besuch herunterzuladen. Dies ist besonders wichtig, wenn dangerouslyAllowSVG auf true gesetzt ist.

Sie können optional inline konfigurieren, um dem Browser zu erlauben, das Bild beim direkten Besuch zu rendern, ohne es herunterzuladen.

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

Animierte Bilder

Der Standard-Loader umgeht die Bildoptimierung automatisch für animierte Bilder und stellt das Bild unverändert bereit.

Die Auto-Erkennung für animierte 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