getStaticPaths

Wenn Sie eine Funktion namens getStaticPaths aus einer Seite exportieren, die Dynamische Routen verwendet, wird Next.js alle von getStaticPaths angegebenen Pfade statisch vor-rendern.

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // Siehe Abschnitt "paths" unten
    ],
    fallback: true, // false oder "blocking"
  }
}) satisfies GetStaticPaths

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

export async function getStaticPaths() {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // Siehe Abschnitt "paths" unten
    ],
    fallback: true, // false oder "blocking"
  }
}

export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

Rückgabewerte von getStaticPaths

Die Funktion getStaticPaths sollte ein Objekt mit den folgenden erforderlichen Eigenschaften zurückgeben:

paths

Der paths-Schlüssel bestimmt, welche Pfade vorgerendert werden. Angenommen, Sie haben eine Seite mit Dynamischen Routen namens pages/posts/[id].js. Wenn Sie getStaticPaths von dieser Seite exportieren und Folgendes für paths zurückgeben:

return {
  paths: [
    { params: { id: '1' }},
    {
      params: { id: '2' },
      // Bei konfigurierter i18n kann auch das Locale für den Pfad zurückgegeben werden
      locale: "en",
    },
  ],
  fallback: ...
}

Dann wird Next.js während next build die Seiten /posts/1 und /posts/2 statisch generieren, indem es die Seitenkomponente in pages/posts/[id].js verwendet.

Die Werte für jedes params-Objekt müssen den Parametern entsprechen, die im Seitennamen verwendet werden:

• Wenn der Seitenname pages/posts/[postId]/[commentId] lautet, sollte params postId und commentId enthalten.
• Wenn der Seitenname Catch-all-Routen wie pages/[...slug] verwendet, sollte params slug enthalten (was ein Array ist). Wenn dieses Array ['hello', 'world'] ist, generiert Next.js die Seite statisch unter /hello/world.
• Wenn die Seite eine optionale Catch-all-Route verwendet, verwenden Sie null, [], undefined oder false, um die Root-Route zu rendern. Wenn Sie beispielsweise slug: false für pages/[[...slug]] angeben, generiert Next.js die Seite / statisch.

Die params-Strings sind case-sensitive und sollten idealerweise normalisiert werden, um sicherzustellen, dass die Pfade korrekt generiert werden. Wenn beispielsweise WoRLD für einen Parameter zurückgegeben wird, wird dies nur übereinstimmen, wenn WoRLD der tatsächlich besuchte Pfad ist, nicht world oder World.

Unabhängig vom params-Objekt kann ein locale-Feld zurückgegeben werden, wenn i18n konfiguriert ist, wodurch das Locale für den generierten Pfad konfiguriert wird.

fallback: false

Wenn fallback false ist, führt jeder Pfad, der nicht von getStaticPaths zurückgegeben wird, zu einer 404-Seite.

Wenn next build ausgeführt wird, prüft Next.js, ob getStaticPaths fallback: false zurückgegeben hat, und baut dann nur die von getStaticPaths zurückgegebenen Pfade. Diese Option ist nützlich, wenn Sie eine kleine Anzahl von Pfaden erstellen müssen oder neue Seitendaten nicht häufig hinzugefügt werden. Wenn Sie feststellen, dass Sie mehr Pfade hinzufügen müssen und fallback: false haben, müssen Sie next build erneut ausführen, damit die neuen Pfade generiert werden können.

Das folgende Beispiel rendert einen Blog-Beitrag pro Seite namens pages/posts/[id].js vor. Die Liste der Blog-Beiträge wird von einem CMS abgerufen und von getStaticPaths zurückgegeben. Dann werden für jede Seite die Beitragsdaten vom CMS mit getStaticProps abgerufen.

function Post({ post }) {
  // Beitrag rendern...
}

// Diese Funktion wird zur Build-Zeit aufgerufen
export async function getStaticPaths() {
  // Externen API-Endpunkt aufrufen, um Beiträge abzurufen
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Pfade basierend auf Beiträgen erhalten, die wir vor-rendern wollen
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // Wir werden nur diese Pfade zur Build-Zeit vor-rendern.
  // { fallback: false } bedeutet, dass andere Routen zu 404 führen.
  return { paths, fallback: false }
}

// Diese Funktion wird ebenfalls zur Build-Zeit aufgerufen
export async function getStaticProps({ params }) {
  // params enthält die Beitrags-ID.
  // Wenn die Route z.B. /posts/1 ist, dann ist params.id 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Beitragsdaten via Props an die Seite übergeben
  return { props: { post } }
}

export default Post

fallback: true

Wenn fallback true ist, ändert sich das Verhalten von getStaticProps wie folgt:

