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 durch 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
}

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 während der Laufzeit. Sie können überprüfen, ob der Code innerhalb von getStaticPaths aus dem Client-Bundle entfernt wurde, mit diesem Tool.

Wie wird getStaticProps in Bezug auf getStaticPaths ausgeführt

• getStaticProps wird während next build für alle während des Builds zurückgegebenen paths ausgeführt
• 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. 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 Entwicklungsumgebung (next dev) wird getStaticPaths bei jeder Anfrage aufgerufen.

Generierung von Pfaden bei Bedarf

getStaticPaths ermöglicht es Ihnen, zu steuern, welche Seiten während des Builds generiert werden, anstatt bei Bedarf mit fallback. Die Generierung von mehr 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 nützlich für Websites mit hunderten/tausenden statischen Seiten.

export async function getStaticPaths() {
  // Wenn dies wahr ist (in Vorschauumgebungen), werden keine
  // statischen Seiten vorgerendert
  // (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 ermitteln, die vorgerendert werden sollen
  // In Produktionsumgebungen alle Seiten vorrendern
  // (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 }
}