Comment NVM gère-t-il plusieurs versions de Node.js ? Méthode de bascule entre les environnements de développement Node 18, 20, 22 et 24 et problèmes courants

Installer les versions nécessaires, sélectionner celle du projet avec nvm use, puis vérifier à la fois node -v et le chemin de node : c’est la méthode fiable pour éviter qu’un terminal exécute une autre version que celle attendue. Elle concerne nvm-sh sur macOS et Linux ; sous Windows, l’implémentation NVM est différente et ses commandes ne doivent pas être transposées à l’identique.

Cet article s’adresse aux développeurs qui maintiennent des projets utilisant des versions différentes de Node.js, à ceux qui vérifient la compatibilité des versions 18, 20, 22 et 24, ainsi qu’aux personnes qui travaillent dans un terminal Mac distant et doivent diagnostiquer une bascule qui n’a pas pris effet.

Dernière mise à jour : 15 octobre 2026 ; état des versions vérifié dans les pages officielles de publication et de fin de vie de Node.js. (nodejs.org)

NVM pour gérer plusieurs versions de Node.js sur macOS

Le premier choix consiste à utiliser l’implémentation correspondant au système et au shell, plutôt qu’à traiter « NVM » comme un programme identique partout. Le projet nvm-sh est un script destiné aux shells compatibles POSIX, notamment ceux utilisés sur macOS et Linux. L’implémentation NVM for Windows est un projet distinct : son fonctionnement, ses réglages et ses limites ne se confondent pas avec ceux de nvm-sh.

Sur un Mac, il est donc généralement cohérent d’utiliser nvm-sh et de charger NVM depuis le fichier de configuration du shell. Dans un environnement Windows, les commandes doivent être vérifiées dans la documentation NVM for Windows. Cette distinction est importante en équipe : un fichier .nvmrc partagé peut être compris par nvm-sh, mais ne garantit pas que chaque outil ou shell tiers change automatiquement de version en entrant dans le dossier.

Voici un repère comparatif pour choisir une méthode. La note est une appréciation éditoriale pour un poste ou un environnement de développement Mac distant, fondée sur la documentation des projets — ce n’est ni un résultat de performance ni une mesure de compatibilité universelle.

Un autre critère est l’état de maintenance de chaque version. Au 15 octobre 2026, la page officielle de Node.js classe les versions 18 et 20 comme arrivées en fin de vie, tandis que les branches 22 et 24 sont indiquées comme LTS. Une branche en fin de vie peut rester nécessaire pour reproduire un ancien projet ou vérifier une migration, mais ne doit pas être assimilée à un choix conseillé pour un nouveau déploiement sans évaluation des risques. Consultez les statuts de publication Node.js et les informations officielles sur les versions en fin de vie avant de fixer une politique de mise à niveau.

Installation et contrôle des versions

Sur macOS ou Linux, les commandes suivantes supposent que nvm-sh est installé et chargé dans le shell. Son guide officiel décrit l’installation ainsi que le chargement depuis les fichiers de configuration ; il convient de suivre sa procédure à jour plutôt que de recopier un script d’installation ancien trouvé dans un tutoriel. Après installation, command -v nvm doit reconnaître la fonction. which nvm n’est pas un contrôle équivalent, car nvm-sh est chargé comme fonction du shell et non comme exécutable autonome.

Pour ajouter les quatre branches concernées, ouvrez un terminal où NVM est accessible et exécutez les commandes nécessaires :

nvm install 18
nvm install 20
nvm install 22
nvm install 24

Un numéro majeur demande la version correspondante de la branche disponible auprès de NVM ; il ne fixe pas, à lui seul, un numéro de correctif déterminé pour toujours. Pour reproduire un environnement de livraison de façon stricte, utilisez le numéro complet exigé par le projet et conservez le fichier de verrouillage des dépendances correspondant. Les archives officielles de Node.js permettent de vérifier les versions publiées et les fichiers disponibles pour les systèmes et architectures visés ; par exemple, l’archive de la branche 24 liste les versions et leurs artefacts.

