<Image> (Legacy)

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

Ansehen der neuen next/image API-Referenz

Vergleich

Im Vergleich zu next/legacy/image hat die neue next/image-Komponente die folgenden Änderungen:

• Entfernt <span>-Wrapper um <img> zugunsten von nativem berechneten Seitenverhältnis
• Fügt Unterstützung für kanonische style-Eigenschaft hinzu
  • Entfernt layout-Eigenschaft zugunsten von style oder className
  • Entfernt objectFit-Eigenschaft zugunsten von style oder className
  • Entfernt objectPosition-Eigenschaft zugunsten von style oder className
• Entfernt IntersectionObserver-Implementierung zugunsten von nativem Lazy Loading
  • Entfernt lazyBoundary-Eigenschaft, da es kein natives Äquivalent gibt
  • Entfernt lazyRoot-Eigenschaft, da es kein natives Äquivalent gibt
• Entfernt loader-Konfiguration zugunsten von loader-Eigenschaft
• Ändert alt-Eigenschaft von optional zu erforderlich
• Ändert onLoadingComplete-Callback, um Referenz auf <img>-Element zu empfangen

Erforderliche Eigenschaften

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

src

Muss eine der folgenden Optionen sein:

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

Bei Verwendung des Standard-Loaders beachten Sie außerdem Folgendes für Quellbilder:

• 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 im SVG-Format ist, wird es blockiert, es sei denn, unoptimized oder dangerouslyAllowSVG ist aktiviert

width

Die width-Eigenschaft kann die gerenderte oder originale Breite in Pixel darstellen, abhängig von den layout- und sizes-Eigenschaften.

Bei Verwendung von layout="intrinsic" oder layout="fixed" stellt die width-Eigenschaft die gerenderte Breite in Pixel dar, sodass sie die Größe des Bildes beeinflussen wird.

Bei Verwendung von layout="responsive", layout="fill" stellt die width-Eigenschaft die originale Breite in Pixel dar, sodass sie nur das Seitenverhältnis beeinflusst.

Die width-Eigenschaft ist erforderlich, außer bei statisch importierten Bildern oder solchen mit layout="fill".

height

Die height-Eigenschaft kann die gerenderte oder originale Höhe in Pixel darstellen, abhängig von den layout- und sizes-Eigenschaften.

Bei Verwendung von layout="intrinsic" oder layout="fixed" stellt die height-Eigenschaft die gerenderte Höhe in Pixel dar, sodass sie die Größe des Bildes beeinflussen wird.

Bei Verwendung von layout="responsive", layout="fill" stellt die height-Eigenschaft die originale Höhe in Pixel dar, sodass sie nur das Seitenverhältnis beeinflusst.

Die height-Eigenschaft ist erforderlich, außer bei statisch importierten Bildern oder solchen mit layout="fill".

Optionale Eigenschaften

Die <Image />-Komponente akzeptiert zusätzlich zu den erforderlichen Eigenschaften noch eine Reihe weiterer Eigenschaften. Dieser Abschnitt beschreibt die am häufigsten verwendeten Eigenschaften der Bildkomponente. Details zu selten verwendeten Eigenschaften finden Sie im Abschnitt Erweiterte Eigenschaften.

layout

Das Layout-Verhalten des Bildes, wenn sich die Viewport-Größe ändert.

• 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, wenn sich der Viewport ändert (keine Responsivität), ä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 herauf.
  • Stellen Sie sicher, dass das übergeordnete Element display: block in ihrem Stylesheet verwendet.
• Demo des fill-Layouts
  • Bei fill streckt sich das Bild sowohl in Breite als auch Höhe auf die Abmessungen des übergeordneten Elements, vorausgesetzt, das übergeordnete Element ist relativ.
  • Dies wird normalerweise mit der objectFit-Eigenschaft kombiniert.
  • Stellen Sie sicher, dass das übergeordnete Element position: relative in ihrem Stylesheet hat.
• Demo Hintergrundbild

loader

Eine benutzerdefinierte Funktion zur Auflösung von URLs. Das Festlegen des Loaders als Eigenschaft auf der Bildkomponente überschreibt den standardmäßigen 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 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="Bild des Autors"
      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 wird die Leistung für Bilder mit layout="responsive" oder layout="fill" stark beeinflussen. Er wird für Bilder mit layout="intrinsic" oder layout="fixed" ignoriert.

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

