Installation de Node.js

Ce guide couvre l’installation de Node.js sur Windows, macOS et Linux. Node.js est une dépendance clé pour les outils locaux HagiCode, notamment OpenSpec, les outils frontend et plusieurs CLI de développeur.

Exigences de la version

HagiCode recommande Node.js 24+ (Node.js minimum pris en charge >= 18.0). Dans la plupart des cas, installez la dernière version de LTS, puis vérifiez que votre version répond aux exigences.

Installation de Node.js

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

Visitez le Site officiel de Node.js
Téléchargez le programme d’installation Windows de la version LTS (Long Term Support) (.msi fichier)
Double-cliquez pour exécuter le programme d’installation
Suivez les invites de l’assistant d’installation pour terminer l’installation :
- Accepter le contrat de licence
- Choisissez le chemin d’installation (la valeur par défaut convient)
- Assurez-vous que “Installer automatiquement les outils nécessaires” est coché
- Cliquez sur “Installer” pour démarrer l’installation
Une fois l’installation terminée, cliquez sur “Terminer”

Deuxième méthode : utiliser Winget

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

winget install OpenJS.NodeJS.LTS

Après l’installation, rouvrez le terminal pour que les modifications prennent effet.

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

Visitez le Site officiel de Node.js
Téléchargez le programme d’installation de macOS de la version LTS (Long Term Support) (.pkg fichier)
Double-cliquez pour exécuter le programme d’installation
Suivez les invites de l’assistant d’installation pour terminer l’installation :
- Cliquez sur “Continuer”
- Accepter le contrat de licence
- Choisissez le disque d’installation
- Cliquez sur “Installer” et entrez le mot de passe administrateur
Une fois l’installation terminée, cliquez sur “Fermer”

Deuxième méthode : utiliser Homebrew

Si vous avez Homebrew installé, vous pouvez installer Node.js via le terminal :

brew install node

Homebrew ajoutera 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)"

Utilisation du référentiel NodeSource (recommandé)

C’est le meilleur moyen d’obtenir la dernière version de Node.js :

# Use curl to download the installation script
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Utiliser le gestionnaire de paquets apt

Si vous n’avez pas besoin de la dernière version, vous pouvez utiliser le référentiel Ubuntu par défaut :

sudo apt-get update
sudo apt-get install -y nodejs npm

La version de Node.js dans le référentiel par défaut est peut-être plus ancienne. Après l’installation, vérifiez la version pour vous assurer qu’elle répond aux exigences de Node.js >= 18.0 (Node.js 24+ est recommandé).

Utilisation du référentiel NodeSource (recommandé)

# Use curl to download the installation script
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

Utilisation du gestionnaire de paquets Yum

sudo yum install -y nodejs npm

Utilisation du gestionnaire de packages dnf

sudo dnf install -y nodejs npm

Le référentiel de logiciels de Fedora contient généralement des versions plus récentes de Node.js et peut être installé directement via dnf.

Utilisation des outils de gestion des versions

Si vous devez basculer entre plusieurs versions de Node.js, vous pouvez utiliser des outils de gestion de versions.

Linux/macOS

# Install using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Or install using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Après l’installation, rechargez la configuration de votre shell :

source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Fenêtres

Sous Windows, nous vous recommandons d’utiliser NVM-Windows:

Téléchargez la dernière nvm-setup.exe de versions nvm-windows
Exécutez le programme d’installation
Rouvrir l’invite de commande ou PowerShell

Après avoir installé nvm, vous pouvez l’utiliser pour installer et gérer les versions de Node.js :

# Install the latest LTS version (recommended)
nvm install --lts

# Install Node.js 24 (recommended version)
nvm install 24

# Install a specific Node.js version
nvm install 18.20.0

# List installed versions
nvm list

# Switch to a specified Node.js version
nvm use 24

# Set default version
nvm alias default 24

# Windows nvm-windows syntax is slightly different
nvm install 24
nvm use 24

fnm (gestionnaire de nœuds rapide)

fnm est un outil de gestion de versions Node.js plus rapide et plus simple construit avec Rust.

Installing fnm
Using fnm

Linux/macOS

# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash

# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Fenêtres

Utiliser cuillère ou aile:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

# Install the latest LTS version (recommended)
fnm install --lts

# Install Node.js 24 (recommended version)
fnm install 24

# Install a specific Node.js version
fnm install 18.20.0

# List installed versions
fnm list

# Switch to a specified Node.js version
fnm use 24

# Set default version
fnm default 24

Accélération pour les utilisateurs de Chine continentale

Si vous êtes en Chine continentale, le téléchargement des packages Node.js et npm peut être lent. Voici quelques solutions d’accélération.