Après les installations, contrôlez l’inventaire et la version active :

nvm ls
nvm current
node -v
npm -v

nvm ls permet de distinguer les versions installées de la version active dans le shell courant ; node -v et npm -v montrent ce que les commandes lancent effectivement. Si une installation échoue, ne concluez pas immédiatement que le numéro majeur n’existe pas : vérifiez d’abord le système, l’architecture et l’accès aux fichiers de distribution attendus par la version ciblée. La page officielle de publication est la référence pour vérifier l’état de la branche, pas une hypothèse fondée sur le seul numéro annoncé dans un projet.

L’installation de plusieurs branches consomme aussi de l’espace disque, et les paquets globaux ne sont pas nécessairement partagés entre elles. Un outil installé avec npm install -g appartient à l’environnement de la version Node active au moment de l’installation ; après bascule, il peut ne plus apparaître dans le chemin de recherche de l’autre version. La documentation npm décrit l’installation globale comme un mode d’installation d’outils sur la machine, tandis que nvm-sh gère les installations de Node séparément. Pour un outil réellement requis par le projet, une dépendance locale et un script de paquet sont souvent plus faciles à reproduire qu’une installation globale implicite.

Sélection de la version et valeur par défaut

La bascule de nvm use s’applique au shell courant : elle ne remplace pas automatiquement la version dans tous les onglets, tous les processus déjà lancés ou toutes les fenêtres d’un éditeur. Depuis le répertoire du projet, sélectionnez la branche voulue, puis vérifiez les commandes dans ce même terminal :

nvm use 18
node -v
command -v node

Pour passer d’un projet exigeant la version 18 à un autre qui utilise la version 22, relancez nvm use 22 dans le second terminal ou après vous être déplacé dans son répertoire. La vérification du chemin compte autant que celle du numéro : si node -v indique une version inattendue ou si le chemin pointe vers une installation système, le shell peut résoudre une autre commande avant celle gérée par NVM.

La version par défaut sert de point de départ aux nouveaux shells lorsqu’aucun projet ne demande explicitement une autre version. Avec nvm-sh, elle peut être définie ainsi :

nvm alias default 22

Cette valeur ne remplace pas un choix explicite effectué ensuite dans le shell et ne doit pas être confondue avec la version inscrite dans un fichier .nvmrc. Pour tester le réglage, ouvrez un nouveau terminal plutôt que de vous fier uniquement à celui où la commande vient d’être exécutée :

nvm current
node -v
command -v node

Si le nouveau shell ne charge pas NVM, l’alias ne peut pas déterminer le résultat de node dans ce shell. La priorité est alors de corriger l’initialisation du shell avant de multiplier les changements de version par défaut.

Association d’une version à chaque projet

Un fichier .nvmrc placé à la racine d’un projet consigne la version demandée par le projet. Il rend le choix visible dans le dépôt et réduit les erreurs lorsque plusieurs applications utilisent des branches différentes. Pour un projet qui doit tester la branche 20, le fichier peut contenir :

20

Depuis le dossier du projet, nvm-sh permet ensuite de demander la version indiquée par le fichier :

nvm use

Si cette version n’est pas encore installée, nvm install lancé depuis le même dossier peut installer la version prescrite par le fichier, puis l’activer. Pour une équipe qui exige une reproduction à l’identique, le fichier peut aussi contenir une version complète plutôt qu’un numéro majeur ; la politique doit correspondre à la façon dont le projet veut gérer les mises à jour de correctifs. Les règles de lecture de .nvmrc et les commandes concernées sont détaillées dans le guide officiel de nvm-sh.

