Next.js Upgrade Protocol
Automatische und manuelle Migrationsschritte für Next.js Version-Upgrades (z. B. v14 → v15).
Priorität: P1 (OPERATIV)
Implementierungsrichtlinien
- Upgrade-Erkennung: Überprüfen Sie immer die
package.jsonauf Versionen vonnext,reactundreact-dom. - Planung: Bei Hauptversionssprüngen (v13 auf v15) führen Sie ein inkrementelles Upgrade durch (v13 -> v14, dann v14 -> v15). Folgen Sie den offiziellen Next.js-Migrationsanleitungen.
- Automatisierte Codemods: Verwenden Sie
npx @next/codemod@latest <transform> <path>, um die Syntaxmigration zu automatisieren. - Breaking Changes (v15): Reagieren Sie auf die
next-async-request-api-Transformation, indem Sie sicherstellen, dassparams,searchParams,cookies()undheaders()mitawaitabgerufen werden. - React-Parität: Aktualisieren Sie
reactundreact-dom, um den Next.js-Peer-Abhängigkeiten zu entsprechen (z. B. React 19 für Next.js 15). - Validierung: Führen Sie nach jedem inkrementellen Schritt
next devundnext buildaus. Überprüfen Sie die Konsolenfehler auf Hydrationswarnungen. - Berichterstattung: Melden Sie alle Codemod-Fehler oder manuell erforderlichen Korrekturen dem Team.
3. Abhängigkeitsaktualisierung
Aktualisieren Sie Next.js und die Peer-Abhängigkeiten synchron:
# Mit npm
npm install next@latest react@latest react-dom@latest
# TypeScript-Typen aktualisieren
npm install --save-dev @types/react@latest @types/react-dom@latest
4. Manuelle Überprüfungsregeln
- Asynchroner Kontext: Stellen Sie sicher, dass alle Verwendungen von
cookies(),headers()und Routen-paramsjetzt mitawaitabgerufen werden. - Metadaten: Stellen Sie sicher, dass die Typen von
generateMetadatamit der neuen asynchronenparams-Signatur übereinstimmen. - Caching: In v15+ verwendet
fetchstandardmäßig{ cache: 'no-store' }. Wenn Sie das alte Verhalten benötigen, setzen Sie explizit{ cache: 'force-cache' }.
5. Build-Test
- Führen Sie unmittelbar nach Codemods und Paketaktualisierungen
npm run buildaus. - Überprüfen Sie auf „Hydration failed“- oder „Turbopack“-Kompatibilitätsfehler, wenn Sie
--turboverwenden.
Anti-Patterns
- Keine Hauptversionen überspringen: Aktualisieren Sie jeweils nur eine Hauptversion (13→14, dann 14→15).
- Keine manuellen Breaking-Change-Korrekturen: Führen Sie zuerst immer
npx @next/codemod@latest <transform> <path>aus. - Kein angenommenes Caching-Verhalten nach dem Upgrade: v15 standardisiert auf
no-store; überprüfen Sie allefetch-Aufrufe. - Keine asynchronen Page-Funktionen im Pages Router:
export default async function Page()führt zu schwerwiegenden Fehlern.