getStaticProps

Wenn Sie eine Funktion namens getStaticProps (Static Site Generation) von einer Seite exportieren, wird Next.js diese Seite zur Build-Zeit 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 im initialen HTML auf der Client-Seite sichtbar sind. Dies dient dazu, die Seite korrekt zu hydrieren. Stellen Sie sicher, dass Sie keine sensiblen Informationen in props übergeben, die nicht auf dem Client verfügbar sein sollten.

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

Wann sollte ich getStaticProps verwenden?

Sie sollten getStaticProps verwenden, wenn:

Die zum Rendern der Seite erforderlichen Daten zum Build-Zeitpunkt vor einer Benutzeranfrage verfügbar sind
Die Daten von einem Headless CMS stammen
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 zwischengespeichert werden können, um die Leistung zu verbessern
Die Daten öffentlich zwischengespeichert werden können (nicht benutzerspezifisch). Diese Bedingung kann in bestimmten Situationen durch die Verwendung eines Middleware zur Pfadumleitung umgangen werden.

Wann wird getStaticProps ausgeführt

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

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 frische Seite dem Browser bereitgestellt 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, sollten Sie zusätzlich zu getStaticProps eine Middleware verwenden.

Daten von einem CMS mit getStaticProps abrufen

Das folgende Beispiel zeigt, wie Sie eine Liste von Blog-Beiträgen von einem CMS abrufen können.

// posts werden zur Build-Zeit von getStaticProps() befüllt
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// Diese Funktion wird zur Build-Zeit auf der Server-Seite aufgerufen.
// Sie wird nicht auf der Client-Seite aufgerufen, sodass Sie sogar
// direkte Datenbankabfragen durchführen können.
export async function getStaticProps() {
  // Rufen Sie einen externen API-Endpunkt ab, um Beiträge zu erhalten.
  // Sie können jede Datenabrufbibliothek 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 Build-Zeit
  return {
    props: {
      posts,
    },
  }
}

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

Serverseitigen Code direkt schreiben

Da getStaticProps nur auf der Server-Seite ausgeführt wird, wird es niemals auf der Client-Seite ausgeführt. Es wird nicht einmal im JS-Bundle für den Browser enthalten sein, sodass Sie direkte Datenbankabfragen schreiben können, ohne dass sie an Browser gesendet werden.

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

Betrachten Sie das folgende Beispiel. Eine API-Route wird verwendet, um einige Daten von einem CMS abzurufen. Diese API-Route wird dann direkt von getStaticProps aufgerufen. Dies führt zu einem zusätzlichen Aufruf und verringert die Leistung. Stattdessen kann die Logik zum Abrufen der Daten vom CMS durch die Verwendung eines lib/-Verzeichnisses gemeinsam genutzt werden. Dann kann sie mit getStaticProps geteilt werden.

lib/load-posts.js

// Die folgende Funktion wird mit getStaticProps
// und API-Routen aus einem `lib/`-Verzeichnis geteilt
export async function loadPosts() {
  // Rufen Sie einen externen API-Endpunkt ab, um Beiträge zu erhalten
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

pages/blog.js

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// Diese Funktion wird nur auf der Server-Seite ausgeführt
export async function getStaticProps() {
  // Anstatt Ihre `/api`-Route abzurufen, können Sie dieselbe
  // Funktion direkt in `getStaticProps` aufrufen
  const posts = await loadPosts()

  // Die zurückgegebenen Props werden an die Seitenkomponente übergeben
  return { props: { posts } }
}

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

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

Statische Generierung von HTML und JSON

Wenn eine Seite mit getStaticProps zur Build-Zeit vorgerendert wird, generiert Next.js neben der HTML-Datei der Seite auch eine JSON-Datei mit dem Ergebnis der Ausführung von getStaticProps.

Diese JSON-Datei wird beim clientseitigen 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 (die zur Build-Zeit vorberechnet wurde) ab und verwendet sie als Props für die Seitenkomponente. Das bedeutet, dass clientseitige Seitenübergänge nicht getStaticProps aufrufen, da nur das exportierte JSON verwendet wird.

Bei Verwendung der inkrementellen statischen Generierung wird getStaticProps im Hintergrund ausgeführt, um das für das clientseitige Routing benötigte JSON zu generieren. Sie können dies in Form mehrerer Anfragen für dieselbe Seite sehen, dies ist jedoch beabsichtigt und hat keine Auswirkungen auf die Leistung für Endbenutzer.

Wo kann ich getStaticProps verwenden

getStaticProps kann nur von einer Seite exportiert werden. Sie können es nicht von Nicht-Seiten-Dateien, _app, _document oder _error exportieren.

Einer der Gründe für diese Einschränkung ist, dass React alle erforderlichen Daten vor dem Rendern der Seite benötigt.

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

Gut zu wissen: Wenn Sie eine benutzerdefinierte App erstellt haben, stellen Sie sicher, dass Sie die pageProps wie im verlinkten Dokument gezeigt an die Seitenkomponente übergeben, da die Props sonst leer sein werden.

Ausführung bei jeder Anfrage in der Entwicklung

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

Vorschaumodus

Sie können die statische Generierung vorübergehend umgehen und die Seite zur Anfragezeit statt zur Build-Zeit rendern, indem Sie den Vorschaumodus verwenden. Zum Beispiel könnten Sie ein Headless CMS verwenden und Entwürfe vor der Veröffentlichung anzeigen wollen.

On this page