getStaticPaths

Wenn von einer Seite, die dynamische Routen verwendet, eine Funktion namens getStaticPaths exportiert wird, wird Next.js alle von getStaticPaths angegebenen Pfade statisch vorrendern.

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 den "paths"-Abschnitt 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 getStaticPaths-Funktion sollte ein Objekt mit den folgenden erforderlichen Eigenschaften zurückgeben:

paths

Der paths-Schlüssel bestimmt, welche Pfade vorgerendert werden. Nehmen wir zum Beispiel an, 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 konfiguriertem i18n kann auch das Gebietsschema für den Pfad zurückgegeben werden
      locale: "en",
    },
  ],
  fallback: ...
}

Dann wird Next.js während next build statisch /posts/1 und /posts/2 mit der Seitenkomponente in pages/posts/[id].js generieren.

Der Wert für jedes params-Objekt muss mit den Parametern übereinstimmen, die im Seitennamen verwendet werden:

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

Die params-Strings sind groß-/kleinschreibungsabhängig und sollten idealerweise normalisiert werden, um eine korrekte Pfadgenerierung zu gewährleisten. Wenn beispielsweise WoRLD für einen Parameter zurückgegeben wird, wird er nur übereinstimmen, wenn WoRLD der tatsächlich besuchte Pfad ist, nicht world oder World.

Unabhängig vom params-Objekt kann bei konfiguriertem i18n ein locale-Feld zurückgegeben werden, das das Gebietsschema für den generierten Pfad konfiguriert.

fallback: false

Wenn fallback false ist, führen alle Pfade, die nicht von getStaticPaths zurückgegeben werden, zu einer 404-Seite.

Wenn next build ausgeführt wird, prüft Next.js, ob getStaticPaths fallback: false zurückgegeben hat, und generiert dann nur die von getStaticPaths zurückgegebenen Pfade. Diese Option ist nützlich, wenn Sie nur eine kleine Anzahl von Pfaden erstellen müssen oder keine neuen Seitendaten häufig hinzugefügt werden. Wenn Sie feststellen, dass Sie weitere 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. Anschließend ruft es für jede Seite die Beitragsdaten von einem CMS mit getStaticProps ab.

function Post({ post }) {
  // Beitrag rendern...
}
 
// Diese Funktion wird zur Buildzeit aufgerufen
export async function getStaticPaths() {
  // Eine externe API aufrufen, um Beiträge zu erhalten
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // Die Pfade bestimmen, die wir basierend auf den Beiträgen vorrendern möchten
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))
 
  // Wir werden nur diese Pfade zur Buildzeit vorrendern.
  // { fallback: false } bedeutet, dass andere Routen 404 sein sollen.
  return { paths, fallback: false }
}
 
// Dies wird auch zur Buildzeit aufgerufen
export async function getStaticProps({ params }) {
  // params enthält die Beitrags-`id`.
  // Wenn die Route wie /posts/1 aussieht, ist params.id gleich 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()
 
  // Beitragsdaten über 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 Buildzeit von getStaticProps in HTML gerendert.
• Die Pfade, die zur Buildzeit nicht generiert wurden, führen nicht zu einer 404-Seite. Stattdessen wird Next.js bei der ersten Anfrage an einen solchen Pfad eine "Fallback"-Version der Seite bereitstellen. Web-Crawler wie Google erhalten kein Fallback und das Verhalten entspricht fallback: 'blocking'.
• Wenn eine Seite mit fallback: true über next/link oder next/router (clientseitig) aufgerufen wird, wird Next.js kein Fallback bereitstellen, und die Seite verhält sich wie fallback: 'blocking'.
• Im Hintergrund generiert Next.js statisch den angeforderten Pfad-HTML und JSON. Dies beinhaltet die Ausführung von getStaticProps.
• Sobald dies abgeschlossen ist, 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 Benutzerperspektive 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 werden die generierte Seite bereitstellen, wie andere Seiten, die zur Buildzeit vorgerendert wurden.

Hinweis: 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 von 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 einer Ladeindikator- oder Skelett-Komponente.

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

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

fallback: true wird generierte Seiten nicht aktualisieren. Dafür werfen Sie einen Blick auf Inkrementelle Statische Regenerierung.

fallback: 'blocking'

Wenn fallback 'blocking' ist, warten neue Pfade, die nicht von getStaticPaths zurückgegeben werden, bis die HTML generiert sind (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 Buildzeit von getStaticProps zu HTML gerendert.
• Die Pfade, die zur Buildzeit nicht generiert wurden, führen nicht zu einer 404-Seite. Stattdessen wird Next.js die Seite bei der ersten Anfrage serverseitig rendern und das generierte HTML zurückgeben.
• Nach Abschluss empfängt der Browser das HTML für den generierten Pfad. Aus Benutzersicht wechselt dies von „der Browser fordert die Seite an" zu „die vollständige Seite ist geladen". Es gibt keinen Ladeübergangszustand.
• Gleichzeitig fügt Next.js diesen Pfad zur Liste der vorgerenderten Seiten hinzu. Nachfolgende Anfragen an denselben Pfad liefern die generierte Seite, wie andere Seiten, die zur Buildzeit vorgerendert wurden.

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

Hinweis: 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.
• Über den Router können Sie erkennen, ob das 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
  // zunächst angezeigt, bis getStaticProps() abgeschlossen ist
  if (router.isFallback) {
    return <div>Lädt...</div>
  }
 
  // Post rendern...
}
 
// Diese Funktion wird zur Buildzeit aufgerufen
export async function getStaticPaths() {
  return {
    // Nur `/posts/1` und `/posts/2` werden zur Buildzeit generiert
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    // Statisches Generieren zusätzlicher Seiten aktivieren
    // Zum Beispiel: `/posts/3`
    fallback: true,
  }
}
 
// Dies wird auch zur Buildzeit aufgerufen
export async function getStaticProps({ params }) {
  // params enthält die Post-`id`.
  // Wenn die Route wie /posts/1 aussieht, ist params.id 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()
 
  // Übergabe der Post-Daten an die Seite über Props
  return {
    props: { post },
    // Post höchstens einmal pro Sekunde neu generieren,
    // wenn eine Anfrage eingeht
    revalidate: 1,
  }
}
 
export default Post

Versionshistorie