Installation de Node.js

Ce guide explique comment installer Node.js sous Windows, macOS et Linux. Les versions Desktop et Microsoft Store n’embarquent plus Node.js : elles utilisent directement les commandes node et npm de votre système, dont dépendent aussi OpenSpec et la plupart des Agent CLI.

Version requise

Node.js 24 ou supérieur est requis, et le minimum est lui aussi 24. En général, il suffit d’installer la dernière version LTS. npm est installé avec Node.js, il n’y a pas besoin de l’installer séparément.

Quelles méthodes d’installation en ont besoin

• Microsoft Store / Desktop : oui, et node et npm doivent être trouvables dans le PATH du système.

Installer Node.js

Windows

Première méthode : installateur officiel (recommandé)

1. Visitez le site officiel de Node.js
2. Téléchargez le programme d’installation Windows de la version LTS (Long Term Support) (fichier .msi) et vérifiez que le numéro de version n’est pas inférieur à 24
3. Double-cliquez pour exécuter le programme d’installation
4. Suivez les invites de l’assistant d’installation pour terminer l’installation :
   • Acceptez le contrat de licence
   • Choisissez le chemin d’installation (la valeur par défaut convient)
   • Laissez l’option « Add to PATH » cochée
   • Cliquez sur « Install » pour démarrer l’installation
5. Une fois l’installation terminée, cliquez sur « Finish »

Deuxième méthode : utiliser winget

Ouvrez PowerShell ou l’invite de commande et exécutez la commande suivante :

winget install OpenJS.NodeJS.LTS

Une fois l’installation terminée, rouvrez le terminal pour que les modifications prennent effet.

macOS

Première méthode : installateur officiel (recommandé)

1. Visitez le site officiel de Node.js
2. Téléchargez le programme d’installation macOS de la version LTS (Long Term Support) (fichier .pkg) et vérifiez que le numéro de version n’est pas inférieur à 24
3. Double-cliquez pour exécuter le programme d’installation
4. Suivez les invites de l’assistant d’installation pour terminer l’installation :
   • Cliquez sur « Continuer »
   • Acceptez le contrat de licence
   • Choisissez le disque d’installation
   • Cliquez sur « Installer » et saisissez le mot de passe administrateur
5. Une fois l’installation terminée, cliquez sur « Fermer »

Deuxième méthode : utiliser Homebrew

Si Homebrew est déjà installé, vous pouvez installer Node.js depuis le terminal :

brew install node

Homebrew ajoute automatiquement Node.js à votre PATH. Si la commande n’est pas disponible, redémarrez le terminal ou exécutez :

eval "$(/opt/homebrew/bin/brew shellenv)"

Ubuntu/Debian

Utiliser le dépôt NodeSource (recommandé)

Le Node.js des dépôts fournis avec la distribution est généralement inférieur à 24 ; utilisez le dépôt 24.x proposé par NodeSource :

# Télécharger le script d'installation avec curl
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

N’installez pas la version fournie par la distribution avec sudo apt-get install nodejs npm : elle ne satisfera très probablement pas le minimum requis de 24.

Si vous ne souhaitez pas ajouter de source logicielle tierce, vous pouvez aussi utiliser nvm ou fnm, présentés plus bas.

CentOS/RHEL

Utiliser le dépôt NodeSource (recommandé)

# Télécharger le script d'installation avec curl
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

Le Node.js des dépôts fournis avec la distribution est généralement inférieur à 24, il n’est donc pas recommandé de l’utiliser directement. Vous pouvez aussi utiliser nvm ou fnm, présentés plus bas.

Fedora

Utiliser le gestionnaire de paquets dnf

sudo dnf install -y nodejs npm

Après l’installation, exécutez node --version pour vérifier que la version n’est pas inférieure à 24. Si la version du dépôt est trop ancienne, utilisez le dépôt 24.x de NodeSource, ou nvm ou fnm, présentés plus bas.

Utilisation des outils de gestion des versions

