Pour trouver la version de Node.js attendue par un projet sur votre Mac, inspectez ses fichiers de version et sa configuration avant de vérifier la version active dans le Terminal. Commencez par .nvmrc, puis vérifiez les paramètres volta et engines dans package.json. Ces indices ont des significations différentes : certains fixent une version pour un outil, tandis que d'autres décrivent une plage de compatibilité.

1. Ouvrir le dossier du projet dans le Terminal

Dans le Finder, localisez le dossier du projet. Faites un clic avec la touche Contrôle enfoncée et choisissez Nouveau terminal au dossier si cette option est disponible ; sinon, ouvrez le Terminal et accédez au dossier avec cd. Vous pouvez faire glisser le dossier depuis le Finder dans la fenêtre du Terminal après avoir tapé cd , puis appuyer sur Entrée. Cela évite de taper incorrectement un chemin contenant des espaces.

Exécutez ces commandes en lecture seule depuis le répertoire du projet :

ls -a
grep -nE '"(engines|volta)"|"node"' package.json .nvmrc

ls -a inclut les fichiers masqués tels que .nvmrc. grep affiche les lignes correspondantes des fichiers existants ; si un fichier est absent, il peut afficher une erreur pour ce fichier, ce qui ne signifie pas que le projet est défectueux. Pour inspecter un fichier particulier de manière plus détaillée, utilisez sed -n '1,160p' package.json ou sed -n '1,20p' .nvmrc lorsque le fichier existe. Ces commandes affichent du texte ; elles ne modifient pas le projet.

2. Lire .nvmrc comme une instruction pour le gestionnaire de versions

Si vous trouvez .nvmrc, lisez son contenu. Une valeur telle que 20.16.0 indique que le projet spécifie cette version de Node.js pour les utilisateurs de nvm. nvm accepte également des sélecteurs de version tels que 20 ou lts/*, le fichier peut donc ne pas identifier une version de correctif fixe. La documentation de nvm indique que ses commandes peuvent trouver .nvmrc dans le répertoire du projet ou dans un répertoire parent, et que nvm use sans version utilise le fichier lorsqu'il est disponible. README de nvm : .nvmrc

Sur macOS, vérifiez si nvm est disponible et quelle version il résout dans ce répertoire :

command -v nvm
nvm use
node --version

command -v nvm devrait afficher nvm lorsque nvm est chargé dans le shell actuel. Si la commande n'est pas disponible, ne présumez pas que .nvmrc est invalide ; le fichier peut tout de même documenter le choix du projet même si nvm n'est pas installé ou chargé. nvm use sélectionne la version indiquée dans le fichier si elle est installée ; si elle est absente, nvm peut vous inviter à l'installer. Ne lancez une installation que si vous avez l'intention d'ajouter cette version de Node à votre Mac.

3. Vérifier package.json pour Volta et les plages de compatibilité

Recherchez un objet volta de premier niveau. Par exemple :

"volta": {
  "node": "20.16.0"
}

Il s'agit d'un verrouillage de version de Node pour les projets gérés avec Volta. La documentation de Volta indique que volta pin enregistre les versions des outils sélectionnés dans package.json, et que Volta redirige les commandes Node vers la version du projet. Comprendre Volta Si vous utilisez Volta, node --version depuis le répertoire du projet peut indiquer quelle version la chaîne d'outils exécute ; sans Volta, l'objet reste une métadonnée du projet, et non une commande pour le Terminal macOS.

Inspectez également la propriété engines, généralement écrite ainsi :

"engines": {
  "node": ">=18 <23"
}

Cela indique une plage de compatibilité, pas nécessairement la version installée par les développeurs. La documentation de npm décrit engines.node comme spécifiant les versions de Node avec lesquelles un paquet fonctionne ; à moins que engine-strict ne soit activé, npm traite cela comme un simple avertissement lors de l'installation des dépendances. Documentation package.json de npm Une plage étendue signifie que le projet revendique une compatibilité sur l'ensemble des versions autorisées ; cela ne définit pas une version attendue exacte.

4. Comparer les fichiers et résoudre les indices contradictoires

Considérez un .nvmrc exact ou un verrouillage Volta comme l'indice le plus fort d'une version particulière gérée par un outil. Considérez engines.node comme une contrainte de compatibilité. Si les fichiers sont en désaccord (par exemple, .nvmrc indique 18 mais engines.node requiert >=20), n'en choisissez pas un silencieusement. Les fichiers peuvent être obsolètes, servir différents outils ou refléter une modification récente. Consultez le fichier README et les instructions de configuration du projet, puis demandez aux responsables ou à l'équipe quel fichier les contributeurs sont censés suivre.

Les projets peuvent également définir des versions dans des fichiers utilisés par d'autres gestionnaires de versions ou dans la configuration d'intégration continue (CI). Si .nvmrc et package.json ne fournissent aucune réponse utile, recherchez les fichiers de projet visibles avec ls -a et inspectez la documentation d'installation ainsi que la configuration des workflows. Un fichier de CI peut indiquer la version utilisée pour les builds automatisés, mais celle-ci peut différer de la configuration de développement locale ; confirmez le contexte avant de la considérer comme l'exigence du projet.

5. Vérifier la version de Node que votre Mac utilise réellement

Après avoir identifié l'instruction du projet, comparez-la avec l'environnement d'exécution actif :

node --version
command -v node

La première commande indique la version active de Node ; la seconde montre le chemin de l'exécutable sélectionné via la variable PATH de votre shell. Celles-ci décrivent votre environnement Terminal actuel, et non l'exigence du projet en soi. Avec nvm, exécutez nvm use depuis le répertoire du projet avant de vérifier. Avec Volta, lancez les vérifications depuis ce répertoire afin que les paramètres de son projet puissent s'appliquer. Si la version signalée diffère toujours du verrouillage, le gestionnaire concerné n'est peut-être pas installé, chargé ou en train de contrôler l'exécutable node dans ce shell.

La réponse pratique consiste à examiner les deux côtés : la déclaration de version du dépôt indique ce qu'il demande, tandis que node --version indique ce que votre Mac exécute actuellement. Si ces éléments ne correspondent pas, configurez le gestionnaire ou l'instruction du projet avant de vous fier aux résultats locaux.

Sources