<Image> (Legacy)

Ab Next.js 13 wurde die next/image-Komponente überarbeitet, um sowohl die Leistung als auch die Developer Experience 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 <span>-Wrapper um <img> zugunsten von nativer berechneter Seitenverhältnis
• Fügt Unterstützung für den kanonischen style-Prop hinzu
  • Entfernt layout-Prop zugunsten von style oder className
  • Entfernt objectFit-Prop zugunsten von style oder className
  • Entfernt objectPosition-Prop zugunsten von style oder className
• Entfernt IntersectionObserver-Implementierung zugunsten von nativem Lazy Loading
  • Entfernt lazyBoundary-Prop, da es kein natives Äquivalent gibt
  • Entfernt lazyRoot-Prop, da es kein natives Äquivalent gibt
• Entfernt loader-Konfiguration zugunsten des loader-Props
• Ändert alt-Prop von optional zu erforderlich
• Ändert onLoadingComplete-Callback, um Referenz auf <img>-Element zu erhalten

Erforderliche Props

Die <Image />-Komponente erfordert folgende 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 Anzeigegröß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 Anzeigegröß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 neben den erforderlichen. 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 oft mit der objectFit-Eigenschaft kombiniert.
  • Stellen Sie sicher, dass das Elternelement position: relative in seinem Stylesheet hat.
• Demo Hintergrundbild

loader

Eine benutzerdefinierte Funktion zur Auflösung von URLs. Das Setzen des Loaders als Prop 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 einen benutzerdefinierten Loader:

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

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 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 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 dazu führt, dass ein Bild auf Mobilgeräten die volle Breite einnimmt, auf Tablets in einem 2-Spalten-Layout und auf Desktop-Displays in einem 3-Spalten-Layout, sollten Sie eine sizes-Eigenschaft wie folgt angeben:

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 kann 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.

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

priority

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-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-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 folgende erweiterte 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 ü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 folgenden Eigenschaften:

• naturalWidth
• naturalHeight

loading

Hinweis: Diese Eigenschaft ist nur für fortgeschrittene 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. Die Verwendung größerer Bilder als Platzhalter kann die Leistung Ihrer Anwendung beeinträchtigen.

Probieren Sie es aus:

• Demo der standardmäßigen blurDataURL-Prop
• 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).

Die Ref muss auf ein DOM-Element oder eine React-Komponente zeigen, die die 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 bereitgestellt, ohne Qualität, Größe oder Format anzupassen. 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 die next.config.js mit folgender Konfiguration aktualisiert wird:

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

Weitere Eigenschaften

Andere Eigenschaften der <Image />-Komponente werden an das zugrundeliegende 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/**',
      },
    ],
  },
}

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

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

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

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. 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:

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

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

Domains

Warnung: Wir empfehlen, strikte remotePatterns anstelle von domains zu konfigurieren, um Ihre Anwendung vor böswilligen Nutzern zu schützen. Verwenden Sie domains nur, wenn Ihnen alle Inhalte der Domain gehören.

Ä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.

Hier 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 eingebaute Next.js Image Optimization API zu nutzen, können Sie den loader und das path-Präfix in Ihrer next.config.js-Datei konfigurieren. Dadurch können Sie relative URLs für das Bild-src verwenden und automatisch die korrekte absolute URL für Ihren Anbieter generieren.

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

Eingebaute 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 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.

Erweitert

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

Device Sizes

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 die folgende Standardeinstellung verwendet.

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

Image Sizes

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, die zur Generierung der Bild-srcsets verwendet werden.

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 die Größen in imageSizes alle kleiner sein als die kleinste Größe in deviceSizes.

Wenn keine Konfiguration angegeben 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.

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 angegeben 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 typischerweise 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 Bedarf dynamisch optimiert und im Verzeichnis <distDir>/cache/images gespeichert. Die optimierte Bilddatei wird für nachfolgende Anfragen bereitgestellt, bis die Gültigkeitsdauer abgelaufen ist. Wenn eine Anfrage gemacht wird, die auf eine zwischengespeicherte, aber abgelaufene Datei zutrifft, 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, 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 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 nachgeschaltete 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.

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

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

Die Gültigkeitsdauer (oder Max Age) des optimierten Bildes wird entweder durch die 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 auf dem Upstream-Bild zu setzen (z.B. /some-asset.jpg, nicht /_next/image selbst).

Es gibt derzeit keinen Mechanismus zum Invalidieren 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 diese dann der src-Eigenschaft zuzuweisen.

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

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 der gleichen Funktionen wie HTML/CSS, was ohne entsprechende Content Security Policy (CSP) headers zu Sicherheitslücken führen kann.

Wenn Sie 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 stellt das Bild unverändert bereit.

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