Node.js installieren

Dieses Handbuch behandelt die Installation von Node.js unter Windows, macOS und Linux. Node.js ist eine wichtige Abhängigkeit für die lokalen HagiCode-Tools, einschließlich OpenSpec, Frontend-Tools und mehreren Entwickler-CLIs.

Versionsanforderungen

HagiCode empfiehlt Node.js 24+ (mindestens unterstütztes Node.js >= 18.0). In den meisten Fällen installieren Sie die neueste LTS-Version und überprüfen Sie dann, ob Ihre Version die Anforderungen erfüllt.

Node.js installieren

Windows

Methode Eins: Offizieller Installer (empfohlen)

1. Besuchen Sie die Offizielle Website von Node.js
2. Laden Sie das Windows-Installationsprogramm LTS (Long Term Support) herunter (.msi Datei)
3. Doppelklicken Sie, um das Installationsprogramm auszuführen
4. Befolgen Sie die Anweisungen des Installationsassistenten, um die Installation abzuschließen:
   • Akzeptieren Sie die Lizenzvereinbarung
   • Wählen Sie den Installationspfad (Standard ist in Ordnung)
   • Stellen Sie sicher, dass die Option „Erforderliche Tools automatisch installieren“ aktiviert ist
   • Klicken Sie auf „Installieren“, um die Installation zu starten
5. Klicken Sie nach Abschluss der Installation auf „Fertig stellen“.

Methode Zwei: Winget verwenden

Öffnen Sie PowerShell oder die Eingabeaufforderung und führen Sie Folgendes aus:

winget install OpenJS.NodeJS.LTS

Öffnen Sie nach der Installation das Terminal erneut, damit die Änderungen wirksam werden.

macOS

Methode Eins: Offizieller Installer (empfohlen)

1. Besuchen Sie die Offizielle Website von Node.js
2. Laden Sie das macOS-Installationsprogramm für die Version LTS (Long Term Support) herunter (.pkg Datei)
3. Doppelklicken Sie, um das Installationsprogramm auszuführen
4. Befolgen Sie die Anweisungen des Installationsassistenten, um die Installation abzuschließen:
   • Klicken Sie auf „Weiter“
   • Akzeptieren Sie die Lizenzvereinbarung
   • Wählen Sie die Installationsdiskette
   • Klicken Sie auf „Installieren“ und geben Sie das Administratorkennwort ein
5. Klicken Sie nach Abschluss der Installation auf „Schließen“.

Methode Zwei: Homebrew verwenden

Wenn ja Homebrew installiert ist, können Sie Node.js über das Terminal installieren:

brew install node

Homebrew fügt Node.js automatisch zu Ihrem PATH hinzu. Wenn der Befehl nicht verfügbar ist, starten Sie das Terminal neu oder führen Sie Folgendes aus:

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

Ubuntu/Debian

Verwendung des NodeSource-Repositorys (empfohlen)

Dies ist der beste Weg, um die neueste Node.js-Version zu erhalten:

# 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

Verwenden des apt-Paketmanagers

Wenn Sie nicht die neueste Version benötigen, können Sie das Standard-Ubuntu-Repository verwenden:

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

Die Node.js-Version im Standard-Repository ist möglicherweise älter. Überprüfen Sie nach der Installation die Version, um sicherzustellen, dass sie die Anforderungen von Node.js >= 18.0 erfüllt (Node.js 24+ wird empfohlen).

CentOS/RHEL

Verwendung des NodeSource-Repositorys (empfohlen)

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

Mit yum Package Manager

sudo yum install -y nodejs npm

Fedora

Verwenden des dnf-Paketmanagers

sudo dnf install -y nodejs npm

Das Software-Repository von Fedora enthält in der Regel neuere Node.js-Versionen und kann direkt über dnf installiert werden.

Verwenden von Versionsverwaltungstools

Wenn Sie zwischen mehreren Node.js-Versionen wechseln müssen, können Sie Versionsverwaltungstools verwenden.

nvm (Knotenversionsmanager)

Installing nvm

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

Laden Sie nach der Installation Ihre Shell-Konfiguration neu:

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

Windows

Unter Windows empfehlen wir die Verwendung nvm-windows:

1. Laden Sie die neueste Version herunter nvm-setup.exe von NVM-Windows-Versionen
2. Führen Sie das Installationsprogramm aus
3. Öffnen Sie die Eingabeaufforderung oder PowerShell erneut

Using nvm

Nach der Installation von nvm können Sie damit Node.js-Versionen installieren und verwalten:

# 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 (Fast Node Manager)

fnm ist ein schnelleres und einfacheres Node.js-Versionsverwaltungstool, das mit Rust erstellt wurde.

Installing 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

Windows

Benutzen Schaufel oder Winget:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

Using 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

Beschleunigung für Benutzer auf dem chinesischen Festland

Wenn Sie sich auf dem chinesischen Festland befinden, kann das Herunterladen von Node.js- und npm-Paketen langsam sein. Hier sind einige Beschleunigungslösungen.

