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
}

Rückgabewerte von getStaticPaths

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

paths

Der Schlüssel paths 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 mit der Seitenkomponente in pages/posts/[id].js generieren.

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

• 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, können Sie null, [], undefined oder false verwenden, um die Root-Route zu rendern. Wenn Sie z.B. 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 z.B. 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, was das Locale für den generierten Pfad konfiguriert.

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 Blogbeitrag pro Seite namens pages/posts/[id].js vor. Die Liste der Blogbeiträge wird von einem CMS abgerufen und von getStaticPaths zurückgegeben. Dann werden für jede Seite die Beitragsdaten mit getStaticProps vom CMS abgerufen.

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

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

  // Pfade basierend auf Beiträgen für das Vor-Rendern ermitteln
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // Nur diese Pfade werden zur Build-Zeit vorgerendert.
  // { fallback: false } bedeutet, dass andere Routen 404 ergeben.
  return { paths, fallback: false }
}

// Wird auch 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 liefert 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 eine Seite mit fallback: true über next/link oder next/router (clientseitig) aufgerufen wird, liefert 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. Dies umfasst die Ausführung von getStaticProps.
• Nach Abschluss erhält der Browser den JSON für den generierten Pfad. Dieser wird verwendet, um die Seite automatisch mit den erforderlichen Props zu rendern. Aus Nutzersicht 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 Anwendung 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 vorrendern möchten, 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 noch nicht generierte Seite anfordert, sieht der Nutzer die Seite mit einem Ladeindikator oder einer Skelettkomponente.

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

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

fallback: true aktualisiert nicht generierte Seiten. 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, ähnlich wie 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 aus und liefert das generierte HTML.
• Nach Abschluss erhält der Browser das HTML für den generierten Pfad. Aus Nutzersicht 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 sind leer.
• Mit dem Router können Sie erkennen, ob der Fallback gerendert wird: router.isFallback ist true.

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>Loading...</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 aktivieren
    // z.B.: `/posts/3`
    fallback: true,
  }
}

// Wird auch 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