Zunächst wird der Wert von sizes vom Browser verwendet, um zu bestimmen, welche Bildgröße aus dem automatisch generierten Quellensatz von next/legacy/image heruntergeladen werden soll. Wenn der Browser auswä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-Eigenschaft ermöglicht es Ihnen, dem Browser mitzuteilen, dass das Bild tatsächlich kleiner als der gesamte Bildschirm sein wird. Wenn Sie keinen sizes-Wert angeben, wird standardmäßig 100vw (volle Bildschirmbreite) verwendet.

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

Zum Beispiel, wenn Sie wissen, dass Ihr Styling ein Bild auf mobilen Geräten vollbreite, auf Tablets in einer 2-Spalten-Anordnung und auf Desktopanzeigen in einer 3-Spalten-Anordnung darstellen wird, sollten Sie eine sizes-Eigenschaft wie 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 Beispiel für sizes könnte dramatische Auswirkungen auf die Performance-Metriken haben. Ohne die 33vw-Größen 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 erforderlich.

Erfahren Sie mehr über 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. Standard ist 75.

priority

Wenn true, wird das Bild als hochprioritär betrachtet und vorgeladen. Lazy Loading wird für Bilder mit priority automatisch deaktiviert.

Sie sollten die priority-Eigenschaft für alle Bilder verwenden, die als Largest Contentful Paint (LCP)-Element erkannt werden. Es kann angemessen sein, mehrere Bilder mit Priorität zu haben, da verschiedene Bilder das LCP-Element für unterschiedliche Viewport-Größen sein können.

Sollte nur verwendet werden, wenn das Bild oberhalb des Scrollbereichs sichtbar ist. Standard ist false.

placeholder

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

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 keinen Platzhalter während des Bilderladens, nur leeren Raum.

Probieren Sie es aus:

• Demo des blur-Platzhalters
• Demo des Shimmer-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-Stilen an das zugrunde liegende Bildelement.

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

Bedenken Sie auch, dass die erforderlichen width- und height-Props mit Ihrer Formatierung interagieren können. Wenn Sie Formatierung verwenden, um die width eines Bildes zu ändern, müssen Sie auch height="auto" einstellen, sonst wird Ihr Bild verzerrt.

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 für das Bild übergeben.

onLoadingComplete

Eine Rückruffunktion, die aufgerufen wird, sobald das Bild vollständig geladen und der Platzhalter entfernt wurde.

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

• naturalWidth
• naturalHeight

loading

Das Ladeverhalten des Bildes. Standard ist lazy.

Bei lazy wird das Laden des Bildes verzögert, bis es eine berechnete Distanz zum Viewport erreicht.

Bei eager wird das Bild sofort geladen.

Mehr erfahren

blurDataURL

Eine Data-URL, die als Platzhalter-Bild verwendet wird, bevor das src-Bild erfolgreich lädt. Wirkt nur in Kombination mit placeholder="blur".

Muss ein base64-kodiertes Bild sein. Es wird vergrößert und verwischt, daher wird ein sehr kleines Bild (10px oder weniger) empfohlen. Das Einbinden größerer Bilder als Platzhalter kann die Leistung Ihrer Anwendung beeinträchtigen.

Probieren Sie es aus:

• Demo der Standard-blurDataURL-Prop
• Demo des Shimmer-Effekts mit blurDataURL-Prop
• Demo des Farb-Effekts mit blurDataURL-Prop

Sie können auch eine feste Farbe als Data-URL generieren, um das Bild zu ergänzen.

lazyBoundary

Eine Zeichenfolge (mit ähnlicher Syntax wie die Margin-Eigenschaft), die als Begrenzungsrahmen dient, um die Überschneidung des Viewports mit dem Bild zu erkennen und das verzögerte Laden auszulösen. Standard ist "200px".

Wenn das Bild in einem scrollbaren übergeordneten Element außerhalb des Dokuments verschachtelt ist, müssen Sie zusätzlich die lazyRoot-Prop zuweisen.

Mehr erfahren

lazyRoot

Eine React-Referenz, die auf das scrollbare übergeordnete Element zeigt. Standard ist null (der Dokument-Viewport).

