generateStaticParams

Die Funktion generateStaticParams kann in Kombination mit dynamischen Routensegmenten verwendet werden, um Routen statisch zur Build-Zeit zu generieren, anstatt bei Bedarf zur Laufzeit.

// Gibt eine Liste von `params` zurück, um das dynamische Segment [slug] zu füllen
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

// Mehrere Versionen dieser Seite werden statisch generiert
// unter Verwendung der von `generateStaticParams` zurückgegebenen `params`
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

Wissenswert:

Sie können die dynamicParams-Segmentkonfigurationsoption verwenden, um zu steuern, was passiert, wenn ein dynamisches Segment aufgerufen wird, das nicht mit generateStaticParams generiert wurde.

Sie müssen entweder ein leeres Array von generateStaticParams zurückgeben oder export const dynamic = 'force-static' verwenden, um Pfade zur Laufzeit neu zu validieren (ISR).

Während next dev wird generateStaticParams aufgerufen, wenn Sie zu einer Route navigieren.

Während next build wird generateStaticParams ausgeführt, bevor die entsprechenden Layouts oder Seiten generiert werden.

Während der Neuvvalidierung (ISR) wird generateStaticParams nicht erneut aufgerufen.

generateStaticParams ersetzt die getStaticPaths-Funktion im Pages Router.

Parameter

options.params (optional)

Wenn mehrere dynamische Segmente in einer Route generateStaticParams verwenden, wird die untergeordnete generateStaticParams-Funktion einmal für jeden Satz von params ausgeführt, den das übergeordnete Element generiert.

Das params-Objekt enthält die gefüllten params aus der übergeordneten generateStaticParams-Funktion, die verwendet werden können, um die params in einem untergeordneten Segment zu generieren.

Rückgabewerte

generateStaticParams sollte ein Array von Objekten zurückgeben, wobei jedes Objekt die gefüllten dynamischen Segmente einer einzelnen Route darstellt.

Jede Eigenschaft im Objekt ist ein dynamisches Segment, das für die Route ausgefüllt werden soll.
Der Eigenschaftsname ist der Name des Segments, und der Eigenschaftswert ist der Wert, mit dem das Segment gefüllt werden soll.

Beispiel-Route	Rückgabetyp von `generateStaticParams`
`/product/[id]`	`{ id: string }[]`
`/products/[category]/[product]`	`{ category: string, product: string }[]`
`/products/[...slug]`	`{ slug: string[] }[]`

Einzelnes dynamisches Segment

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// Drei Versionen dieser Seite werden statisch generiert
// unter Verwendung der von `generateStaticParams` zurückgegebenen `params`
// - /product/1
// - /product/2
// - /product/3
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  // ...
}

Mehrere dynamische Segmente

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}

// Drei Versionen dieser Seite werden statisch generiert
// unter Verwendung der von `generateStaticParams` zurückgegebenen `params`
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  const { category, product } = await params
  // ...
}

Catch-all dynamisches Segment

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}

// Drei Versionen dieser Seite werden statisch generiert
// unter Verwendung der von `generateStaticParams` zurückgegebenen `params`
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string[] }>
}) {
  const { slug } = await params
  // ...
}

Beispiele

Statisches Rendering

Alle Pfade zur Build-Zeit

Um alle Pfade zur Build-Zeit statisch zu rendern, übergeben Sie die vollständige Liste der Pfade an generateStaticParams:

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

Teilmenge der Pfade zur Build-Zeit

Um eine Teilmenge der Pfade zur Build-Zeit statisch zu rendern und den Rest beim ersten Aufruf zur Laufzeit, geben Sie eine Teilmenge der Pfade zurück:

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  // Rendert die ersten 10 Beiträge zur Build-Zeit
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

Dann können Sie mit der dynamicParams-Segmentkonfigurationsoption steuern, was passiert, wenn ein dynamisches Segment aufgerufen wird, das nicht mit generateStaticParams generiert wurde.

// Alle Beiträge außer den Top 10 werden als 404 gerendert
export const dynamicParams = false

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  const topPosts = posts.slice(0, 10)

  return topPosts.map((post) => ({
    slug: post.slug,
  }))
}

Alle Pfade zur Laufzeit

Um alle Pfade beim ersten Aufruf statisch zu rendern, geben Sie ein leeres Array zurück (keine Pfade werden zur Build-Zeit gerendert) oder verwenden Sie export const dynamic = 'force-static':

app/blog/[slug]/page.js

export async function generateStaticParams() {
  return []
}

Wissenswert: Sie müssen immer ein Array von generateStaticParams zurückgeben, auch wenn es leer ist. Andernfalls wird die Route dynamisch gerendert.

app/changelog/[slug]/page.js

export const dynamic = 'force-static'

Rendering für nicht spezifizierte Pfade deaktivieren

Um zu verhindern, dass nicht spezifizierte Pfade zur Laufzeit statisch gerendert werden, fügen Sie die Option export const dynamicParams = false in einem Routensegment hinzu. Wenn diese Konfigurationsoption verwendet wird, werden nur die von generateStaticParams bereitgestellten Pfade bedient, und nicht spezifizierte Routen führen zu einem 404-Fehler oder werden abgeglichen (im Fall von Catch-all-Routen).

Mehrere dynamische Segmente in einer Route

Sie können Parameter für dynamische Segmente oberhalb des aktuellen Layouts oder der aktuellen Seite generieren, aber nicht unterhalb. Zum Beispiel für die Route app/products/[category]/[product]:

app/products/[category]/[product]/page.js kann Parameter für sowohl [category] als auch [product] generieren.
app/products/[category]/layout.js kann nur Parameter für [category] generieren.

Es gibt zwei Ansätze, um Parameter für eine Route mit mehreren dynamischen Segmenten zu generieren:

Parameter von unten nach oben generieren

Generieren Sie mehrere dynamische Segmente aus dem untergeordneten Routensegment.

// Generiert Segmente für sowohl [category] als auch [product]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

Parameter von oben nach unten generieren

Generieren Sie zuerst die übergeordneten Segmente und verwenden Sie das Ergebnis, um die untergeordneten Segmente zu generieren.

// Generiert Segmente für [category]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
  }))
}

export default function Layout({
  params,
}: {
  params: Promise<{ category: string }>
}) {
  // ...
}

Die generateStaticParams-Funktion eines untergeordneten Routensegments wird einmal für jedes Segment ausgeführt, das eine übergeordnete generateStaticParams-Funktion generiert.

Die untergeordnete generateStaticParams-Funktion kann die params der übergeordneten generateStaticParams-Funktion verwenden, um ihre eigenen Segmente dynamisch zu generieren.

// Generiert Segmente für [product] unter Verwendung der `params`,
// die von der übergeordneten `generateStaticParams`-Funktion übergeben wurden
export async function generateStaticParams({
  params: { category },
}: {
  params: { category: string }
}) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

  return products.map((product) => ({
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

Wissenswert: fetch-Anfragen werden automatisch memoisiert für dieselben Daten über alle generate-präfixierten Funktionen, Layouts, Seiten und Serverkomponenten hinweg. React cache kann verwendet werden, falls fetch nicht verfügbar ist.

Versionsverlauf

Version	Änderungen
`v13.0.0`	`generateStaticParams` eingeführt.

On this page