## Introduction La mise à niveau de Node.js est une tâche opérationnelle récurrente qui impacte l'outillage de build, le comportement de l'application, la performance et la posture de sécurité. Bien exécutée, elle réduit les risques et débloque les fonctionnalités linguistiques modernes ainsi que les mises à jour de l'écosystème. Ce guide vous donne une méthode pratique, sans drame, pour planifier et exécuter des mises à niveau Node.js avec des commandes exécutables, des résultats attendus, des diagnostics et des chemins de rollback clairs. Les exemples supposent une pile API web typique (serveur Express, pilote MongoDB, client Redis optionnel), mais la méthode s'adapte à la plupart des services Node.js. Ce que vous obtiendrez : - Une approche d'inventaire de référence qui détecte les surprises tôt - Un chemin de configuration sûr avec épinglage de version et rayon d'impact réduit - Une mise à niveau étape par étape avec vérification et diagnostics - Des playbooks de récupération pour les casses courantes - Une liste de contrôle opérations réutilisable pour les futures mises à niveau Prérequis : - Accès shell à vos environnements de développement et de test - Permission d'installer ou de sélectionner des versions Node.js (nvm sur macOS/Linux ; un gestionnaire de versions équivalent ou un installeur sur Windows) - Une suite de tests fonctionnelle ou au minimum un endpoint de santé à sonder - Branching Git de base et capacité à restaurer un lockfile ## Inventaire des versions et de l'environnement Établir une ligne de base précise est la façon la plus rentable de réduire le risque de mise à niveau. Capturez les éléments suivants : ### Runtime et outillage - Enregistrez les versions Node.js et npm : node -v npm -v - Identifiez le gestionnaire de paquets utilisé (npm, yarn, pnpm). Utilisez un seul gestionnaire pendant la mise à niveau. - Confirmez les détails de l'OS (ex. : distribution Linux, version glibc) si vous utilisez des modules natifs. ### Application et dépendances - Notez la branche courante et créez une branche de mise à niveau dédiée, par exemple : upgrade/node20 - Faites un instantané de package.json et package-lock.json (ou yarn.lock / pnpm-lock.yaml ) - Listez les dépendances de premier niveau et leurs versions : npm ls --depth=0 - Identifiez les add-ons natifs (modules qui compilent) : - Cherchez les dépendances avec des scripts d'installation exécutant node-gyp ou prebuild - Recherchez des fichiers binding.gyp ### Environnement et topologie - Enregistrez les variables d'environnement utilisées par le service, surtout NODE_ENV et toute variable liée à TLS - Enregistrez les services externes : URI MongoDB, hôte/port Redis, APIs amont utilisées par votre app - Identifiez un chemin pilote étroit et à faible risque (un seul service, un seul endpoint, ou un seul job) pour tester la mise à niveau Tableau de référence pour choisir une portée et anticiper les changements de runtime :
Node cibleChangements clés à considérerNotes de risque
16 -> 18fetch disponible, mises à jour OpenSSL, sauts V8Reconstruction modules natifs, décalage défauts TLS
18 -> 20Test runner disponible, drapeaux permission (expérimental), raffinements URL/streamCas limites ESM/CJS, avertissements plus stricts
20 -> 22Mises à jour performance et V8, dépréciations runtime qui avancentAPIs legacy retirées ; auditer les dépréciations
## Chemin de configuration sûr Votre objectif : un changement contrôlé, observable, avec rollback facile. Appliquez ces choix avant de toucher au code : ### Choisissez la version cible délibérément - Préférez le LTS actif actuel pour les apps en production - Si vous êtes sur un LTS plus ancien, planifiez un saut en une seule étape quand possible (par exemple, 16 -> 20) plutôt que de passer par chaque version intermédiaire, sauf si des blocages forcent une étape intermédiaire ### Isolez le rayon d'impact - Utilisez un feature flag ou une méthode de gating de route pour tester un seul endpoint ou job d'arrière-plan en premier - Exécutez la nouvelle version Node.js côte à côte en développement et test, ne promouvez que quand les checks sont verts ### Épinglez et enregistrez les versions - Ajoutez ou mettez à jour .nvmrc avec votre version majeure cible (par exemple, 20 ) - Dans package.json , définissez un champ engines pour communiquer les attentes de runtime : { "engines": { "node": ">=20 <21" }, "engineStrict": false } Mettez engineStrict à true seulement si votre gestionnaire de paquets et la politique de l'organisation exigent une application stricte. ### Protégez-vous avec un point de départ propre et réversible - Commitez le lockfile actuel et la suppression de node_modules comme un seul changement seulement lors du basculement entre majeures Node.js - Gardez la mise à niveau dans une branche dédiée pour éviter de mélanger des changements non liés ## Parcours de mise à niveau pratique Cet exemple suppose macOS/Linux avec nvm. Sur Windows, utilisez un outil comparable (par exemple, nvs ou un installeur de confiance) et des commandes similaires. ### Créez la branche et confirmez la ligne de base git checkout -b upgrade/node20 node -v npm -v npm ci npm test Résultat attendu : tous les tests verts, l'app démarre sans nouveaux avertissements. ### Installez et sélectionnez le Node.js cible nvm install 20 --latest-npm nvm use 20 node -v npm -v echo "20" > .nvmrc Résultat attendu : le shell utilise le nouveau Node 20 ; .nvmrc communique votre intention aux autres développeurs. ### Rafraîchissez dépendances et lockfile sous le nouveau runtime rm -rf node_modules rm -f package-lock.json npm install npm ls --depth=0 Résultat attendu : un lockfile frais reflète les mises à jour de dépendances transitives compilées contre Node 20, incluant tout module natif. ### Reconstruisez ou vérifiez les add-ons natifs (s'il y en a) npm rebuild Sur les systèmes nécessitant des outils de build, assurez-vous que les prérequis sont présents (par exemple, Python et une chaîne d'outils C/C++) si des modules natifs existent. Résultat attendu : pas d'échecs de build depuis node-gyp ou prebuild ; artefacts compilés présents dans node_modules . ### Adressez les différences ESM/CJS et bibliothèque standard Si vous utilisez ESM ("type": "module\)), privilégiez les imports ESM natifs : // Avant (CommonJS) const fs = require('fs/promises'); // Après (ESM) import fs from 'node:fs/promises'; Si une dépendance est ESM-only et que vous utilisez CommonJS, vous pouvez voir ERR_REQUIRE_ESM . Options : - Convertissez votre fichier en ESM (renommez en .mjs ou définissez "type": "module\)) et utilisez import - Chargez le module via import() dynamique dans les contextes CommonJS ### Démarrez le service avec drapeaux diagnostiques pour attraper les problèmes tôt NODE_OPTIONS="--trace-warnings --trace-deprecation" npm start Résultat attendu : l'app démarre ; toute API dépréciée est loguée avec traces de pile pour guider les correctifs. ### Exemple : API Express avec MongoDB et Redis // server.js (Express) import express from 'express'; import { MongoClient } from 'mongodb'; import { createClient as createRedisClient } from 'redis'; const app = express(); const mongo = new MongoClient(process.env.MONGO_URI); const redis = createRedisClient({ url: process.env.REDIS_URL }); app.get('/health', async (req, res) => { try { await mongo.db('admin').command({ ping: 1 }); await redis.ping(); res.json({ ok: true, node: process.version }); } catch (err) { res.status(500).json({ ok: false, error: String(err) }); } }); const port = process.env.PORT || 3000; app.listen(port, () => console.log(`listening on ${port}`)); Démarrez l'app et sondez la santé : npm start curl -sf http://localhost:3000/health | jq Résultat attendu : JSON montre ok: true et node: v20.x . Si les connexions échouent, vos logs de service devraient fournir des traces de pile ; confirmez les URIs et identifiants dans les variables d'environnement. ## Vérification et diagnostics La vérification confirme que le nouveau runtime se comporte comme attendu sur les chemins de code qui vous importent. Utilisez des checks explicites avec sortie observable. Checks recommandés et résultats attendus :
CheckCommandeRésultat attendu
Version runtimenode -vAffiche v20.x (cible)
Santé gestionnaire paquetsnpm -v && npm doctorVersion npm récente ; doctor signale aucun problème critique
Install proprenpm ci (pre-upgrade), npm install (post-upgrade)Arbre de dépendances déterministe ; pas de pics audit/sévérité
Rebuild natifnpm rebuildPas d'erreurs de build ; deps natifs présents
Tests unitaires/intégrationnpm testTous tests verts ; pas de nouveaux tests flaky
Démarrage serviceNODE_OPTIONS="--trace-warnings --trace-deprecation" npm startDémarre proprement ; avertissements actionnables
Endpoint santécurl -sf http://localhost:3000/healthHTTP 200 ; JSON ok: true ; node signale version cible
Diagnostics additionnels à considérer : - Activez le logging verbeux de vos clients MongoDB et Redis temporairement pour repérer timeouts subtils ou changements d'authentification - Utilisez process.report (si disponible) pour générer des rapports diagnostiques lors de crashes natifs - Exécutez un petit test de charge localement (par exemple, frapper un seul endpoint à rythme soutenu) pour attraper blocages de boucle d'événements ou problèmes de backpressure ## Modes d'échec et récupération Problèmes courants après une mise à niveau majeure Node.js et comment les résoudre ou faire rollback proprement : ### Échecs de build de modules natifs - Symptôme : erreurs node-gyp , chaîne de compilation manquante, ou binaires préconstruits incompatibles - Correctif : installez les outils de build nécessaires ; mettez à jour la dépendance fautive vers une version supportant votre Node.js cible ; en palliatif, épinglez à une version compatible - Rollback : basculez vers le Node.js précédent via le gestionnaire de versions et restaurez le lockfile antérieur ### Incompatibilités TLS/crypto - Symptôme : échecs de handshake TLS en se connectant aux services ; erreurs mentionnant OpenSSL - Correctif : mettez à jour la bibliothèque cliente vers des versions testées avec votre Node.js cible ; vérifiez les suites de chiffrement et versions TLS minimales attendues par les serveurs - Rollback : revenez au runtime et lockfile précédents ; confirmez que les connexions précédentes fonctionnent ### Erreurs de frontière ESM/CJS ( ERR_REQUIRE_ESM ou ERR_MODULE_NOT_FOUND ) - Symptôme : impossible de charger des packages ESM-only depuis des modules CommonJS - Correctif : convertissez les points d'entrée en ESM, ou utilisez import() dynamique là où nécessaire ; assurez-vous que "type": "module" est défini appropriément - Rollback : annulez changements et runtime ; planifiez un refactor ciblé ### Dépréciations devenant erreurs - Symptôme : APIs dépréciées auparavant fonctionnelles lancent maintenant des erreurs ou se comportent différemment - Correctif : remplacez les APIs dépréciées ; inspectez la sortie --trace-deprecation pour localiser les piles - Rollback : épinglez au runtime précédent pendant l'implémentation des remplacements ### Régressions de performance sous charges spécifiques - Symptôme : latence ou CPU plus élevés après mise à niveau - Correctif : capturez profils CPU et logs GC ; vérifiez les chemins chauds pour I/O synchrone ou boucles serrées ; validez que les mises à jour de dépendances n'ont pas changé les défauts (ex. : pooling) - Rollback : revenez en arrière pendant que vous isolez la régression ; essayez de mettre à jour seulement le runtime ou seulement certaines bibliothèques pour bisecter la cause ### Procédure de récupération # Arrêtez l'instance(s) mise(s) à niveau nvm use 18 # Ou votre commutateur de version équivalent git checkout HEAD -- package-lock.json rm -rf node_modules npm ci npm start Vérification après rollback : - node -v affiche la version précédente - Tests et checks de santé passent comme avant - Logs ne montrent pas de nouveaux avertissements introduits par la tentative échouée ## Liste de contrôle opérations Utilisez cette liste pour répéter le processus sur plusieurs services avec un minimum de retravail : ### Planification et inventaire - Identifiez le LTS cible et le plus petit pilote précieux (un service ou endpoint) - Enregistrez les versions Node.js et npm actuelles ; confirmez un seul gestionnaire de paquets - Faites un instantané de package.json et lockfile ; listez les dépendances de premier niveau - Notez les modules natifs et outils de build requis ### Préparation de l'environnement - Créez la branche de mise à niveau - Installez le Node.js cible via un gestionnaire de versions ; mettez à jour .nvmrc - Épinglez engines dans package.json si votre politique l'exige ### Exécution - npm ci sur l'ancien runtime pour confirmer une ligne de base propre - Basculez vers le nouveau runtime ; supprimez node_modules et lockfile ; lancez npm install - npm rebuild pour les modules natifs - Démarrez l'app avec NODE_OPTIONS="--trace-warnings --trace-deprecation" - Ajustez l'usage import/require ESM/CJS là où nécessaire ### Vérification - Lancez les tests (unitaires, intégration) - Frappez les endpoints de santé et inspectez les logs - Optionnellement, lancez un test de charge léger sur un seul endpoint ### Décision et déploiement - Si vert : mergez et planifiez une promotion contrôlée vers les environnements supérieurs - Si problèmes : corrigez en avant si petit et bien compris ; sinon rollback propre et documentez le blocage ### Rollback - Revenez à la version Node.js précédente - Restaurez le dernier lockfile connu bon ; npm ci - Relancez santé et tests pour confirmer la récupération ## Conclusion Vous avez maintenant une méthode pratique pour mettre à niveau Node.js : établissez une ligne de base précise, isolez un pilote petit mais représentatif, avancez délibérément avec épinglage de version et lockfiles propres, vérifiez avec des checks observables, et gardez le rollback simple et rapide. La même méthode s'échelonne à un portefeuille de services : répétez la liste de contrôle, capturez les leçons par service (modules natifs, frontières ESM, défauts TLS), et standardisez sur un LTS cible pour la cohérence. En cas de doute, gardez le pilote étroit, rendez les résultats mesurables, et n'élargissez le rayon d'impact que quand les preuves montrent que la mise à niveau est sûre.