• Die von getStaticPaths zurückgegebenen Pfade werden zur Build-Zeit von getStaticProps zu HTML gerendert.
• Pfade, die zur Build-Zeit nicht generiert wurden, führen nicht zu einer 404-Seite. Stattdessen serviert Next.js beim ersten Aufruf eines solchen Pfads eine "Fallback"-Version der Seite. Webcrawler wie Google erhalten keinen Fallback, sondern der Pfad verhält sich wie bei fallback: 'blocking'.
• Wenn auf eine Seite mit fallback: true über next/link oder next/router (clientseitig) navigiert wird, serviert Next.js keinen Fallback, sondern die Seite verhält sich wie bei fallback: 'blocking'.
• Im Hintergrund generiert Next.js den angeforderten Pfad statisch als HTML und JSON. Dazu gehört die Ausführung von getStaticProps.
• Wenn dies abgeschlossen ist, erhält der Browser das JSON für den generierten Pfad. Dies wird verwendet, um die Seite automatisch mit den erforderlichen Props zu rendern. Aus Benutzersicht wird die Seite von der Fallback-Seite zur vollständigen Seite gewechselt.
• Gleichzeitig fügt Next.js diesen Pfad zur Liste der vorgerenderten Seiten hinzu. Nachfolgende Anfragen an denselben Pfad liefern die generierte Seite, wie andere zur Build-Zeit vorgerenderte Seiten.

Gut zu wissen: fallback: true wird nicht unterstützt, wenn output: 'export' verwendet wird.

Wann ist fallback: true nützlich?

fallback: true ist nützlich, wenn Ihre App eine sehr große Anzahl statischer Seiten hat, die von Daten abhängen (z.B. ein sehr großer E-Commerce-Shop). Wenn Sie alle Produktseiten vor-rendern wollen, würden die Builds sehr lange dauern.

Stattdessen können Sie eine kleine Teilmenge der Seiten statisch generieren und fallback: true für den Rest verwenden. Wenn jemand eine Seite anfordert, die noch nicht generiert wurde, sieht der Benutzer die Seite mit einem Ladeindikator oder einer Skelettkomponente.

Kurz darauf wird getStaticProps fertiggestellt und die Seite mit den angeforderten Daten gerendert. Ab diesem Zeitpunkt erhält jeder, der dieselbe Seite anfordert, die statisch vorgerenderte Seite.

Dies stellt sicher, dass Benutzer immer eine schnelle Erfahrung haben, während schnelle Builds und die Vorteile der statischen Generierung erhalten bleiben.

fallback: true wird generierte Seiten nicht aktualisieren. Dafür siehe Inkrementelle Statische Regeneration.

fallback: 'blocking'

Wenn fallback 'blocking' ist, warten neue Pfade, die nicht von getStaticPaths zurückgegeben werden, auf die Generierung des HTML, identisch zu SSR (daher blocking), und werden dann für zukünftige Anfragen zwischengespeichert, sodass dies nur einmal pro Pfad geschieht.

getStaticProps verhält sich wie folgt:

• Die von getStaticPaths zurückgegebenen Pfade werden zur Build-Zeit von getStaticProps zu HTML gerendert.
• Pfade, die zur Build-Zeit nicht generiert wurden, führen nicht zu einer 404-Seite. Stattdessen führt Next.js beim ersten Aufruf SSR durch und gibt das generierte HTML zurück.
• Wenn dies abgeschlossen ist, erhält der Browser das HTML für den generierten Pfad. Aus Benutzersicht wechselt es von "der Browser fordert die Seite an" zu "die vollständige Seite ist geladen". Es gibt keinen flüchtigen Lade-/Fallback-Zustand.
• Gleichzeitig fügt Next.js diesen Pfad zur Liste der vorgerenderten Seiten hinzu. Nachfolgende Anfragen an denselben Pfad liefern die generierte Seite, wie andere zur Build-Zeit vorgerenderte Seiten.

fallback: 'blocking' aktualisiert generierte Seiten standardmäßig nicht. Um generierte Seiten zu aktualisieren, verwenden Sie Inkrementelle Statische Regeneration in Verbindung mit fallback: 'blocking'.

Gut zu wissen: fallback: 'blocking' wird nicht unterstützt, wenn output: 'export' verwendet wird.

Fallback-Seiten

In der "Fallback"-Version einer Seite:

• Die Props der Seite werden leer sein.
• Mit dem Router können Sie erkennen, ob der Fallback gerendert wird: router.isFallback wird true sein.

Das folgende Beispiel zeigt die Verwendung von isFallback:

import { useRouter } from 'next/router'

function Post({ post }) {
  const router = useRouter()

  // Wenn die Seite noch nicht generiert wurde, wird dies angezeigt,
  // bis getStaticProps() fertig ist
  if (router.isFallback) {
    return <div>Laden...</div>
  }

  // Beitrag rendern...
}

// Diese Funktion wird zur Build-Zeit aufgerufen
export async function getStaticPaths() {
  return {
    // Nur `/posts/1` und `/posts/2` werden zur Build-Zeit generiert
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    // Statische Generierung zusätzlicher Seiten ermöglichen
    // Zum Beispiel: `/posts/3`
    fallback: true,
  }
}

// Diese Funktion wird ebenfalls zur Build-Zeit aufgerufen
export async function getStaticProps({ params }) {
  // params enthält die Beitrags-ID.
  // Wenn die Route z.B. /posts/1 ist, dann ist params.id 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Beitragsdaten via Props an die Seite übergeben
  return {
    props: { post },
    // Beitrag höchstens einmal pro Sekunde neu generieren,
    // wenn eine Anfrage eingeht
    revalidate: 1,
  }
}

export default Post

Versionsverlauf