Implementierung von Incremental Static Regeneration (ISR)

Incremental Static Regeneration (ISR) ermöglicht Ihnen:

• Statische Inhalte ohne Neubau der gesamten Website zu aktualisieren
• Serverlast zu reduzieren durch Ausliefern vorgerenderter, statischer Seiten für die meisten Anfragen
• Sicherzustellen, dass korrekte cache-control-Header automatisch zu Seiten hinzugefügt werden
• Große Mengen von Inhaltsseiten ohne lange next build-Zeiten zu verwalten

Hier ist ein minimales Beispiel:

interface Post {
  id: string
  title: string
  content: string
}

// Next.js wird den Cache ungültig machen, wenn eine
// Anfrage eingeht, maximal einmal alle 60 Sekunden.
export const revalidate = 60

// Wir werden nur die Parameter aus `generateStaticParams` zur Build-Zeit vorrendern.
// Wenn eine Anfrage für einen Pfad kommt, der nicht generiert wurde,
// wird Next.js die Seite bedarfsgerecht serverseitig rendern.
export const dynamicParams = true // oder false, um bei unbekannten Pfaden 404 zurückzugeben

export async function generateStaticParams() {
  const posts: Post[] = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )
  return posts.map((post) => ({
    id: String(post.id),
  }))
}

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post: Post = await fetch(`https://api.vercel.app/blog/${id}`).then(
    (res) => res.json()
  )
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  )
}

So funktioniert dieses Beispiel:

1. Während next build werden alle bekannten Blogbeiträge generiert (in diesem Beispiel gibt es 25)
2. Alle Anfragen an diese Seiten (z.B. /blog/1) werden zwischengespeichert und sind sofort verfügbar
3. Nach 60 Sekunden zeigt die nächste Anfrage weiterhin die zwischengespeicherte (veraltete) Seite
4. Der Cache wird ungültig gemacht und eine neue Version der Seite beginnt im Hintergrund zu generieren
5. Nach erfolgreicher Generierung zeigt Next.js die aktualisierte Seite an und speichert sie im Cache
6. Wenn /blog/26 angefragt wird, generiert Next.js diese Seite bedarfsgerecht und speichert sie im Cache

Referenz

Routensegment-Konfiguration

• revalidate
• dynamicParams

Funktionen

• revalidatePath
• revalidateTag

Beispiele

Zeitbasierte Revalidierung

Dies holt eine Liste von Blogbeiträgen auf /blog ab und zeigt sie an. Nach einer Stunde wird der Cache für diese Seite bei der nächsten Anfrage ungültig gemacht. Dann wird im Hintergrund eine neue Version der Seite mit den neuesten Blogbeiträgen generiert.

interface Post {
  id: string
  title: string
  content: string
}

export const revalidate = 3600 // jede Stunde ungültig machen

export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts: Post[] = await data.json()
  return (
    <main>
      <h1>Blogbeiträge</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </main>
  )
}

Wir empfehlen, eine hohe Revalidierungszeit zu setzen. Zum Beispiel 1 Stunde statt 1 Sekunde. Wenn Sie mehr Präzision benötigen, sollten Sie On-Demand-Revalidierung in Betracht ziehen. Wenn Sie Echtzeitdaten benötigen, sollten Sie zu dynamischem Rendering wechseln.

On-Demand-Revalidierung mit revalidatePath

Für eine präzisere Methode der Revalidierung können Sie Seiten bedarfsgerecht mit der Funktion revalidatePath ungültig machen.

Zum Beispiel würde diese Server Action nach dem Hinzufügen eines neuen Beitrags aufgerufen werden. Unabhängig davon, wie Sie Ihre Daten in Ihrer Server-Komponente abrufen, entweder mit fetch oder durch Verbindung zu einer Datenbank, wird dies den Cache für die gesamte Route löschen und der Server-Komponente ermöglichen, frische Daten abzurufen.

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost() {
  // Macht die /posts-Route im Cache ungültig
  revalidatePath('/posts')
}

Demo ansehen und Quellcode erkunden.

On-Demand-Revalidierung mit revalidateTag

Für die meisten Anwendungsfälle ist es besser, ganze Pfade zu revalidieren. Wenn Sie feinere Kontrolle benötigen, können Sie die Funktion revalidateTag verwenden. Zum Beispiel können Sie einzelne fetch-Aufrufe taggen:

export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog', {
    next: { tags: ['posts'] },
  })
  const posts = await data.json()
  // ...
}

Wenn Sie ein ORM verwenden oder eine Datenbank verbinden, können Sie unstable_cache nutzen:

import { unstable_cache } from 'next/cache'
import { db, posts } from '@/lib/db'

const getCachedPosts = unstable_cache(
  async () => {
    return await db.select().from(posts)
  },
  ['posts'],
  { revalidate: 3600, tags: ['posts'] }
)

export default async function Page() {
  const posts = getCachedPosts()
  // ...
}

Sie können dann revalidateTag in einer Server Action oder einem Route Handler verwenden:

'use server'

import { revalidateTag } from 'next/cache'

export async function createPost() {
  // Macht alle mit 'posts' getaggten Daten im Cache ungültig
  revalidateTag('posts')
}

Behandlung unbehandelter Ausnahmen

Wenn ein Fehler beim Versuch auftritt, Daten zu revalidieren, werden die zuletzt erfolgreich generierten Daten weiterhin aus dem Cache bereitgestellt. Bei der nächsten nachfolgenden Anfrage wird Next.js den Revalidierungsversuch wiederholen. Mehr über Fehlerbehandlung erfahren.

Anpassung des Cache-Speicherorts

Sie können den Cache-Speicherort von Next.js konfigurieren, wenn Sie zwischengespeicherte Seiten und Daten in dauerhaften Speicher persistieren oder den Cache über mehrere Container oder Instanzen Ihrer Next.js-Anwendung hinweg teilen möchten. Mehr erfahren.

Problembehandlung

Debuggen von zwischengespeicherten Daten in der lokalen Entwicklung

Wenn Sie die fetch-API verwenden, können Sie zusätzliche Protokollierung hinzufügen, um zu verstehen, welche Anfragen zwischengespeichert oder nicht zwischengespeichert sind. Mehr über die logging-Option erfahren.

module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
}

Überprüfung des korrekten Produktionsverhaltens

Um zu überprüfen, ob Ihre Seiten in der Produktion korrekt zwischengespeichert und revalidiert werden, können Sie lokal testen, indem Sie next build und dann next start ausführen, um den Next.js-Produktionsserver zu starten.

Dadurch können Sie das ISR-Verhalten (Incremental Static Regeneration) testen, wie es in einer Produktionsumgebung funktionieren würde. Für weitere Debugging-Zwecke fügen Sie die folgende Umgebungsvariable zu Ihrer .env-Datei hinzu:

NEXT_PRIVATE_DEBUG_CACHE=1

Dies führt dazu, dass der Next.js-Server ISR-Cache-Treffer und -Fehlschläge in der Konsole protokolliert. Sie können die Ausgabe untersuchen, um zu sehen, welche Seiten während next build generiert werden und wie Seiten aktualisiert werden, wenn Pfade bedarfsgesteuert aufgerufen werden.

Einschränkungen

• ISR wird nur unterstützt, wenn die Node.js-Laufzeitumgebung (Standard) verwendet wird.
• ISR wird nicht unterstützt, wenn ein Statischer Export erstellt wird.
• Wenn Sie mehrere fetch-Anfragen in einer statisch gerenderten Route haben und jede eine unterschiedliche revalidate-Frequenz aufweist, wird die niedrigste Zeit für ISR verwendet. Diese Revalidate-Frequenzen werden jedoch weiterhin vom Daten-Cache berücksichtigt.
• Wenn eine der fetch-Anfragen in einer Route eine revalidate-Zeit von 0 oder ein explizites no-store aufweist, wird die Route dynamisch gerendert.
• Middleware wird nicht für bedarfsgesteuerte ISR-Anfragen ausgeführt, was bedeutet, dass Pfadumleitungen oder Logik in der Middleware nicht angewendet werden. Stellen Sie sicher, dass Sie den exakten Pfad revalidieren. Zum Beispiel /post/1 anstelle eines umgeleiteten /post-1.

Plattformunterstützung

Erfahren Sie, wie Sie ISR konfigurieren, wenn Sie Next.js selbst hosten.

Versionsverlauf