Utilisation de sources miroir nationales

Miroir npm Taobao (recommandé)

# Temporarily use Taobao mirror
npm install --registry=https://registry.npmmirror.com

# Permanently set Taobao mirror
npm config set registry https://registry.npmmirror.com

# Verify mirror is set successfully
npm config get registry

Utiliser nrm pour gérer les sources miroir

nrm (gestionnaire de registre npm) vous aide à changer rapidement de source de miroir npm :

# Install nrm
npm install -g nrm

# List available mirror sources
nrm ls

# Switch to Taobao mirror
nrm use taobao

# Test mirror source speed
nrm test

Accélération des téléchargements du programme d’installation de Node.js

Taobao Node.js Mirror
FastGit Acceleration

Taobao propose des téléchargements miroir pour les installateurs Node.js :

Adresse de téléchargement : https://npmmirror.com/mirrors/node/

Visitez l’adresse ci-dessus et sélectionnez la version que vous devez télécharger.

Si le téléchargement de NVM ou d’autres outils depuis GitHub est lent, vous pouvez utiliser le miroir FastGit :

# Use FastGit to accelerate nvm installation
curl -o- https://fastgit.org/nvm-sh/nvm/raw/master/install.sh | bash

Le service FastGit peut changer, veuillez vous référer aux informations officielles.

Miroirs homebrew domestiques

Si vous utilisez Homebrew en Chine continentale, vous pouvez configurer des miroirs nationaux pour l’accélération :

# Install Homebrew using domestic mirror
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

# Or use USTC mirror
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Gestionnaires de packages spécifiques à la Chine continentale

cnpm

cnpm est un client npm fourni par l’équipe Taobao qui utilise le miroir Taobao par défaut :

# Install cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com

# Use cnpm to install packages
cnpm install <package-name>

cnpm est principalement compatible avec les commandes npm et peut être utilisé en remplacement direct.

Vérification de l’effet d’accélération du miroir

Après avoir configuré les miroirs, vérifiez en :

# Test download speed
time npm install express --registry=https://registry.npmmirror.com

# Compare with official source speed
time npm install express --registry=https://registry.npmjs.org

Vérification de l’installation

Après l’installation, vérifiez que Node.js et npm sont correctement installés :

# Check Node.js version
node --version

# Check npm version
npm --version

Assurez-vous que la version de Node.js >= 18.0 (Node.js 24+ est recommandé). Si la version est trop basse, veuillez réinstaller en utilisant les méthodes ci-dessus ou utiliser les outils de gestion de version pour installer la version correcte.

Exemple de résultat de vérification

Le résultat d’une vérification réussie devrait ressembler à :

$ node --version
v24.3.0

$ npm --version
10.2.3

Dépannage

Problèmes Windows

Command Not Available
PowerShell Execution Policy

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

Redémarrez l’invite de commande ou PowerShell
S’il n’est toujours pas disponible, ajoutez manuellement Node.js à PATH :
- Recherchez « Variables d’environnement » et ouvrez « Modifier les variables d’environnement système »
- Cliquez sur “Variables d’environnement”
- Recherchez « Chemin » dans « Variables système » 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

Si vous rencontrez des erreurs de politique d’exécution lors de l’utilisation de NVM :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problèmes macOS

Permission Errors
Command Not Available

Si vous rencontrez des erreurs d’autorisation lors de l’installation des packages npm globaux :

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Si les commandes ne sont pas disponibles après l’installation, redémarrez le terminal ou ajoutez manuellement à PATH (généralement dans /usr/local/bin).

Problèmes Linux

Permission Errors
Version Too Old

Si vous rencontrez des erreurs d’autorisation lors de l’installation de packages npm globaux, il est recommandé d’utiliser les outils de gestion de versions Node.js (comme nvm ou fnm) au lieu des gestionnaires de packages système.

Vérification de l’environnement

Si la vérification échoue, vérifiez les points suivants :

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

# Check version details
node -v

Prochaines étapes

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

Install OpenSpec Install the OpenSpec specification-driven development tool to manage proposals, specs, and changes.

Install AI Agent CLI Use one registry for the official install entries for Claude Code, Codex, Gemini, GitHub Copilot, CodeBuddy, OpenCode, Kimi, QoderCLI, and Kiro.

Return to Installation Guide Return to the main installation guide to continue configuring other dependencies.

Besoin de plus d’aide ?

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

Visitez le Documentation officielle de Node.js
Passez en revue le Présentation du produit HagiCode pour le contexte actuel du produit et de l’outillage
Visitez le Site Internet HagiCode pour les derniers points d’entrée du support