Si vous devez basculer entre plusieurs versions de Node.js, vous pouvez utiliser un outil de gestion de versions.

Remarque pour les utilisateurs de Desktop

Sous macOS et Linux, des outils comme nvm ou fnm ne définissent généralement le PATH que dans les fichiers de configuration du shell (tels que .bashrc ou .zshrc). Desktop lancé depuis le Dock, le menu des applications ou une icône du bureau ne lit pas ces fichiers et risque de ne pas trouver node. Si vous utilisez un gestionnaire de versions, lancez Desktop depuis un terminal où node fonctionne déjà, ou utilisez plutôt l’installation au niveau du système décrite plus haut.

nvm (Node Version Manager)

Installer nvm

Linux/macOS

Copiez directement la dernière commande d’installation indiquée dans le README du dépôt officiel de nvm ; n’utilisez pas l’adresse d’un ancien script d’installation.

Une fois l’installation terminée, rechargez la configuration de votre shell :

source ~/.bashrc
# Ou pour les utilisateurs de Zsh
source ~/.zshrc

Windows

Sous Windows, nous recommandons d’utiliser nvm-windows :

1. Téléchargez le dernier nvm-setup.exe depuis les versions de nvm-windows
2. Exécutez le programme d’installation
3. Rouvrez l’invite de commande ou PowerShell

Utiliser nvm

Une fois nvm installé, vous pouvez l’utiliser pour installer et gérer les versions de Node.js :

# Installer Node.js 24
nvm install 24

# Passer à Node.js 24
nvm use 24

# Définir la version par défaut
nvm alias default 24

# Lister les versions installées
nvm list

La commande alias de nvm-windows n’est pas disponible ; nvm install 24 et nvm use 24 suffisent.

fnm (Fast Node Manager)

fnm est un gestionnaire de versions de Node.js plus rapide et plus simple, construit en Rust.

Installer fnm

Linux/macOS

# Installer avec curl
curl -fsSL https://fnm.vercel.app/install | bash

# Une fois l'installation terminée, recharger la configuration du shell
source ~/.bashrc
# Ou pour les utilisateurs de Zsh
source ~/.zshrc

Windows

Utilisez scoop ou winget :

# Avec scoop
scoop install fnm

# Ou avec winget
winget install Schniz.fnm

Utiliser fnm

# Installer Node.js 24
fnm install 24

# Passer à Node.js 24
fnm use 24

# Définir la version par défaut
fnm default 24

# Lister les versions installées
fnm list

Accélération pour les utilisateurs de Chine continentale

Si vous êtes en Chine continentale, le téléchargement de Node.js et des paquets npm peut être lent ; vous pouvez alors utiliser des miroirs nationaux.

Miroir npm

# Utiliser temporairement le miroir pour l'installation
npm install --registry=https://registry.npmmirror.com

# Définir le miroir de façon permanente
npm config set registry https://registry.npmmirror.com

# Vérifier que le miroir est bien configuré
npm config get registry

Miroir des programmes d’installation de Node.js

Les programmes d’installation de Node.js disposent aussi d’une adresse de téléchargement en miroir : https://npmmirror.com/mirrors/node/. Une fois sur le site, choisissez une version qui n’est pas inférieure à 24.

Miroir Homebrew

Si vous utilisez Homebrew en Chine continentale, vous pouvez configurer le miroir de l’USTC pour les bottles :

export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Vérification de l’installation

Une fois l’installation terminée, vérifiez que Node.js et npm sont disponibles dans un terminal nouvellement ouvert :

# Vérifier la version de Node.js, v24.0.0 ou supérieure requise
node --version

# Vérifier la version de npm
npm --version

Une sortie réussie ressemble à ceci :

$ node --version
v24.3.0

$ npm --version
11.4.2

Si node --version affiche une version inférieure à 24, réinstallez Node.js avec les méthodes ci-dessus, ou utilisez un gestionnaire de versions pour passer à la version 24 ou supérieure.

