getStaticProps

Wenn Sie eine Funktion namens getStaticProps (Static Site Generation) von einer Seite exportieren, wird Next.js diese Seite zur Buildzeit mit den von getStaticProps zurückgegebenen Props vorrendern.

import type { InferGetStaticPropsType, GetStaticProps } from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
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
}

Beachten Sie, dass unabhängig vom Rendering-Typ alle props an die Seitenkomponente übergeben werden und auf der Clientseite im initialen HTML angezeigt werden können. Dies dient dazu, dass die Seite korrekt hydratisiert werden kann. Stellen Sie sicher, dass Sie keine sensiblen Informationen in props übergeben, die nicht auf dem Client verfügbar sein sollten.

Die getStaticProps API-Referenz behandelt alle Parameter und Props, die mit getStaticProps verwendet werden können.

Wann sollte ich getStaticProps verwenden?

Sie sollten getStaticProps verwenden, wenn:

• Die zur Darstellung der Seite erforderlichen Daten zur Buildzeit vor der Anfrage eines Benutzers verfügbar sind
• Die Daten aus einem Headless-CMS stammen
• Die Seite vorgerendert (für SEO) und sehr schnell sein muss — getStaticProps generiert HTML- und JSON-Dateien, die beide von einem CDN zur Leistungsoptimierung zwischengespeichert werden können
• Die Daten öffentlich zwischengespeichert werden können (nicht benutzerspezifisch). Diese Bedingung kann in bestimmten spezifischen Situationen durch eine Middleware zum Umschreiben des Pfads umgangen werden.

Wann wird getStaticProps ausgeführt

getStaticProps wird immer auf dem Server und niemals auf dem Client ausgeführt. Sie können überprüfen, ob Code, der in getStaticProps geschrieben wurde, aus dem Client-seitigen Bundle entfernt wurde mit diesem Tool.

• getStaticProps wird immer während next build 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
• getStaticProps wird im Hintergrund ausgeführt, wenn revalidate verwendet wird
• getStaticProps wird bei Bedarf im Hintergrund ausgeführt, wenn revalidate() verwendet wird

In Kombination mit Inkrementeller Statischer Regenerierung wird getStaticProps im Hintergrund ausgeführt, während die veraltete Seite neu validiert wird und die aktuelle Seite an den Browser ausgeliefert wird.

getStaticProps hat keinen Zugriff auf die eingehende Anfrage (wie Abfrageparameter oder HTTP-Header), da es statisches HTML generiert. Wenn Sie Zugriff auf die Anfrage für Ihre Seite benötigen, erwägen Sie die Verwendung von Middleware zusätzlich zu getStaticProps.

Verwendung von getStaticProps zum Abrufen von Daten aus einem CMS

Das folgende Beispiel zeigt, wie Sie eine Liste von Blogbeiträgen aus einem CMS abrufen können.

// Posts werden zur Buildzeit durch getStaticProps() befüllt
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
 
// Diese Funktion wird zur Buildzeit auf der Serverseite aufgerufen.
// Sie wird nicht auf der Clientseite aufgerufen, sodass Sie sogar
// direkte Datenbankabfragen durchführen können.
export async function getStaticProps() {
  // Eine externe API aufrufen, um Posts zu erhalten.
  // Sie können eine beliebige Daten-Fetching-Bibliothek verwenden
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // Durch die Rückgabe von { props: { posts } } erhält die Blog-Komponente
  // `posts` als Prop zur Buildzeit
  return {
    props: {
      posts,
    },
  }
}

Die getStaticProps API-Referenz behandelt alle Parameter und Props, die mit getStaticProps verwendet werden können.

Serverseitigen Code direkt schreiben

Da getStaticProps nur serverseitig ausgeführt wird, wird es niemals auf der Clientseite ausgeführt. Es wird nicht einmal in das JS-Bundle für den Browser aufgenommen, sodass Sie direkte Datenbankabfragen durchführen können, ohne sie an Browser zu senden.