Die Referenz muss auf ein DOM-Element oder eine React-Komponente zeigen, die die Referenz 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>
  )
}

Weitere Informationen

unoptimized

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

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

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. Es ist immer "async".

Konfigurationsoptionen

Remote-Muster

Um Ihre 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 Ihrem Konto über die Next.js-Bildoptimierungs-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: '',
      },
    ],
  },
}

Hinweis: Das obige Beispiel stellt sicher, dass die src-Eigenschaft von next/legacy/image mit https://example.com/account123/ beginnen und keine Abfragezeichenfolge haben muss. Jedes andere Protokoll, Hostname, Port oder nicht übereinstimmende Pfad wird mit 400 Bad Request geantwortet.

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

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

Hinweis: 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 haben. Jedes andere Protokoll oder nicht übereinstimmender Hostname wird mit 400 Bad Request geantwortet.

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.

Hinweis: Beim Weglassen von protocol, port, pathname oder search wird das Wildcard ** impliziert. Dies wird nicht empfohlen, da es böswilligen Akteuren ermöglichen kann, URLs zu optimieren, die Sie nicht beabsichtigt haben.

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

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

Hinweis: 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 haben muss. Jedes andere Protokoll oder Abfragezeichenfolge wird mit 400 Bad Request geantwortet.

Domains

Warnung: Seit Next.js 14 veraltet zugunsten der strengen remotePatterns, um Ihre Anwendung vor böswilligen Benutzern zu schützen. Verwenden Sie domains nur, wenn Sie den gesamten Inhalt der Domain besitzen.

Ä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-Mustererkennung und kann Protokoll, Port oder Pfadnamen nicht einschränken.

Hier ist ein Beispiel für die Eigenschaft domains 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-Bildoptimierungs-API zu nutzen, können Sie den loader und das Pfadpräfix in Ihrer next.config.js-Datei konfigurieren. Dies ermöglicht es Ihnen, relative URLs für das Bild-src zu verwenden und automatisch die korrekte absolute URL für Ihren Anbieter zu generieren.

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

Integrierte Loader

Die folgenden Bildoptimierungs-Cloud-Anbieter sind enthalten:

• Standard: Funktioniert automatisch mit next dev, next start oder einem benutzerdefinierten Server
• Vercel: Funktioniert automatisch bei Bereitstellung auf Vercel, keine Konfiguration erforderlich. Weitere Informationen
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Benutzerdefiniert: loader: 'custom' Verwendung eines benutzerdefinierten Cloud-Anbieters durch Implementierung der loader-Eigenschaft in 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 bei der Erstellung nicht optimiert werden mit output: 'export', nur bei Bedarf. Um next/legacy/image mit output: 'export' zu verwenden, benötigen Sie einen anderen Loader als den Standard. Weitere Informationen in der Diskussion.

Erweitert

Die folgende Konfiguration ist für Anwendungsfälle mit fortgeschrittenen Anforderungen und normalerweise nicht notwendig. Wenn Sie sich entscheiden, die nachfolgenden Eigenschaften zu konfigurieren, werden Sie alle Änderungen an den Next.js-Standardwerten in zukünftigen Updates außer Kraft setzen.

Gerätegrößen

Wenn Sie die erwarteten Gerätebreiten Ihrer Benutzer kennen, können Sie eine Liste von Gerätebreiten-Schwellenwerten mithilfe der deviceSizes-Eigenschaft 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 Benutzers bereitgestellt wird.

Wenn keine Konfiguration bereitgestellt wird, wird die unten stehende Standardeinstellung verwendet.

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

Bildgrößen

Sie können eine Liste von Bildbreiten mithilfe 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 zwei separate Listen ist, dass imageSizes nur für Bilder verwendet wird, die eine sizes-Eigenschaft bereitstellen, was darauf hinweist, dass das Bild weniger als die volle Bildschirmbreite hat. Daher sollten die Größen in imageSizes alle kleiner sein als die kleinste Größe in deviceSizes.

Wenn keine Konfiguration bereitgestellt wird, wird die unten stehende Standardeinstellung verwendet.

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

Akzeptable Formate

Die Standard-Bildoptimierungs-API wird automatisch die vom Browser unterstützten Bildformate über den Accept-Header der Anfrage erkennen, um das beste Ausgabeformat zu bestimmen.