La présence du fichier ne signifie pas que chaque terminal changera de version dès l’ouverture du dossier. Avec nvm-sh, l’appel explicite à nvm use est le comportement à retenir ; la commutation automatique lors d’un cd est une intégration supplémentaire au shell, documentée comme une configuration à ajouter. Cette nuance évite un piège fréquent : une configuration locale qui fonctionne dans un terminal interactif peut ne pas être chargée par un terminal intégré, un processus automatisé ou une session distante non interactive.

Une procédure d’équipe vérifiable consiste à versionner .nvmrc, documenter la commande de sélection dans le README technique du dépôt et faire afficher node -v dans les vérifications de démarrage ou d’intégration continue. Pour vérifier une compatibilité entre branches, exécutez la même suite de tests dans des environnements séparés, en conservant les fichiers de verrouillage et les commandes de construction du projet. Le résultat indique alors si un écart provient du runtime ou d’une modification accidentelle des dépendances.

Diagnostic des changements sans effet

Quand node -v reste inchangé après une commande de bascule, le diagnostic doit suivre l’ordre de résolution réel des commandes. Changer plusieurs fichiers de configuration en même temps rend plus difficile l’identification de la cause ; mieux vaut commencer par l’état du shell courant, puis examiner son initialisation et son chemin d’accès.

1. Confirmer que NVM est chargé. Dans le terminal concerné, exécutez command -v nvm. Si la commande ne renvoie rien, rechargez le fichier de démarrage utilisé par ce shell ou ouvrez un nouvel onglet. Sur macOS, nvm-sh signale notamment les cas où le shell utilise zsh mais où le fichier .zshrc n’existe pas ou ne charge pas NVM. Vérifiez la configuration réellement utilisée au lieu d’ajouter des lignes au hasard dans plusieurs fichiers.
2. Sélectionner la version dans ce terminal. Lancez nvm use 22 ou, depuis un projet correctement configuré, nvm use. Une bascule dans un terminal n’active pas nécessairement le même environnement dans un autre onglet.
3. Contrôler la résolution de la commande. Utilisez command -v node, puis type -a node dans les shells qui acceptent cette commande. Sur macOS et Linux, which -a node peut aussi aider à repérer plusieurs installations, mais le contrôle décisif reste le chemin réellement retourné dans le shell où l’application est lancée.
4. Inspecter le résultat du chemin et des versions. node -p "process.execPath" affiche le chemin de l’exécutable utilisé par Node.js. Comparez-le avec nvm which current, puis vérifiez node -v et npm -v. Si ces valeurs ne concordent pas, recherchez une installation système ou un autre gestionnaire qui précède le chemin NVM dans PATH.
5. Vérifier les outils globaux séparément. Après la bascule, contrôlez un outil attendu avec command -v et, si nécessaire, inspectez les paquets globaux avec npm ls -g --depth=0. Un outil absent peut simplement ne pas être installé pour la version actuellement sélectionnée ; ce constat ne prouve pas que le changement de Node a échoué.

Sur macOS, vérifiez aussi que le terminal et le processus de développement utilisent le même shell et le même utilisateur. Une session SSH, un terminal intégré à l’éditeur et une fenêtre interactive peuvent charger des fichiers différents ; un NVM présent dans un shell n’est donc pas automatiquement visible dans les autres.

Si l’environnement est Windows, ne corrigez pas les variables de nvm-sh dans les fichiers zsh ou bash en espérant réparer NVM for Windows. Cette implémentation utilise notamment un lien symbolique configuré dans le système ; la documentation de dépannage mentionne les conflits de chemin ou les liens invalides parmi les causes d’échec de nvm use. Suivez alors les contrôles propres à NVM for Windows et à ses problèmes courants, sans appliquer ces réglages au Mac.

Vérification dans un environnement Mac distant

Dans un Mac distant, la validation doit être effectuée dans l’environnement où le projet s’exécutera réellement, et non seulement dans un terminal local. Une session SSH, une fenêtre de terminal et un processus de construction peuvent ne pas charger la même configuration. Le contrôle doit donc relier le répertoire du projet, le shell actif, la version déclarée et la commande résolue.