Das bedeutet, dass Sie anstatt eine API-Route von getStaticProps abzurufen (die selbst Daten aus einer externen Quelle abruft), den serverseitigen Code direkt in getStaticProps schreiben können.

Betrachten Sie das folgende Beispiel. Eine API-Route wird verwendet, um Daten aus einem CMS abzurufen. Diese API-Route wird dann direkt von getStaticProps aufgerufen. Dies erzeugt einen zusätzlichen Aufruf und reduziert die Leistung. Stattdessen kann die Logik zum Abrufen der Daten aus dem CMS durch Verwendung eines lib/-Verzeichnisses geteilt werden. Anschließend kann sie mit getStaticProps geteilt werden.

// Die folgende Funktion wird 
// mit getStaticProps und API-Routen
// aus einem `lib/`-Verzeichnis geteilt
export async function loadPosts() {
  // Eine externe API aufrufen, um Posts zu erhalten
  const res = await fetch('https://.../posts/')
  const data = await res.json()
 
  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'
 
// Diese Funktion läuft nur auf der Serverseite
export async function getStaticProps() {
  // Anstatt Ihre `/api`-Route abzurufen, können Sie die gleiche
  // Funktion direkt in `getStaticProps` aufrufen
  const posts = await loadPosts()
 
  // Zurückgegebene Props werden an die Seitenkomponente übergeben
  return { props: { posts } }
}

Alternativ kann die fetch() API direkt in getStaticProps verwendet werden, um Daten abzurufen, wenn Sie keine API-Routen zum Datenabruf verwenden.

Um zu überprüfen, was Next.js aus dem Client-seitigen Bundle eliminiert, können Sie das next-code-elimination-Tool verwenden.

Statisch generiert HTML und JSON

Wenn eine Seite mit getStaticProps zur Buildzeit vorgerendert wird, generiert Next.js zusätzlich zur Seiten-HTML-Datei eine JSON-Datei, die das Ergebnis der Ausführung von getStaticProps enthält.

Diese JSON-Datei wird für das Client-seitige Routing über next/link oder next/router verwendet. Wenn Sie zu einer Seite navigieren, die mit getStaticProps vorgerendert wurde, ruft Next.js diese JSON-Datei ab (die zur Build-Zeit vorberechnet wurde) und verwendet sie als Props für die Seitenkomponente. Das bedeutet, dass Client-seitige Seitenübergänge getStaticProps nicht aufrufen, da nur die exportierte JSON verwendet wird.

Bei Verwendung von Incremental Static Generation wird getStaticProps im Hintergrund ausgeführt, um die für die Client-seitige Navigation benötigte JSON zu generieren. Sie können dies in Form mehrerer Anfragen für dieselbe Seite sehen, jedoch ist dies beabsichtigt und hat keine Auswirkungen auf die Endbenutzer-Performance.

Wo kann ich getStaticProps verwenden

getStaticProps kann nur von einer Seite exportiert werden. Es kann nicht aus Nicht-Seiten-Dateien, _app, _document oder _error exportiert werden.

Einer der Gründe für diese Einschränkung ist, dass React alle erforderlichen Daten benötigt, bevor die Seite gerendert wird.

Außerdem müssen Sie getStaticProps als eigenständige Funktion exportieren - es funktioniert nicht, wenn Sie getStaticProps als Eigenschaft der Seitenkomponente hinzufügen.

Hinweis: Wenn Sie eine benutzerdefinierte App erstellt haben, stellen Sie sicher, dass Sie die pageProps an die Seitenkomponente übergeben, wie im verlinkten Dokument gezeigt, andernfalls sind die Props leer.

Wird in der Entwicklung bei jeder Anfrage ausgeführt

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

Vorschau-Modus

Sie können die statische Generierung vorübergehend umgehen und die Seite stattdessen zur Anforderungszeit anstatt zur Build-Zeit rendern, indem Sie den Vorschau-Modus verwenden. Beispielsweise könnten Sie ein Headless-CMS verwenden und Entwürfe vor der Veröffentlichung vorschauen wollen.