getServerSideProps

Wenn Sie eine Funktion namens getServerSideProps (Server-Side Rendering) aus einer Seite exportieren, wird Next.js diese Seite bei jeder Anfrage mit den von getServerSideProps zurückgegebenen Daten vorrendern.

import type { InferGetServerSidePropsType, GetServerSideProps } from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getServerSideProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetServerSideProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return repo.stargazers_count
}

export async function getServerSideProps() {
  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
}

Hinweis: Unabhängig vom Rendering-Typ werden alle props an die Seitenkomponente übergeben und können auf der Client-Seite im initialen HTML eingesehen werden. Dies dient dazu, die Hydration der Seite korrekt durchzuführen. Stellen Sie sicher, dass Sie keine sensiblen Informationen in props übergeben, die nicht auf dem Client verfügbar sein sollten.

Wann wird getServerSideProps ausgeführt

getServerSideProps wird nur auf der Server-Seite ausgeführt und niemals im Browser. Wenn eine Seite getServerSideProps verwendet, gilt:

Wenn Sie diese Seite direkt aufrufen, wird getServerSideProps zur Anfragezeit ausgeführt und die Seite mit den zurückgegebenen Props vorgerendert
Wenn Sie diese Seite über next/link oder next/router aufrufen, sendet Next.js eine API-Anfrage an den Server, der getServerSideProps ausführt

getServerSideProps gibt JSON zurück, das zum Rendern der Seite verwendet wird. All diese Arbeiten werden automatisch von Next.js übernommen, sodass Sie nichts weiter tun müssen, solange getServerSideProps definiert ist.

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

getServerSideProps kann nur aus einer Seite exportiert werden. Sie können es nicht aus Nicht-Seiten-Dateien exportieren.

Beachten Sie, dass Sie getServerSideProps als eigenständige Funktion exportieren müssen – es funktioniert nicht, wenn Sie getServerSideProps als Eigenschaft der Seitenkomponente hinzufügen.

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

Wann sollte ich getServerSideProps verwenden

Sie sollten getServerSideProps nur verwenden, wenn Sie eine Seite rendern müssen, deren Daten zur Anfragezeit abgerufen werden müssen. Dies kann aufgrund der Art der Daten oder Eigenschaften der Anfrage (wie authorization-Header oder Geo-Standort) erforderlich sein. Seiten, die getServerSideProps verwenden, werden zur Anfragezeit serverseitig gerendert und nur zwischengespeichert, wenn Cache-Control-Header konfiguriert sind.

Wenn Sie die Daten nicht während der Anfrage rendern müssen, sollten Sie in Betracht ziehen, die Daten auf der Client-Seite oder mit getStaticProps abzurufen.

getServerSideProps oder API-Routen

Es kann verlockend sein, eine API-Route zu verwenden, wenn Sie Daten vom Server abrufen möchten, und dann diese API-Route von getServerSideProps aus aufzurufen. Dies ist ein unnötiger und ineffizienter Ansatz, da er eine zusätzliche Anfrage verursacht, da sowohl getServerSideProps als auch API-Routen auf dem Server ausgeführt werden.

Nehmen Sie das folgende Beispiel. Eine API-Route wird verwendet, um Daten von einem CMS abzurufen. Diese API-Route wird dann direkt von getServerSideProps aufgerufen. Dies führt zu einem zusätzlichen Aufruf und reduziert die Leistung. Importieren Sie stattdessen die Logik, die in Ihrer API-Route verwendet wird, direkt in getServerSideProps. Dies könnte bedeuten, dass Sie ein CMS, eine Datenbank oder eine andere API direkt von getServerSideProps aus aufrufen.

getServerSideProps mit Edge-API-Routen

getServerSideProps kann mit Serverless- und Edge-Runtimes verwendet werden, und Sie können Props in beiden setzen. Allerdings haben Sie in der Edge-Runtime derzeit keinen Zugriff auf das Response-Objekt. Das bedeutet, dass Sie beispielsweise keine Cookies in getServerSideProps hinzufügen können. Um Zugriff auf das Response-Objekt zu haben, sollten Sie weiterhin die Node.js-Runtime verwenden, die die Standard-Runtime ist.

Sie können die Runtime pro Seite explizit festlegen, indem Sie die config ändern, zum Beispiel:

pages/index.js

export const config = {
  runtime: 'nodejs', // oder "edge"
}

export const getServerSideProps = async () => {}

Daten auf der Client-Seite abrufen

Wenn Ihre Seite häufig aktualisierte Daten enthält und Sie die Daten nicht vorrendern müssen, können Sie die Daten auf der Client-Seite abrufen. Ein Beispiel hierfür sind benutzerspezifische Daten:

Zeigen Sie zunächst die Seite ohne Daten an. Teile der Seite können mit Static Generation vorgerendert werden. Sie können Ladezustände für fehlende Daten anzeigen
Rufen Sie dann die Daten auf der Client-Seite ab und zeigen Sie sie an, wenn sie bereit sind

Dieser Ansatz eignet sich gut für Benutzer-Dashboard-Seiten. Da ein Dashboard eine private, benutzerspezifische Seite ist, ist SEO nicht relevant und die Seite muss nicht vorgerendert werden. Die Daten werden häufig aktualisiert, was eine Datenabfrage zur Anfragezeit erfordert.

Verwendung von getServerSideProps zum Abrufen von Daten zur Anfragezeit

Das folgende Beispiel zeigt, wie Sie Daten zur Anfragezeit abrufen und das Ergebnis vorrendern können.

// Dies wird bei jeder Anfrage aufgerufen
export async function getServerSideProps() {
  // Daten von externer API abrufen
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // Daten über Props an die Seite übergeben
  return { props: { data } }
}

export default function Page({ data }) {
  // Daten rendern...
}

Caching mit Server-Side Rendering (SSR)

Sie können Cache-Header (Cache-Control) in getServerSideProps verwenden, um dynamische Antworten zwischenzuspeichern. Zum Beispiel mit stale-while-revalidate.

// Dieser Wert gilt für zehn Sekunden als frisch (s-maxage=10).
// Wenn eine Anfrage innerhalb der nächsten 10 Sekunden wiederholt wird, wird der zuvor
// zwischengespeicherte Wert noch als frisch betrachtet. Wenn die Anfrage vor 59 Sekunden wiederholt wird,
// wird der zwischengespeicherte Wert als veraltet betrachtet, aber trotzdem gerendert (stale-while-revalidate=59).
//
// Im Hintergrund wird eine Revalidierungsanfrage gestellt, um den Cache
// mit einem frischen Wert zu füllen. Wenn Sie die Seite aktualisieren, sehen Sie den neuen Wert.
export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59'
  )

  return {
    props: {},
  }
}

Erfahren Sie mehr über Caching.

Zeigt getServerSideProps eine Fehlerseite an

Wenn in getServerSideProps ein Fehler auftritt, wird die Datei pages/500.js angezeigt. Lesen Sie die Dokumentation zur 500-Seite, um mehr über deren Erstellung zu erfahren. Während der Entwicklung wird diese Datei nicht verwendet und stattdessen das Dev-Overlay angezeigt.

On this page