Konfiguration von Routensegmenten

Die auf dieser Seite beschriebenen Optionen sind deaktiviert, wenn das dynamicIO-Flag aktiviert ist, und werden in Zukunft schrittweise abgeschafft.

Mit den Routensegment-Optionen können Sie das Verhalten einer Seite, eines Layouts oder eines Route Handlers konfigurieren, indem Sie die folgenden Variablen direkt exportieren:

Optionen

experimental_ppr

Aktiviert Partielles Prerendering (PPR) für ein Layout oder eine Seite.

export const experimental_ppr = true
// true | false

dynamic

Ändert das dynamische Verhalten eines Layouts oder einer Seite zu vollständig statisch oder vollständig dynamisch.

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

Gut zu wissen: Das neue Modell im app-Verzeichnis bevorzugt eine granulare Cache-Steuerung auf der Ebene der fetch-Anfragen gegenüber dem binären Alles-oder-Nichts-Modell von getServerSideProps und getStaticProps auf Seitenebene im pages-Verzeichnis. Die dynamic-Option bietet eine Möglichkeit, zum vorherigen Modell zurückzukehren und erleichtert die Migration.

• 'auto' (Standard): Die Standardoption, um so viel wie möglich zu cachen, ohne Komponenten daran zu hindern, dynamisches Verhalten zu nutzen.
• 'force-dynamic': Erzwingt dynamisches Rendering, wodurch Routen bei jeder Anfrage für jeden Benutzer gerendert werden. Diese Option entspricht:
  • Setzen der Option jeder fetch()-Anfrage in einem Layout oder einer Seite auf { cache: 'no-store', next: { revalidate: 0 } }.
  • Setzen der Segmentkonfiguration auf export const fetchCache = 'force-no-store'
• 'error': Erzwingt statisches Rendering und cacht die Daten eines Layouts oder einer Seite, indem ein Fehler ausgelöst wird, wenn Komponenten Dynamische APIs oder ungecachte Daten verwenden. Diese Option entspricht:
  • getStaticProps() im pages-Verzeichnis.
  • Setzen der Option jeder fetch()-Anfrage in einem Layout oder einer Seite auf { cache: 'force-cache' }.
  • Setzen der Segmentkonfiguration auf fetchCache = 'only-cache', dynamicParams = false.
  • dynamic = 'error' ändert den Standardwert von dynamicParams von true zu false. Sie können dynamisches Rendering für dynamische Parameter, die nicht von generateStaticParams generiert wurden, durch manuelles Setzen von dynamicParams = true wieder aktivieren.
• 'force-static': Erzwingt statisches Rendering und cacht die Daten eines Layouts oder einer Seite, indem cookies, headers() und useSearchParams() gezwungen werden, leere Werte zurückzugeben. Es ist möglich, revalidate, revalidatePath oder revalidateTag in Seiten oder Layouts zu verwenden, die mit force-static gerendert wurden.

Gut zu wissen:

• Anleitungen zur Migration von getServerSideProps und getStaticProps zu dynamic: 'force-dynamic' und dynamic: 'error' finden Sie im Upgrade-Guide.

dynamicParams

Steuert, was passiert, wenn ein dynamisches Segment aufgerufen wird, das nicht mit generateStaticParams generiert wurde.

export const dynamicParams = true // true | false,

• true (Standard): Dynamische Segmente, die nicht in generateStaticParams enthalten sind, werden bei Bedarf generiert.
• false: Dynamische Segmente, die nicht in generateStaticParams enthalten sind, geben einen 404-Fehler zurück.

Gut zu wissen:

• Diese Option ersetzt die fallback: true | false | blocking-Option von getStaticPaths im pages-Verzeichnis.
• Um alle Pfade beim ersten Aufruf statisch zu rendern, müssen Sie ein leeres Array in generateStaticParams zurückgeben oder export const dynamic = 'force-static' verwenden.
• Wenn dynamicParams = true, verwendet das Segment Streaming Server Rendering.

revalidate

Legt die Standard-Revalidierungszeit für ein Layout oder eine Seite fest. Diese Option überschreibt nicht den revalidate-Wert einzelner fetch-Anfragen.

