Protocole de mise à niveau Next.js
Étapes de migration automatisées et manuelles pour les mises à niveau de version Next.js (p. ex., v14 → v15).
Priorité : P1 (OPÉRATIONNEL)
Consignes d'implémentation
- Détection de mise à niveau : Vérifier toujours
package.jsonpour les versions denext,react, etreact-dom. - Planification : Pour les sauts de version majeure (v13 vers v15), effectuer une mise à niveau incrémentielle (v13 → v14, puis v14 → v15). Suivre les Guides de migration Next.js officiels.
- Codemods automatisés : Utiliser
npx @next/codemod@latest <transform> <path>pour automatiser la migration de syntaxe. - Changements cassants (v15) : Répondre à la transformation
next-async-request-apien s'assurant queparams,searchParams,cookies()etheaders()sont attendus (await). - Parité React : Mettre à niveau
reactetreact-dompour correspondre aux dépendances pairs de Next.js (p. ex., React 19 pour Next.js 15). - Validation : Exécuter
next devetnext buildaprès chaque étape incrémentielle. Vérifier les erreurs de console pour les avertissements d'hydratation. - Rapport : Signaler tous les échecs de codemod ou correctifs manuels nécessaires à l'équipe.
3. Mise à jour des dépendances
Mettre à niveau Next.js et les dépendances pairs de manière synchronisée :
# Avec npm
npm install next@latest react@latest react-dom@latest
# Mettre à jour les types
npm install --save-dev @types/react@latest @types/react-dom@latest
4. Règles de vérification manuelle
- Contexte asynchrone : Vérifier que toutes les utilisations de
cookies(),headers(), et les paramètres de routeparamssont maintenant attendues (await). - Métadonnées : S'assurer que les types de
generateMetadatacorrespondent à la nouvelle signature asynchrone deparams. - Mise en cache : Dans v15+,
fetchutilise par défaut{ cache: 'no-store' }. Si vous avez besoin de l'ancien comportement, définissez explicitement{ cache: 'force-cache' }.
5. Test de construction
- Exécuter
npm run buildimmédiatement après les codemods et les mises à jour de paquets. - Vérifier les erreurs "Hydration failed" ou de compatibilité "Turbopack" si vous utilisez
--turbo.
Anti-patrons
- Ne pas sauter de version majeure : Mettre à niveau une version majeure à la fois (13→14, puis 14→15).
- Ne pas appliquer de correctifs manuels pour les changements cassants : Toujours exécuter les transformations
npx @next/codemod@latesten premier. - Ne pas supposer un comportement de mise en cache après la mise à niveau : v15 utilise par défaut
no-store; auditer tous les appelsfetch. - Ne pas utiliser de fonctions de page asynchrones dans le Pages Router :
export default async function Page()est fatal.