Was macht next-cache-components-adoption?
Aktiviere Cache Components in einer App und führe sie zu einem erfolgreichen Build. Diese Skill sequenziert die Arbeit; Fehlerbehebungen für einzelne Fehler befinden sich in den Dev-Overlay-Reparaturkarten und in der Build-Terminal-Ausgabe. Der Leitfaden zur Migration zu Cache Components ist die kanonische Referenz für die Konzepte und API-spezifischen Rezepte, die diese Skill anwendet – konsultiere ihn immer, wenn die Skill-Schritte ein Muster erwähnen ("use cache", cacheLife, <Suspense>-Platzierung usw.) und du die vollständige Erklärung wünschst.
Voraussetzungen
-
App Router-Projekt. Cache Components ist eine Funktion des App Routers;
cacheComponents: truehat keine Wirkung aufpages/-Routen. Wenn das Projekt einenpages/- odersrc/pages/-Baum, aber keinenapp/- odersrc/app/-Baum hat, stoppe und informiere den Benutzer – die Migration von Pages zu App ist ein eigenes Projekt und nicht Teil dieser Skill. Eine Hybrid-App (sowohlpages/als auchapp/) ist in Ordnung: Das Flag betrifft dieapp/-Routen;pages/-Routen sind nicht betroffen und benötigen keine Ausnahmen. -
Next.js 16.3 oder neuer. Diese Version enthält die Bestandteile, auf die sich diese Skill stützt: top-level
cacheComponents,export const instant, die Dev-Overlay-Validierungswarnungen für die sofortige Navigation und die Codemodcache-components-instant-false. Wennnext --versioneine Version unter 16.3 anzeigt, aktualisiere zuerst:npx @next/codemod@latest upgrade latestum die versionsspezifischen Codemods anzuwenden.- Lese den entsprechenden Versions-Upgrade-Leitfaden (z.B. Version 16) für das, was die Codemod nicht abdeckt.
-
Keine inkompatiblen Konfigurationsschlüssel.
cacheComponents: trueführt bei Dateien, die nochdynamic,revalidateoderfetchCacheexportieren, zu Fehlern. Übersetze, lösche nicht. Jeder Export kodiert ein Verhalten, das die Route beibehalten muss; migriere jeden einzelnen über die schlüsselspezifischen Abschnitte des Migrationsleitfadens in sein Cache Components-Äquivalent. Wenn ein Wert noch nicht sauber übersetzt werden kann, hinterlasse einen// TODO: Cache Components adoption — restore revalidate = 3600-Kommentar, damit die Schleife ihn aufgreift. Die Codemodcache-components-instant-falseberührt diese nicht. -
experimental.dynamicIOist fatal. Es wurde in das top-levelcacheComponentsumbenannt, und der alte Schlüssel bricht den Build jetzt ab – entferne ihn (oder ersetze ihn durchcacheComponents: true) zuerst.experimental.useCachewird noch als veraltetes Alias akzeptiert; es ist redundant, sobaldcacheComponents: truegesetzt ist, also entferne es zur Klarheit.
Hinweise
-
Keine funktionierende Basislinie vor dem Flag. Wenn die App bereits
"use cache"verwendet, schlägt der Build vor dem Setzen des Flags mit dem Fehlerplease enable the feature flag cacheComponentsfehl. Das Setzen des Flags ist das Erste, was du tust (inkrementell vor der Codemod, direkt vor der Fehlerbehebung) – nicht etwas, das du nach einem erfolgreichen Build tust. Vermerke dies in deiner Zusammenfassung zu Beginn, damit es nicht wie eine Regression aussieht. -
Offline-Dokumentation. Offline-Kopien der Leitfaden-Links befinden sich unter
node_modules/next/dist/docs/, wobei die Verzeichnisstruktur für die Sortierung nummeriert ist (z.B.node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). Der letzte Dateiname entspricht dem Slug. Wenn du das nummerierte Präfix nicht vorhersagen kannst, löstfind node_modules/next/dist/docs -name '<slug>.md'es auf. Die/docs/messages/*Fehlerseiten sind nicht gebündelt. Wenn die Offline-Dokumentation vollständig fehlt, führenpx @next/codemod@latest agents-mdaus, um einen versionsgemäßen Index inAGENTS.md/CLAUDE.mdzu schreiben.
Die Struktur der Arbeit
Es gibt eine Schleife: Durchlaufe den Routenbaum von oben nach unten, eine Funktion nach der anderen, und adoptiere jede Route mit next dev + einem Browser. Der Build ist eine abschließende Überprüfung für jede Funktion, nicht die Arbeitsumgebung.
Die Wahl in Schritt 1 ist, ob zuerst die Validierungsfehler unterdrückt oder sie sofort behoben werden. In beiden Fällen ist die Schleife dieselbe:
- Mit einem ruhigen Vorschritt (Inkrementell). Führe die Codemod aus, um jede Seite und jedes Layout von der Validierung auszunehmen. Sobald du auch das behoben hast, was die Codemod nicht kann (synchrone I/O-Aufrufe, übrig gebliebene
revalidate/dynamic/fetchCache-Exporte), ist der Build erfolgreich; du lieferst dies als eigenen PR aus und beginnst dann die Schleife – entferne nach und nach eine Ausnahme und adoptiere diese Route. Zerlegt die Arbeit in kleine, überprüfbare PRs. - Ohne (Direkt). Aktiviere
cacheComponentsund beginne die Schleife mit dem, was der Build zuerst meldet. Gleiche Schleife, aber jede Korrektur befindet sich auf einem Branch, bis die Adoption abgeschlossen ist.
In beiden Fällen ist das Erfolgskriterium pro Route dasselbe: Die Dev-Schleife meldet keine Fehler UND next build ist erfolgreich. Frage den Benutzer nach jeder Funktion. Erwarte, die meiste Zeit in der Schleife zu verbringen, nicht im Vorschritt.
Hintergrund
cacheComponents: true erfordert, dass jede Route vorgerendert werden kann. Eine Route, die Anfragedaten außerhalb von <Suspense> liest, ist "blockierend" und führt zu einem Build-Fehler. export const instant = false markiert eine Route als blockierungsfähig, was sie sowohl in der Entwicklung als auch im Build freigibt; bei einem Layout deckt es den gesamten darunter liegenden Teilbaum ab. Lesevorgänge, die in eine "use cache"-Funktion eingebettet sind, gelten als Cache-Grenzen, nicht als blockierende Lesevorgänge.
Drei Klassen von Blockierern treten in dieser Reihenfolge auf:
- Anfragezeit-Lesevorgänge (
cookies(),headers(),await params,await searchParams). Alle vier blockieren, wenn sie am Anfang einer Seite oder eines Layouts abgewartet werden.paramsundsearchParamswerden oft übersehen, weil sie nicht als "Anfragedaten" wie Cookies und Header kategorisiert werden. Die Lösung besteht darin, den Lesevorgang in ein<Suspense>-gewickeltes Kind zu verschieben – und beiparams/searchParamsdas Promise an das Kind weiterzugeben und es dort abzuwarten; warte nicht am Seitenanfang. - Synchrone I/O zur Modul-/Renderzeit (
new Date(),Date.now(),Math.random(),crypto.randomUUID()). Diese führen selbst mitinstant = falsezu Build-Fehlern – die Ausnahme unterdrückt sie nicht. Wenn sie sich in einem gemeinsamen Layout befinden, blockieren sie jede Route darunter. Die Codemod kann sie nicht beheben; du musst jede einzelne übersetzen (mit"use cache"zwischenspeichern, wenn sie stabil ist, oder inawait connection()+<Suspense>einwickeln, wenn sie pro Anfrage erfolgt), bevor der Build erfolgreich sein kann. Durchsuche das gesamte Repository vor der Ausführung nach diesen Aufrufen. "use cache"-Dateien, die Anfragedaten lesen. Eine Datei mit einer top-level"use cache"-Direktive kann keininstantexportieren; die Kombination führt zum FehlerOnly async functions are allowed to be exported in a "use cache" file.und bedeutet, dass die Direktive für diese Route falsch war. Entferne sie vor der Ausführung der Codemod.
Arbeitsumgebungen
Auffinden blockierender Routen
Bevorzuge next dev gegenüber next build während der Arbeit.
next dev– die Arbeitsumgebung. Besuche eine Route; ihre Blockierungsfehler erscheinen im Dev-Overlay mit vollständigen Stack-Traces und Reparaturkarten, die auf die dokumentationsspezifischen Fehlerseiten verlinken. Arbeite eine Route nach der anderen – Fehler sammeln sich nicht an einer Stelle. Die Route selbst gibt dennoch HTTP 200 zurück, lies also das Overlay (oder.next-dev.log), nicht die Statuscodes. Ein leeres Overlay ist eine Hälfte des "Route sauber"-Zustands – die andere Hälfte ist die Browser-Überprüfung (siehe Schritt 2) und ein erfolgreicher Build für diese Route.next build– nur zur Erkennung. Der Build ist die autoritative Überprüfung fürnext dev, nicht sein Ersatz. Verwende ihn als letzte Hürde für jede Funktion in der Schleife (ein erfolgreicher Build ist Teil des Erfolgskriteriums pro Route) und als abschließende Überprüfung für die gesamte App. Im inkrementellen Modus bestätigt der Build auch den Vorschritt (Codemod hat jede Route ausgenommen, kein gemeinsames Layout hat noch einen synchrone I/O-Blockierer), bevor du diesen PR auslieferst. Greife nicht während der Arbeit an einer Route zum Build, anstatt die Dev-Schleife zu verwenden – ein sauberer Kompilierungsfehler sagt dir nicht, was in der statischen Shell gelandet ist und was gestreamt wurde. Standardmäßig stoppt der Build bei der ersten blockierenden Route, daher ist er auch schlecht für die Einschätzung des Arbeitsumfangs. Zwei Flags helfen bei der Iteration:--debug-build-pathsbaut nur die von dir benannten Routen (kommagetrennte Glob-Muster von Dateipfaden relativ zum Projektstamm, z.B.--debug-build-paths="app/admin/**/page.tsx"– keine URL-Pfade;--debug-build-paths="app/(marketing)/about/page.tsx"– nicht/about;--debug-build-paths="app/admin"trifft nichts und baut stillschweigend null Routen), und--debug-prerenderdeaktiviert den vorzeitigen Abbruch, sodass der Build über den ersten Vorab-Rendering-Fehler hinaus fortfährt, jede blockierende Route meldet und einen detaillierteren Stack-Trace ausgibt, der die Ursprungsdatei und -zeile nennt.
Jeder Blockierungsfehler hat eine Dokumentationsseite – öffne sie. Sowohl das Dev-Overlay als auch das Build-Terminal geben einen https://nextjs.org/docs/messages/<slug>-Link mit jedem Fehler aus. Diese Seite ist das kanonische Rezept für die Behebung; die Inline-Nachricht ist eine Zusammenfassung. Rufe den Link für jeden unterschiedlichen Fehler ab, den du siehst, selbst wenn du denkst, das Muster zu kennen – die Rezepte entwickeln sich weiter, und derselbe Fehlertyp kann je nach dem, was die Route liest, unterschiedliche korrekte Korrekturen erfordern. Improvisiere nicht basierend auf der Inline-Nachricht allein. (/docs/messages/*-Seiten sind nicht offline gebündelt; wenn du kein Netzwerk hast, greife auf die API-spezifischen Leitfäden unter node_modules/next/dist/docs/ zurück und vermerke die Einschränkung, wenn du berichtest.)
Überprüfung jeder Korrektur zur Laufzeit
Ein erfolgreicher Build oder ein leeres Overlay ist kein Beweis dafür, dass sich die Route tatsächlich korrekt verhält – Cache Components ist ein Laufzeitthema (eine statische Shell mit gestreamten Daten). Überprüfe nach jeder Korrektur, nicht erst am Ende.
In bevorzugter Reihenfolge:
-
next-dev-loop– stark bevorzugt. Kreuzt/_next/mcpmit dem Live-Browser viaagent-browserab und deckt sowohl Kompilierungs- als auch Laufzeitprobleme in einem Durchgang auf. Die Diagnostik (React-Baum, Suspense-Grenzen, Console + Netzwerk) ist umfangreicher als das händische Herumprobieren mitnext dev.Installiere es vor Beginn der Schleife. Warte nicht, bis du auf etwas stößt, das
next devallein nicht erklären kann. Führe aus:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loopDie Skill erfordert
agent-browser >= 0.27.0und führt dich durch.Erfordert Turbopack. Wenn das
dev-Skript inpackage.json--webpackübergibt, weise den Benutzer darauf hin und frage, ob es einen Grund gibt, bei webpack zu bleiben. Wenn nicht, wechsle zu Turbopack (Standard ab Next.js 16.3+). Wenn sie webpack behalten möchten, überspringe diese Installation und verwende stattdessen die Nur-Build-Schleife.Du benötigst keine Erlaubnis,
next-dev-loopselbst zu installieren. Es ist ein Werkzeug, wie die Installation einer Dev-Abhängigkeit. Wenn ein Benutzer in der Leitung ist, informiere ihn kurz, dass du es zur Überprüfung installierst. In einem nicht-interaktiven Durchlauf (CI, Dashboard, Sandbox) installiere es ohne Nachfrage – "Ich kann den Benutzer nicht fragen" ist kein Grund, es zu überspringen. Die einzigen legitimen Überspringungen sind echte technische Hürden: kein Netzwerk, kein npm, read-only Dateisystem, eine erklärte "Keine neuen Abhängigkeiten"-Richtlinie oder ein reines webpack-Dev-Skript. Wenn du überspringst, nenne die spezifische Hürde in deinem Abschlussbericht. -
Ein Browser, den du selbst steuern kannst. Playwright,
agent-browserdirekt, jedes Browser-Automatisierungswerkzeug. Verwende nur, wennnext-dev-loopwirklich blockiert ist. Dir entgehen die Framework-seitigen Prüfungen (/_next/mcp), daher erkennen DOM-Assertionen allein nicht jede Regression – sei vorsichtiger bei dem, was du als "verifiziert" bezeichnest. -
Nur Build. Wenn du überhaupt keinen Dev-Server ausführen kannst, ist der Build dein einziges Signal.
○ (Static)-Routen ohne<Suspense>sind durch den Build vollständig verifiziert (nichts zu testendes Gestreamtes).◐ (Partial Prerender)-Routen sind nur in der Shell verifiziert – markiere sie, wenn du Bericht erstattest. -
Überhaupt keine Werkzeuge. Bitte den Benutzer, den Dev-Server (oder Build) auszuführen und zu berichten, was er sieht, oder committe den erreichten Meilenstein und gib ab.
Schritt 1: Wähle eine Strategie
Frage den Benutzer. Formuliere es als Frage zur PR-Struktur, nicht als Frage zum Umfang. Verwende niemals die internen Bezeichnungen (Inkrementell, Direkt, Meilenstein A), wenn du mit dem Benutzer sprichst – das sind deine eigenen Konzepte. Frage in Bezug auf PRs und Funktionen, z.B.: "Möchtest du, dass ich zuerst einen PR öffne, der Cache Components aktiviert und jede Route von der Validierung ausnimmt, und dann die eigentlichen Route-Adoptionen funktionsweise in Folge-PRs behandle? Oder alles auf einem Branch erledigen?" Selbst bei einer winzigen App hat der inkrementelle Pfad noch Wert (überprüfbarer PR, rückgängig zu machen, die // TODO: Cache Components adoption-Marker dienen gleichzeitig als deine Aufgabenliste für die nächste Sitzung). Entscheide nicht in ihrem Namen.
Wenn es keinen Benutzer zu fragen gibt, standardmäßig Inkrementell und dokumentiere die Wahl.
- Inkrementell – ruhiger Vorschritt + die Schleife. Führe die Codemod aus, um jede Seite und jedes Layout von der Validierung auszunehmen, bringe den Build zum Laufen, stoppe und stimme dich mit dem Benutzer ab (siehe Ende des Vorschritts: Prüfung), dann betrete Schritt 2s Schleife und liefere jede Funktion als Folge-PR aus.
- Direkt – überspringe den Vorschritt. Aktiviere
cacheComponentsund gehe direkt zu Schritt 2s Schleife; die blockierenden Routen des Builds sind die Aufgabenliste.
Inkrementell
Behebe vor der Ausführung der Codemod die beiden Blockierer-Klassen, die sie nicht beheben kann.
-
Synchrone I/O zur Modul-/Renderzeit. Durchsuche das gesamte Repository nach
new Date(),Date.now(),Math.random()undcrypto.randomUUID()(nicht nurapp/**/layout.{js,jsx,ts,tsx}– der Lesevorgang könnte in jeder Komponente leben, die von einem Layout importiert wird). Übersetze jede Fundstelle mit dem Rezept aus ihrerblocking-prerender-*Fehlerkarte. -
Inkompatible Segment-Konfigurationen. Suche nach
^export const (revalidate|dynamic|fetchCache)im gesamtenapp/-Verzeichnis und übersetze gemäß dem Hinweis im Abschnitt "Voraussetzungen". Die Codemod berührt sie nicht; wenn sie an Ort und Stelle bleiben, führt der Build nach der Codemod fehl.
Die Codemod weigert sich, auf einem dreckigen Arbeitsbaum ausgeführt zu werden. Committe oder stash zuerst unabhängige Arbeiten, oder übergib --force, damit ihre Bearbeitungen neben deinen laufenden Änderungen landen können. Häufige Fehlannahme: Wenn du kürzlich Next.js aktualisiert hast, sind package.json und die Lockdatei bereits dreckig – committe diese zuerst.
Verwende den @canary
…
[gekürzt für die Übersetzung]