export const revalidate = false
// false | 0 | number

• false (Standard): Die Standardheuristik, um alle fetch-Anfragen zu cachen, die ihre cache-Option auf 'force-cache' setzen oder vor der Verwendung einer Dynamischen API entdeckt werden. Semantisch äquivalent zu revalidate: Infinity, was bedeutet, dass die Ressource effektiv unbegrenzt gecacht wird. Einzelne fetch-Anfragen können weiterhin cache: 'no-store' oder revalidate: 0 verwenden, um das Caching zu vermeiden und die Route dynamisch zu rendern. Oder setzen Sie revalidate auf eine positive Zahl, die niedriger ist als der Standardwert der Route, um die Revalidierungshäufigkeit zu erhöhen.
• 0: Stellt sicher, dass ein Layout oder eine Seite immer dynamisch gerendert wird, auch wenn keine Dynamischen APIs oder ungecachten Datenabrufe entdeckt werden. Diese Option ändert den Standardwert von fetch-Anfragen, die keine cache-Option setzen, zu 'no-store', lässt aber fetch-Anfragen, die 'force-cache' oder eine positive revalidate verwenden, unverändert.
• number: (in Sekunden) Legt die Standard-Revalidierungshäufigkeit eines Layouts oder einer Seite auf n Sekunden fest.

Gut zu wissen:

• Der Revalidate-Wert muss statisch analysierbar sein. Zum Beispiel ist revalidate = 600 gültig, aber revalidate = 60 * 10 nicht.
• Der Revalidate-Wert ist nicht verfügbar, wenn runtime = 'edge' verwendet wird.
• In der Entwicklung werden Seiten immer bei Bedarf gerendert und nie gecacht. Dies ermöglicht es Ihnen, Änderungen sofort zu sehen, ohne auf eine Revalidierungsperiode warten zu müssen.

Revalidierungshäufigkeit

• Der niedrigste revalidate-Wert über alle Layouts und Seiten einer einzelnen Route bestimmt die Revalidierungshäufigkeit der gesamten Route. Dies stellt sicher, dass untergeordnete Seiten so häufig revalidiert werden wie ihre übergeordneten Layouts.
• Einzelne fetch-Anfragen können einen niedrigeren revalidate-Wert als den Standardwert der Route setzen, um die Revalidierungshäufigkeit der gesamten Route zu erhöhen. Dies ermöglicht es Ihnen, basierend auf bestimmten Kriterien dynamisch eine häufigere Revalidierung für bestimmte Routen zu aktivieren.

fetchCache

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

runtime

Wir empfehlen, die Node.js-Runtime für das Rendering Ihrer Anwendung und die Edge-Runtime für Middleware zu verwenden.

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

• 'nodejs' (Standard)
• 'edge'

preferredRegion

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

Die Unterstützung für preferredRegion und die unterstützten Regionen hängt von Ihrer Deployment-Plattform ab.

Gut zu wissen:

• Wenn preferredRegion nicht angegeben ist, erbt es die Option des nächstgelegenen übergeordneten Layouts.
• Das Root-Layout standardmäßig auf all Regionen.

maxDuration

Standardmäßig begrenzt Next.js nicht die Ausführung von serverseitiger Logik (Rendern einer Seite oder Verarbeiten einer API). Deployment-Plattformen können maxDuration aus der Next.js-Build-Ausgabe verwenden, um spezifische Ausführungslimits hinzuzufügen.

Hinweis: Diese Einstellung erfordert Next.js 13.4.10 oder höher.

export const maxDuration = 5

Gut zu wissen:

• Wenn Sie Server Actions verwenden, setzen Sie maxDuration auf Seitenebene, um das Standard-Timeout aller auf der Seite verwendeten Server Actions zu ändern.

generateStaticParams

Die Funktion generateStaticParams kann in Kombination mit dynamischen Routensegmenten verwendet werden, um die Liste der Routensegmentparameter zu definieren, die statisch zur Build-Zeit generiert werden, anstatt bei Bedarf zur Anfragezeit.

Weitere Details finden Sie in der API-Referenz.

Versionsverlauf