Wenn der Accept-Header mehr als ein konfiguriertes Format übereinstimmt, wird der erste Treffer im Array verwendet. Die Arrayfolge ist daher von Bedeutung. Wenn keine Übereinstimmung besteht (oder das Quellbild animiert ist), wird die Bildoptimierungs-API auf das ursprüngliche Bildformat zurückgreifen.

Wenn keine Konfiguration bereitgestellt wird, wird die unten stehende Standardeinstellung verwendet.

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

Du kannst die AVIF-Unterstützung mit dem folgenden Konfigurationselement aktivieren und weiterhin auf WebP zurückgreifen.

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

Hinweis: AVIF benötigt im Allgemeinen 50 % länger zur Kodierung, komprimiert aber 20 % kleiner im Vergleich zu WebP. Das bedeutet, dass die erste Bildanfrage typischerweise langsamer sein wird und nachfolgende zwischengespeicherte Anfragen schneller sein werden.

Caching-Verhalten

Die folgenden Ausführungen beschreiben den Caching-Algorithmus für den Standard-Loader. Für alle anderen Loader konsultieren Sie bitte die Dokumentation Ihres Cloud-Anbieters.

Bilder werden dynamisch bei Anfrage optimiert und im Verzeichnis <distDir>/cache/images gespeichert. Die optimierte Bilddatei wird für nachfolgende Anfragen bereitgestellt, bis der Ablauf erreicht ist. Wenn eine Anfrage für eine zwischengespeicherte, aber abgelaufene Datei gestellt wird, wird das abgelaufene Bild sofort im veralteten Zustand bereitgestellt. Dann wird das Bild im Hintergrund erneut optimiert (auch als Revalidierung bezeichnet) und mit dem neuen Ablaufdatum im Cache gespeichert.

Der Cachestatus eines Bildes kann durch Auslesen des Werts des x-nextjs-cache (x-vercel-cache bei Bereitstellung auf Vercel) Response-Headers bestimmt werden. Die möglichen Werte sind die folgenden:

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

Der Ablauf (oder vielmehr Max Age) wird entweder durch die minimumCacheTTL-Konfiguration oder den Upstream-Bild Cache-Control-Header definiert, je nachdem, welcher Wert größer ist. Insbesondere 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 Browsern weitergeleitet.

• 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 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 Lebensdauer (TTL) in Sekunden für zwischengespeicherte optimierte Bilder konfigurieren. In vielen Fällen ist es besser, einen Statischen Bilderimport zu verwenden, der die Dateiinhalte automatisch hasht und das Bild mit einem Cache-Control-Header von immutable für immer zwischenspeichert.

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

Der Ablauf (oder vielmehr Max Age) des optimierten Bildes wird entweder durch minimumCacheTTL oder den Upstream-Bild Cache-Control-Header 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 auf dem Upstream-Bild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Es gibt derzeit keinen Mechanismus, den Cache zu invalidieren, 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 Importe deaktivieren

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

In manchen Fällen möchten Sie diese Funktion möglicherweise deaktivieren, wenn sie mit anderen Plugins in Konflikt gerät, 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,
  },
}

SVG gefährlich 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 wie HTML/CSS, was ohne entsprechende Content Security Policy (CSP) Header zu Sicherheitslücken führen kann.

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

Wenn Sie jedoch SVG-Bilder mit der Standard-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, auch contentDispositionType zu setzen, um den Browser zu zwingen, das Bild herunterzuladen, sowie contentSecurityPolicy, um zu verhindern, dass in das Bild eingebettete Skripte ausgeführt werden.

contentDispositionType

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

Der Standardwert ist attachment, was den Browser zwingt, das Bild beim direkten Aufrufen herunterzuladen. Dies ist besonders wichtig, wenn dangerouslyAllowSVG aktiviert ist.

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

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

Animierte Bilder

Der Standard-Loader wird automatisch die Image Optimization für animierte Bilder umgehen und das Bild unverändert bereitstellen.

Die Auto-Erkennung für animierte Dateien basiert auf Schätzungen und unterstützt GIF, APNG und WebP. Wenn Sie die Image Optimization für ein bestimmtes animiertes Bild explizit umgehen möchten, verwenden Sie die unoptimized-Eigenschaft.

Versionsverlauf