getStaticPaths

Wenn eine Seite Dynamische Routen verwendet und getStaticProps einsetzt, muss sie eine Liste von Pfaden definieren, die statisch generiert werden sollen.

Wenn Sie eine Funktion namens getStaticPaths (Static Site Generation) aus einer Seite mit dynamischen Routen exportieren, wird Next.js alle von getStaticPaths angegebenen Pfade statisch vorab 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
}

Die getStaticPaths API-Referenz deckt alle Parameter und Props ab, die mit getStaticPaths verwendet werden können.

Wann sollte ich getStaticPaths verwenden?

Sie sollten getStaticPaths verwenden, wenn Sie Seiten mit dynamischen Routen statisch vorab rendern und:

Die Daten von einem Headless-CMS stammen
Die Daten aus einer Datenbank kommen
Die Daten aus dem Dateisystem stammen
Die Daten öffentlich zwischengespeichert werden können (nicht benutzerspezifisch)
Die Seite für SEO-Zwecke vorgerendert werden muss und sehr schnell sein soll — getStaticProps generiert HTML- und JSON-Dateien, die beide von einem CDN für bessere Performance zwischengespeichert werden können

Wann wird getStaticPaths ausgeführt

getStaticPaths wird nur während des Builds in der Produktionsumgebung ausgeführt und nicht zur Laufzeit. Sie können überprüfen, dass der Code innerhalb von getStaticPaths aus dem Client-seitigen Bundle entfernt wurde, mit diesem Tool.

Wie wird getStaticProps in Bezug auf getStaticPaths ausgeführt

getStaticProps wird während next build für alle paths ausgeführt, die während des Builds zurückgegeben werden
getStaticProps wird im Hintergrund ausgeführt, wenn fallback: true verwendet wird
getStaticProps wird vor dem initialen Rendering aufgerufen, wenn fallback: blocking verwendet wird

Wo kann ich getStaticPaths verwenden

getStaticPaths muss mit getStaticProps verwendet werden
Sie können getStaticPaths nicht mit getServerSideProps verwenden
Sie können getStaticPaths aus einer Dynamischen Route exportieren, die auch getStaticProps verwendet
Sie können getStaticPaths nicht aus einer Nicht-Seiten-Datei exportieren (z.B. aus Ihrem components-Ordner)
Sie müssen getStaticPaths als eigenständige Funktion exportieren und nicht als Eigenschaft der Seitenkomponente

Wird bei jeder Anfrage in der Entwicklung ausgeführt

In der Entwicklung (next dev) wird getStaticPaths bei jeder Anfrage aufgerufen.

Pfade bei Bedarf generieren

getStaticPaths ermöglicht es Ihnen, zu steuern, welche Seiten während des Builds generiert werden, anstatt bei Bedarf mit fallback. Die Generierung mehrerer Seiten während eines Builds führt zu langsameren Builds.

Sie können die Generierung aller Seiten bei Bedarf verzögern, indem Sie ein leeres Array für paths zurückgeben. Dies kann besonders hilfreich sein, wenn Sie Ihre Next.js-Anwendung in mehreren Umgebungen bereitstellen. Zum Beispiel können Sie schnellere Builds erreichen, indem Sie alle Seiten für Vorschauen bei Bedarf generieren (aber nicht für Produktions-Builds). Dies ist hilfreich für Websites mit Hunderten/Tausenden von statischen Seiten.

pages/posts/[id].js

export async function getStaticPaths() {
  // Wenn dies wahr ist (in Vorschauumgebungen), werden keine
  // statischen Seiten vorab gerendert
  // (schnellere Builds, aber langsamere initiale Seitenladezeit)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // Externe API aufrufen, um Posts abzurufen
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Pfade basierend auf Posts bestimmen, die vorab gerendert werden sollen
  // In Produktionsumgebungen alle Seiten vorab rendern
  // (langsamere Builds, aber schnellere initiale Seitenladezeit)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } bedeutet, dass andere Routen 404 zurückgeben sollten
  return { paths, fallback: false }
}