generateStaticParams

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

app/blog/[slug]/page.js

// 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
// mit den `params`, die von `generateStaticParams` zurückgegeben werden
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

Hinweis:

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

Sie müssen ein leeres Array von generateStaticParams zurückgeben oder export const dynamic = 'force-static' verwenden, um Pfade zur Laufzeit zu revalidieren (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 Revalidierung (ISR) wird generateStaticParams nicht erneut aufgerufen.

generateStaticParams ersetzt die Funktion getStaticPaths 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 von der übergeordneten generateStaticParams-Funktion, die verwendet werden können, um die params in einem untergeordneten Segment zu generieren.

Rückgabewert

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

Jede Eigenschaft im Objekt ist ein dynamisches Segment, das für die Route gefüllt werden soll.
Der Name der Eigenschaft ist der Name des Segments, und der Wert der Eigenschaft ist das, womit 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

app/product/[id]/page.tsx

TypeScript

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}
 
// Drei Versionen dieser Seite werden statisch generiert
// mit den `params`, die von `generateStaticParams` zurückgegeben werden
// - /product/1
// - /product/2
// - /product/3
export default async function Page({ params }: { params: { id: string } }) {
  const { id } = await params
  // ...
}

Mehrere dynamische Segmente

app/products/[category]/[product]/page.tsx

TypeScript

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}
 
// Drei Versionen dieser Seite werden statisch generiert
// mit den `params`, die von `generateStaticParams` zurückgegeben werden
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({
  params,
}: {
  params: { category: string; product: string }
}) {
  const { category, product } = await params
  // ...
}

Catch-All dynamisches Segment

app/product/[...slug]/page.tsx

TypeScript

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}
 
// Drei Versionen dieser Seite werden statisch generiert
// mit den `params`, die von `generateStaticParams` zurückgegeben werden
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({ params }: { params: { slug: string[] } }) {
  const { slug } = await params
  // ...
}

Beispiele

Statische 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:

app/blog/[slug]/page.tsx

TypeScript

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 Besuch zur Laufzeit, geben Sie eine partielle Liste der Pfade zurück:

app/blog/[slug]/page.tsx

TypeScript

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,
  }))
}

Durch die Verwendung der Segment-Konfigurationsoption dynamicParams können Sie steuern, was passiert, wenn ein dynamisches Segment besucht wird, das nicht mit generateStaticParams generiert wurde.

app/blog/[slug]/page.js

// Alle Beiträge außer den Top 10 führen zu einem 404
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 statisch zu rendern, wenn sie zum ersten Mal besucht werden, 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 []
}

Hinweis: 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 Pfade, die von generateStaticParams bereitgestellt werden, bedient, und nicht spezifizierte Routen führen zu 404 oder passen (im Fall von Catch-All-Routen).

Mehrere dynamische Segmente in einer Route

Sie können Parameter für dynamische Segmente über dem aktuellen Layout oder der Seite generieren, aber nicht darunter. Bei der Route app/products/[category]/[product] beispielsweise:

app/products/[category]/[product]/page.js kann Parameter für beide [category] und [product] generieren.
app/products/[category]/layout.js kann nur Parameter für [category] generieren.

Es gibt zwei Ansätze zur Parametergenerierung für eine Route mit mehreren dynamischen Segmenten:

Parameter von unten nach oben generieren

Generieren Sie mehrere dynamische Segmente aus dem untergeordneten Routensegment.

app/products/[category]/[product]/page.tsx

TypeScript

// Segmente für [category] und [product] generieren
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: { category: string; product: string }
}) {
  // ...
}

Parameter von oben nach unten generieren

Generieren Sie zuerst die übergeordneten Segmente und verwenden Sie das Ergebnis zur Generierung der untergeordneten Segmente.

app/products/[category]/layout.tsx

TypeScript

// Segmente für [category] generieren
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: { category: string } }) {
  // ...
}

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

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

app/products/[category]/[product]/page.tsx

TypeScript

// Segmente für [product] mit den `params` generieren, die von der
// `generateStaticParams`-Funktion des übergeordneten Segments ü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: { category: string; product: string }
}) {
  // ...
}

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

Versionshistorie

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