La séquence de vérification suivante est reproductible et ne dépend pas d’une configuration particulière fournie par un hébergeur :

cd /chemin/du/projet
command -v nvm
nvm use
cat .nvmrc
node -v
npm -v
command -v node
node -p "process.execPath"

Si .nvmrc est absent, la commande nvm use ne peut pas y lire de version : sélectionnez alors explicitement la version documentée par le projet et envisagez d’ajouter le fichier au dépôt. Si le fichier existe, comparez son contenu avec la version affichée par node -v. Dans les deux cas, vérifiez le chemin d’exécution avant de lancer des tests, notamment si la session distante démarre un shell non interactif.

Répétez la procédure pour chaque branche dont la compatibilité doit être testée, en gardant les résultats séparés par projet et par version. Par exemple, la présence de plusieurs versions installées ne prouve pas que le terminal a basculé sur la bonne : il faut relever, dans le même contexte de travail, le contenu de .nvmrc, la sortie de node -v et process.execPath. Il n’existe ici aucune mesure propre à un nœud distant Zilmac ; les commandes décrivent une méthode de contrôle, pas une affirmation sur une configuration ou une performance de service.

Pour examiner si un environnement distant correspond aux besoins du dépôt, consultez la page de location de Mac dans le nuage et les informations tarifaires Mac disponibles ; vérifiez sur ces pages les détails réellement publiés avant de décider. Ce contrôle est particulièrement utile lorsque les tests dépendent de l’architecture, des outils présents ou d’un shell initialisé différemment.

FAQ sur les versions Node.js et NVM

Version active différente de la version par défaut. C’est possible si un shell a déjà exécuté nvm use ou si un fichier .nvmrc indique une autre version. Vérifiez nvm current dans le terminal concerné, puis comparez avec la valeur déclarée par le projet. La version par défaut est un réglage de départ pour un nouveau shell, pas une consigne qui annule tous les choix locaux.

Commande NVM introuvable après l’installation. Dans le même terminal, testez command -v nvm. Si le résultat est vide, rechargez le fichier de configuration effectivement utilisé par le shell ou ouvrez une nouvelle session. Vérifiez que l’initialisation de NVM se trouve dans le fichier adéquat pour zsh ou bash. Sur un Mac distant, le fichier chargé par SSH peut différer de celui du terminal graphique.

Projet ancien qui exige une branche en fin de vie. Une telle branche peut être nécessaire pour reproduire un comportement ou isoler une migration, mais la documentation officielle signale que les versions en fin de vie ne reçoivent plus le même suivi. Réservez-les à la vérification ciblée, évaluez les dépendances et planifiez le passage à une branche maintenue lorsque les contraintes du projet le permettent.

Outil global absent après la bascule. Contrôlez command -v outil et la liste globale npm avec npm ls -g --depth=0. Si l’outil n’est pas présent dans l’environnement Node actif, installez-le pour cette version ou déplacez-le vers les dépendances locales du projet lorsque son usage doit être partagé avec l’équipe.

Avant chaque lancement, la vérification tient en trois contrôles : la version requise par le projet, la version active dans le terminal qui exécutera les commandes, puis le chemin réellement retourné pour node. Une installation locale reste préférable lorsqu’un poste dédié doit conserver un environnement stable et dispose des interfaces physiques nécessaires ; en revanche, elle peut obliger à maintenir une machine distincte et ne résout pas à elle seule les écarts entre shells. Si ces limites comptent et qu’un Mac distant est nécessaire pour un test ou un cycle de développement ponctuel, la location d’un Mac via Zilmac peut éviter l’achat d’une machine réservée à cette tâche. Vérifiez d’abord les caractéristiques effectivement indiquées sur les pages du service, puis refaites la séquence de validation dans le shell distant avant d’y confier le projet.

• Découvrez comment choisir un environnement de développement reproductible avec un Dev Container.
• Comparez les environnements locaux, distants et la CI pour exécuter les tâches de développement.