Kurze Antwort
Der Fehler „Node.js-Version nicht kompatibel“ bedeutet meist, dass Ihr Projekt eine andere Node.js-Version erfordert als die installierte. Die Lösung: Prüfen Sie die aktuelle Version, installieren Sie die passende (z. B. über nvm unter macOS/Linux oder nvm-windows unter Windows) und starten Sie die Installation der Abhängigkeiten erneut.
So erkennen Sie das Problem
- npm install oder yarn install meldet einen Fehler über eine inkompatible Node.js-Version
- Die Anwendung startet nicht oder stürzt direkt nach dem Start ab
- Die Meldung enthält „engine“ oder „Unsupported engine“ und die geforderte Version
- Einige Funktionen arbeiten, aber der Build oder die Tests schlagen fehl
- Die CI/CD-Pipeline meldet einen Fehler aufgrund der Node.js-Version
Häufigste Ursachen
Das Projekt erfordert eine neuere Node.js-Version
In der Datei package.json oder .nvmrc ist eine Mindestversion angegeben, die die aktuelle Installation nicht erfüllt.
Eine veraltete Node.js-Version ist installiert
Das System hat eine ältere Version (z. B. 22.x), während das Projekt 24.x oder eine neuere LTS-Version verlangt.
Konflikt mehrerer Node.js-Versionen
Auf dem Rechner existieren mehrere Installationen, aber der PATH zeigt auf die falsche, oder es wird ein globales npm statt des lokalen verwendet.
Fehlende Versionsverwaltung
Ohne ein Tool wie nvm erfordert der Wechsel zwischen Projekten manuelles Installieren und Deinstallieren.
Lösung Schritt für Schritt
- 1
Prüfen Sie die aktuelle Node.js-Version
Öffnen Sie ein Terminal und führen Sie
node -vundnpm -vaus. Notieren Sie die Ausgabe. Prüfen Sie auch, ob im Projekt eine Datei.nvmrcoder ein Feldenginesinpackage.jsonexistiert, das die benötigte Version definiert. - 2
Finden Sie die erforderliche Version
Wenn im Projekt eine
.nvmrcvorhanden ist, ist der Inhalt dieser Datei die zu verwendende Version. Andernfalls sehen Sie inenginesinpackage.jsonoder in der Projektdokumentation nach. Wenn keine Angaben vorhanden sind, installieren Sie die aktuelle LTS-Version von der offiziellen Website nodejs.org. - 3
Installieren Sie ein Versionsverwaltungstool (empfohlen)
Laden Sie unter Windows nvm-windows vom offiziellen GitHub-Repository herunter und installieren Sie es. Unter macOS/Linux verwenden Sie
nvm(Node Version Manager) gemäß der Anleitung auf der offiziellen Website. Schließen Sie das Terminal nach der Installation und öffnen Sie es erneut. - 4
Installieren Sie die passende Node.js-Version
Wenn Sie nvm verwenden, führen Sie
nvm install 24aus (ersetzen Sie die Zahl durch die vom Projekt geforderte Version). Aktivieren Sie sie dann mitnvm use 24. Unter Windows mit nvm-windows sind die Befehle dieselben, führen Sie sie jedoch in der Eingabeaufforderung oder PowerShell aus. - 5
Legen Sie die Standardversion fest (optional)
Um eine erneute Aktivierung zu vermeiden, legen Sie unter macOS/Linux die Standardversion fest:
nvm alias default 24. Unter Windows mit nvm-windows genügtnvm use 24; nvm-windows unterstütztalias defaultnicht. Prüfen Sie mitnode -v, ob die richtige Version aktiv ist. - 6
Leeren Sie den Cache und installieren Sie die Abhängigkeiten neu
Erstellen Sie eine Sicherungskopie oder prüfen Sie, ob die Änderungen in Git gespeichert sind. Löschen Sie
node_modulesundpackage-lock.json(oderyarn.lock) nur bei Bedarf. Führen Sie dann bei Bedarfnpm cache clean --forceundnpm installaus (oderyarn install/pnpm install, je nach Paketmanager). So vermeiden Sie Reste alter binärer Module, die Fehler verursachen können. - 7
Prüfen Sie, ob der Fehler weiterhin besteht
Führen Sie
npm run buildodernpm startaus und prüfen Sie die Ausgabe. Wenn Sie weiterhin einen Versionsfehler erhalten, prüfen Sie, ob ein globales Paket eine andere Version erfordert oder ob der PATH korrekt ist (which nodeunter macOS/Linux,where.exe nodeunter Windows). - 8
Aktualisieren Sie die CI/CD-Konfiguration
Wenn Sie GitHub Actions, GitLab CI oder Ähnliches verwenden, legen Sie in der Konfigurationsdatei dieselbe Node.js-Version fest (z. B.
node-version: 24). Vergessen Sie nicht, auch die lokale Umgebung an die CI-Umgebung anzupassen.
Wenn nichts hilft
Wenn Sie alle Schritte ausprobiert haben und der Fehler bleibt, prüfen Sie, ob im Projekt eine .npmrc mit engine-strict=true existiert, die die Installation blockiert. Sie können sie vorübergehend entfernen oder auf false setzen, aber tun Sie dies nur, wenn Sie die Konsequenzen verstehen. Prüfen Sie auch, ob Sie den passenden Paketmanager (npm, yarn, pnpm) und dessen Version verwenden. Manchmal ist es notwendig, auch den globalen npm-Cache zu löschen und npm neu zu installieren. Wenn der Fehler nur auf dem Produktionsserver auftritt, prüfen Sie, ob dort dieselbe Node.js-Version wie lokal installiert ist. Bei komplexen Projekten mit mehreren Microservices sollten Sie die Verwendung von Docker in Betracht ziehen, das eine konsistente Umgebung garantiert.
So beugen Sie vor
- Verwenden Sie immer `.nvmrc` oder `engines` in `package.json`, um die Node.js-Version explizit anzugeben.
- Aktualisieren Sie Node.js regelmäßig auf eine stabile LTS-Version und verfolgen Sie, wann Projekte eine neuere Version erfordern.
- Verwenden Sie ein Versionsverwaltungstool (nvm, nvm-windows, fnm), um einfach zwischen Projekten zu wechseln.
- Definieren Sie in der CI/CD-Pipeline dieselbe Node.js-Version wie in der lokalen Entwicklung.
Wann Sie einen Profi rufen sollten
Wenn der Fehler die Produktionsumgebung betrifft oder Sie die Versionen im Team nicht angleichen können, wenden Sie sich an den IT-Support. Dieser kann die richtige Umgebung einrichten und Arbeitsunterbrechungen vermeiden.
Software- und Produktentwicklung · Individuelle Apps, SaaS und ein MVP in 4 bis 8 WochenHäufige Fragen
Woher weiß ich, welche Node.js-Version das Projekt erfordert?
Meist steht sie in `.nvmrc` oder im Feld `engines` in `package.json`. Wenn diese Angaben fehlen, sehen Sie in der README oder der Projektdokumentation nach. Andernfalls installieren Sie die neueste LTS-Version.
Kann ich mehrere Node.js-Versionen gleichzeitig installieren?
Ja, verwenden Sie nvm (macOS/Linux) oder nvm-windows. Damit können Sie mehrere Versionen installieren und pro Projekt auswählen, welche verwendet wird.
Ist es sicher, node_modules und package-lock.json zu löschen?
Das Löschen von `node_modules` ist üblich und sicher, wenn Sie anschließend die Abhängigkeiten neu installieren. Das Löschen von `package-lock.json` oder `yarn.lock` kann den Abhängigkeitsbaum verändern, daher sollten Sie dies nur bei Bedarf tun und vorher die Datei sichern oder prüfen, ob die Änderung committet ist. Führen Sie nach dem Löschen `npm install` aus (oder den entsprechenden Befehl für yarn/pnpm).