Configurer le répertoire global de npm

Desktop installe les paquets gérés, tels que les Agent CLI, dans le répertoire global de votre npm local. Si ce répertoire global se trouve dans un emplacement qui exige des droits d’administrateur, l’installation peut produire une erreur de permissions EACCES. Il est recommandé de déplacer le répertoire global dans votre répertoire utilisateur plutôt que de modifier les permissions d’un répertoire système :

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Ajoutez ensuite ~/.npm-global/bin (sous Windows, le répertoire global de npm lui-même) au PATH du système, puis redémarrez le terminal et Desktop. Avec nvm ou fnm, le répertoire global se trouve déjà dans votre répertoire utilisateur, cette étape est inutile.

Dépannage

Problèmes Windows

Commande indisponible

Si les commandes node ou npm ne sont pas disponibles après l’installation :

1. Redémarrez l’invite de commande ou PowerShell
2. Si elles restent indisponibles, ajoutez manuellement Node.js au PATH :
   • Recherchez « Variables d’environnement » et ouvrez « Modifier les variables d’environnement système »
   • Cliquez sur « Variables d’environnement »
   • Dans « Variables système », recherchez « Path » et cliquez sur « Modifier »
   • Ajoutez le chemin d’installation de Node.js (par défaut : C:\Program Files\nodejs\)
   • Cliquez sur « OK » pour enregistrer les modifications
3. Quittez complètement Desktop puis relancez-le

Stratégie d'exécution PowerShell

Si vous rencontrez des erreurs de stratégie d’exécution en utilisant nvm ou des scripts npm :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problèmes macOS

Erreurs de permissions

Si vous rencontrez des erreurs de permissions lors de l’installation de paquets npm globaux, reportez-vous à la section Configurer le répertoire global de npm ci-dessus, ou utilisez nvm / fnm.

Commande indisponible

Si la commande n’est pas disponible après l’installation, redémarrez le terminal et vérifiez que le répertoire de Node.js (généralement /usr/local/bin ou /opt/homebrew/bin) figure dans le PATH.

Problèmes Linux

Erreurs de permissions

Si vous rencontrez des erreurs de permissions lors de l’installation de paquets npm globaux, reportez-vous à la section Configurer le répertoire global de npm ci-dessus, ou utilisez nvm / fnm, plutôt que d’installer des paquets globaux avec sudo.

Version trop ancienne

Si la version de Node.js installée via le gestionnaire de paquets du système est inférieure à 24 :

1. Utilisez le dépôt 24.x de NodeSource (voir plus haut)
2. Ou utilisez un gestionnaire de versions (nvm / fnm)

Vérification de l’environnement

Si la vérification échoue, contrôlez les points suivants :

Windows

# Vérifier si Node.js est dans le PATH
where node

# Vérifier le chemin d'installation
Get-Command node

macOS

# Vérifier si Node.js est dans le PATH
which node

# Vérifier le chemin d'installation
ls -l $(which node)

Linux

# Vérifier si Node.js est dans le PATH
which node

# Vérifier le chemin d'installation
ls -l $(which node)

Étapes suivantes

Une fois l’installation de Node.js terminée, vous pouvez continuer avec les étapes suivantes :

Retour au guide d'installationTerminez les prérequis comme Git, puis choisissez la méthode d'installation qui vous convient.

Introduction à OpenSpecRendez-vous sur le site de documentation OpenSpec dédié pour découvrir l'installation, les concepts clés et le flux de travail piloté par les spécifications.

Installer un Agent CLI IAConsultez les points d'entrée d'installation officiels des Agent CLI actuellement pris en charge et distinguez l'installation en un clic de l'installation / authentification manuelle.

Besoin de plus d’aide ?

Si vous rencontrez des problèmes non abordés ici :

1. Visitez la documentation officielle de Node.js
2. Consultez Comment Desktop utilise votre environnement Node
3. Consultez la présentation du produit HagiCode pour le contexte actuel du produit et de la chaîne d’outils associée