Node.js Fehlerbehebung

Dieses Dokument soll Entwicklern, die ServBay als lokale Entwicklungsumgebung nutzen, dabei helfen, häufig auftretende Probleme mit Node.js-Paketen zu lösen.

Node.js/npm/pnpm/yarn-Befehlsversion nicht gefunden

Wenn Sie in ServBay Node.js, npm, pnpm oder yarn verwenden und auf eine Fehlermeldung wie die folgende stoßen, bedeutet das, dass das System die von Ihnen angeforderte spezifische Node.js-Version nicht finden kann:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

Dies liegt meist daran, dass die gewünschte Node.js-Version in ServBay noch nicht installiert wurde, oder Sie eine über andere Tools wie nvm oder homebrew installierte Node.js-Version verwenden möchten, aber ServBay diese aufgrund der Umgebungs-Konfiguration nicht korrekt auffindet.

Hinweis

Nach der Installation von ServBay wird ein Skript-Alias eingerichtet, sodass bevorzugt die von ServBay installierten Node.js-Pakete genutzt werden. Falls ServBay die geforderte Version nicht findet, versucht es, auf die von nvm und danach von homebrew installierte Standardversion zurückzugreifen. Gelingt dies nicht, erscheint der oben gezeigte Fehler.

Ursachenanalyse:

1. Die gewünschte Node.js-Version ist nicht in der ServBay-App installiert.
2. Sie haben nvm oder homebrew installiert und möchten deren Node.js-Versionen verwenden, aber durch falsche Shell-Umgebungseinstellungen (insbesondere der Umgebungsvariablen PATH oder NVM_BIN) kann ServBay im Rahmen seines Fallback-Mechanismus diese extern installierten Node.js-Versionen nicht finden.

Lösungswege:

Sollten Sie bereits nvm installiert und damit Node.js-Versionen verwaltet haben, aber dennoch diese Fehlermeldung erhalten, liegt dies häufig an einer fehlenden oder falsch gesetzten Umgebungsvariable NVM_BIN in Ihrer Shell-Konfiguration. Bei korrekter Installation richtet nvm diese Variable automatisch ein – sie zeigt auf das Verzeichnis, in dem sich die von nvm verwalteten Node.js-Binärdateien befinden, und ist essenziell für das reibungslose Funktionieren von nvm.

Überprüfen und korrigieren Sie daher Ihre Shell-Konfigurationsdatei (z.B. ~/.zshrc, ~/.bash_profile), achten Sie auf die korrekte Einrichtung und das Exportieren der Variablen NVM_BIN, und laden Sie anschließend die Konfiguration neu (z.B. durch source ~/.zshrc oder einen Neustart des Terminals). Nach der Korrektur sollte ServBays Fallback-Mechanismus auch Ihre von nvm verwaltete Node.js-Version problemlos erkennen.

Wenn Sie weder nvm noch homebrew verwenden oder explizit die von ServBay bereitgestellten Node.js-Versionen nutzen wollen, stellen Sie sicher, dass die benötigte Version in ServBay über die Oberfläche „Pakete“ installiert ist.

Architektur nicht unterstützt beim Einsatz von node-sass und ähnlichen npm-Paketen

Wenn Sie macOS auf einem Apple Silicon-Chip (M1/M2/M3/M4, Arm64-Architektur) nutzen, kann es beim Einsatz älterer oder nativ kompilierter npm-Pakete (wie node-sass) zu Fehlermeldungen wie Unsupported architecture (arm64) kommen. Ursache sind fehlende oder nicht-kompatible Binärpakete, die häufig nur für x86_64 kompiliert wurden.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

Ursachenanalyse:

Manche npm-Pakete enthalten C++- oder anderen nativen Code, der für die jeweilige CPU-Architektur kompiliert wird. Ältere Versionen bieten oftmals keine Unterstützung oder vorgefertigten Binärdateien für Arm64 (Apple Silicon).

Lösungswege:

1. Umstieg auf moderne Alternativen mit Arm64-Support (empfohlen):

   Die beste Lösung ist der Wechsel auf ein modernes, aktiv gepflegtes und mit Arm64 kompatibles Paket. Im Fall von node-sass empfiehlt sich der Umstieg auf das Paket sass, welches mittlerweile Standard in modernen Frontend-Projekten ist.

   npm uninstall node-sass
   npm install --save-dev sass

2. Node.js für x86_64 in ServBay installieren und mit Rosetta 2 ausführen (nicht empfohlen):

   In ServBay können Sie auch Node.js für die x86_64-Architektur installieren. Auf einem Apple Silicon Mac lässt sich so Node.js samt x86_64-nativer Module mittels der Übersetzungsschicht Rosetta 2 betreiben. Die entsprechende Version kann einfach im „Pakete“-Bereich der Anwendung installiert werden.

   

   Bitte beachten Sie: Dies ist keine langfristige Lösung! Der Betrieb über Rosetta 2 bringt Leistungseinbußen und eventuelle Kompatibilitätsprobleme mit sich. Bitte bevorzugen Sie Lösung 1.

---