cacheLife

Die Funktion cacheLife wird verwendet, um die Lebensdauer des Caches einer Funktion oder Komponente festzulegen. Sie sollte zusammen mit der use cache-Direktive und innerhalb des Gültigkeitsbereichs der Funktion oder Komponente verwendet werden.

Verwendung

Um cacheLife zu verwenden, aktivieren Sie das dynamicIO-Flag in Ihrer next.config.js-Datei:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}

export default nextConfig

Importieren und rufen Sie dann die cacheLife-Funktion innerhalb des Gültigkeitsbereichs der Funktion oder Komponente auf:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

Referenz

Standard-Cache-Profile

Next.js bietet eine Reihe von benannten Cache-Profilen, die auf verschiedenen Zeitskalen modelliert sind. Wenn Sie kein Cache-Profil in der cacheLife-Funktion zusammen mit der use cache-Direktive angeben, wendet Next.js automatisch das default-Cache-Profil an.

Wir empfehlen jedoch, beim Verwenden der use cache-Direktive immer ein Cache-Profil hinzuzufügen, um das Caching-Verhalten explizit zu definieren.

Die Zeichenfolgenwerte, die zum Referenzieren von Cache-Profilen verwendet werden, haben keine inhärente Bedeutung; sie dienen vielmehr als semantische Bezeichnungen. Dies ermöglicht es Ihnen, Ihre zwischengespeicherten Inhalte in Ihrem Codebase besser zu verstehen und zu verwalten.

Gut zu wissen: Die Aktualisierung der Konfigurationsoptionen staleTimes und expireTime aktualisiert auch die Eigenschaften stale und expire des default-Cache-Profils.

Benutzerdefinierte Cache-Profile

Sie können benutzerdefinierte Cache-Profile konfigurieren, indem Sie sie der Option cacheLife in Ihrer next.config.ts-Datei hinzufügen.

Cache-Profile sind Objekte, die die folgenden Eigenschaften enthalten:

Die Eigenschaft "stale" unterscheidet sich von der Einstellung staleTimes, da sie speziell das clientseitige Router-Caching steuert. Während staleTimes eine globale Einstellung ist, die alle Instanzen von dynamischen und statischen Daten betrifft, ermöglicht die cacheLife-Konfiguration die Definition von "stale"-Zeiten auf Basis einzelner Funktionen oder Routen.

Gut zu wissen: Die Eigenschaft "stale" setzt nicht den Cache-control: max-age-Header. Sie steuert stattdessen den clientseitigen Router-Cache.

Beispiele

Definieren wiederverwendbarer Cache-Profile

Sie können ein wiederverwendbares Cache-Profil erstellen, indem Sie es in Ihrer next.config.ts-Datei definieren. Wählen Sie einen Namen, der zu Ihrem Anwendungsfall passt, und legen Sie Werte für die Eigenschaften stale, revalidate und expire fest. Sie können so viele benutzerdefinierte Cache-Profile erstellen, wie Sie benötigen. Jedes Profil kann über seinen Namen als Zeichenfolgenwert referenziert werden, der an die cacheLife-Funktion übergeben wird.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 Tage
        revalidate: 60 * 60 * 24, // 1 Tag
        expire: 60 * 60 * 24 * 14, // 14 Tage
      },
    },
  },
}

module.exports = nextConfig

Das obige Beispiel speichert für 14 Tage zwischen, prüft täglich auf Updates und lässt den Cache nach 14 Tagen ablaufen. Sie können dann auf dieses Profil in Ihrer gesamten Anwendung über seinen Namen verweisen:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

Überschreiben der Standard-Cache-Profile

Während die Standard-Cache-Profile eine nützliche Möglichkeit bieten, darüber nachzudenken, wie frisch oder veraltet ein bestimmter Teil des zwischengespeicherten Outputs sein kann, bevorzugen Sie möglicherweise andere benannte Profile, die besser mit den Caching-Strategien Ihrer Anwendung übereinstimmen.

Sie können die standardmäßigen benannten Cache-Profile überschreiben, indem Sie eine neue Konfiguration mit demselben Namen wie die Standardprofile erstellen.

Das folgende Beispiel zeigt, wie das Standard-Cache-Profil "days" überschrieben wird:

const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 Stunde
        revalidate: 900, // 15 Minuten
        expire: 86400, // 1 Tag
      },
    },
  },
}

module.exports = nextConfig

Definieren von Cache-Profilen inline

Für spezifische Anwendungsfälle können Sie ein benutzerdefiniertes Cache-Profil festlegen, indem Sie ein Objekt an die cacheLife-Funktion übergeben:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife({
    stale: 3600, // 1 Stunde
    revalidate: 900, // 15 Minuten
    expire: 86400, // 1 Tag
  })

  return <div>Page</div>
}

Dieses inline definierte Cache-Profil wird nur auf die Funktion oder Datei angewendet, in der es erstellt wurde. Wenn Sie dasselbe Profil in Ihrer gesamten Anwendung wiederverwenden möchten, können Sie die Konfiguration der cacheLife-Eigenschaft Ihrer next.config.ts-Datei hinzufügen.

Verschachtelte Verwendung von use cache und cacheLife

Wenn Sie mehrere Caching-Verhalten in derselben Route oder Komponentenstruktur definieren und die inneren Caches ihr eigenes cacheLife-Profil angeben, respektiert der äußere Cache die kürzeste Cache-Dauer unter ihnen. Dies gilt nur, wenn der äußere Cache kein eigenes explizites cacheLife-Profil definiert hat.

Wenn Sie beispielsweise die use cache-Direktive zu Ihrer Seite hinzufügen, ohne ein Cache-Profil anzugeben, wird das Standard-Cache-Profil implizit angewendet (cacheLife("default")). Wenn eine in die Seite importierte Komponente ebenfalls die use cache-Direktive mit ihrem eigenen Cache-Profil verwendet, werden die äußeren und inneren Cache-Profile verglichen, und die kürzeste in den Profilen festgelegte Dauer wird angewendet.

// Elternkomponente
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'

export async function ParentComponent() {
  'use cache'
  cacheLife('days')

  return (
    <div>
      <ChildComponent />
    </div>
  )
}

Und in einer separaten Datei haben wir die importierte Child-Komponente definiert:

// Child-Komponente
import { unstable_cacheLife as cacheLife } from 'next/cache'

export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>

  // Der Cache dieser Komponente respektiert das kürzere 'hours'-Profil
}