Verwendung heimischer Spiegelquellen

npm Taobao Mirror (empfohlen)

# 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

Verwenden von nrm zum Verwalten von Spiegelquellen

Mit NRM (NPM-Registrierungsmanager) können Sie NPM-Spiegelquellen schnell wechseln:

# 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

Beschleunigen Sie das Herunterladen von Node.js-Installationsprogrammen

Taobao Node.js Mirror

Taobao bietet Spiegel-Downloads für Node.js-Installationsprogramme:

• Download-Adresse: https://npmmirror.com/mirrors/node/

Besuchen Sie die oben genannte Adresse und wählen Sie die Version aus, die Sie herunterladen möchten.

FastGit Acceleration

Wenn das Herunterladen von NVM oder anderen Tools von GitHub langsam ist, können Sie den FastGit-Spiegel verwenden:

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

Der FastGit-Dienst kann sich ändern. Bitte beachten Sie die offiziellen Informationen.

Inländische Homebrew-Spiegel

Wenn Sie Homebrew auf dem chinesischen Festland verwenden, können Sie inländische Spiegel für die Beschleunigung konfigurieren:

# 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

Spezifische Paketmanager für das chinesische Festland

cnpm

cnpm ist ein vom Taobao-Team bereitgestellter npm-Client, der standardmäßig den Taobao-Spiegel verwendet:

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

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

cnpm ist größtenteils mit npm-Befehlen kompatibel und kann als direkter Ersatz verwendet werden.

Überprüfung des Spiegelbeschleunigungseffekts

Überprüfen Sie nach dem Einrichten der Spiegel Folgendes:

# 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

Überprüfen der Installation

Überprüfen Sie nach der Installation, ob Node.js und npm korrekt installiert sind:

# Check Node.js version
node --version

# Check npm version
npm --version

Stellen Sie sicher, dass die Node.js-Version >= 18.0 ist (Node.js 24+ wird empfohlen). Wenn die Version zu niedrig ist, installieren Sie bitte mit den oben genannten Methoden neu oder verwenden Sie Versionsverwaltungstools, um die richtige Version zu installieren.

Beispiel für eine Verifizierungsausgabe

Die Ausgabe einer erfolgreichen Verifizierung sollte wie folgt aussehen:

$ node --version
v24.3.0

$ npm --version
10.2.3

Fehlerbehebung

Windows-Probleme

Command Not Available

Wenn node oder npm Befehle sind nach der Installation nicht verfügbar:

1. Starten Sie die Eingabeaufforderung oder PowerShell neu
2. Wenn immer noch nicht verfügbar, fügen Sie Node.js manuell zu PATH hinzu:
   • Suchen Sie nach „Umgebungsvariablen“ und öffnen Sie „Systemumgebungsvariablen bearbeiten“.
   • Klicken Sie auf „Umgebungsvariablen“.
   • Suchen Sie unter „Systemvariablen“ nach „Pfad“ und klicken Sie auf „Bearbeiten“.
   • Node.js-Installationspfad hinzufügen (Standard: C:\Program Files\nodejs\)
   • Klicken Sie auf „OK“, um die Änderungen zu speichern

PowerShell Execution Policy

Wenn bei der Verwendung von nvm Ausführungsrichtlinienfehler auftreten:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS-Probleme

Permission Errors

Wenn bei der Installation globaler NPM-Pakete Berechtigungsfehler auftreten:

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

Command Not Available

Wenn nach der Installation keine Befehle verfügbar sind, starten Sie das Terminal neu oder fügen Sie sie manuell zum PATH hinzu (normalerweise in /usr/local/bin).

Linux-Probleme

Permission Errors

Wenn bei der Installation globaler npm-Pakete Berechtigungsfehler auftreten, wird empfohlen, Node.js-Versionsverwaltungstools (wie nvm oder fnm) anstelle von Systempaketmanagern zu verwenden.

Version Too Old

Wenn die über den Systempaketmanager installierte Node.js-Version zu alt ist:

1. NodeSource-Repository verwenden (empfohlen, siehe oben)
2. Oder verwenden Sie Versionsverwaltungstools (nvm/fnm)

Umgebung prüfen

Wenn die Überprüfung fehlschlägt, überprüfen Sie Folgendes:

Windows

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

macOS

# Check if Node.js is in PATH
which node

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

Linux

# Check if Node.js is in PATH
which node

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

# Check version details
node -v

Nächste Schritte

Nachdem die Installation von Node.js abgeschlossen ist, können Sie mit den folgenden Schritten fortfahren:

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.

Benötigen Sie weitere Hilfe?

Wenn Sie auf Probleme stoßen, die hier nicht behandelt werden:

1. Besuchen Sie die Offizielle Node.js-Dokumentation
2. Überprüfen Sie die HagiCode-Produktübersicht für den aktuellen Produkt- und Werkzeugkontext
3. Besuchen Sie die HagiCode-Website für die neuesten Support-Einstiegspunkte