Layer 8Ehrlicher Tech-Support
SoftwareSchweregrad: Lästig

npm: Das engines-Feld verhindert die Installation nicht

Das engines-Feld in package.json blockiert nichts: ohne engine-strict ist es reine Beratung. Was es wirklich tut und wie du es verbindlich machst.

Aufwand:
ca. 15 Min.

Das Symptom

Im package.json steht sauber "engines": { "node": ">=20.0.0" }. Trotzdem meldet ein Kollege, dass das Projekt bei ihm mit Node 18 seltsam kaputtgeht. Auf Nachfrage: Ja, npm install sei durchgelaufen. Eine gelbe Zeile sei da gewesen, glaubt er, aber die Installation hat funktioniert und danach war das Terminal voll mit anderem Text.

Genauso im CI: Das Deployment läuft auf einem Image mit einer viel zu alten Node-Version, npm install ist grün, und der Fehler taucht erst zur Laufzeit auf – irgendwo, wo niemand ihn mit der Node-Version in Verbindung bringt.

Die „Layer 8“-Wahrheit

Das Feld tut genau das, was es soll. Es soll nur weniger, als fast alle annehmen. Die npm-Doku formuliert es ohne Umschweife: „Unless the user has set the engine-strict config flag, this field is advisory only and will only produce warnings when your package is installed as a dependency.“ Beratend. Eine Warnung. Ein Zettel am Kühlschrank, kein Schloss an der Tür.

Dahinter steckt eine bewusste Machtverteilung, die man mögen kann oder nicht: Der Paketautor darf sagen, worauf er getestet hat, aber er darf niemandem die Installation verbieten. Ob diese Angabe verbindlich ist, entscheidet der, der installiert – über engine-strict, und erst dann wird npm laut Doku „stubbornly refuse to install (or even consider installing) any package that claims to not be compatible with the current Node.js version“. Das ist konsequent, aber es bedeutet eben auch: In einem Projekt, in dem niemand engine-strict gesetzt hat, hat dein sorgfältig gepflegtes engines-Feld noch nie irgendetwas verhindert.

Der zweite Teil der Wahrheit ist unbequemer. Selbst mit engine-strict ist die Sperre kein Bollwerk – sie lässt sich mit --force übergehen. Und --force steht in erschreckend vielen CI-Skripten, weil es irgendwann irgendein anderes Problem weggeräumt hat. Wer sich auf engines verlässt, sollte deshalb prüfen, ob im eigenen Build nicht längst ein Schalter steht, der die Prüfung als Kollateralschaden mit ausgeschaltet hat.

Die echte, verifizierte Lösung

1000 % faktenbasiert. Jeder Befehl ist real, jeder Pfad existiert. Schritt für Schritt:

  1. 1.

    Die Erwartung korrigieren

    engines beschreibt eine Anforderung, es erzwingt sie nicht. Ohne engine-strict bleibt es laut Doku beratend und erzeugt nur Warnungen, wenn das Paket als Abhängigkeit installiert wird. Wer damit eine Sperre bauen wollte, hat eine Notiz gebaut.

  2. 2.

    Die Angabe trotzdem sauber setzen

    Auch als Beratung ist das Feld wertvoll: Es dokumentiert maschinenlesbar, worauf das Paket getestet ist, und die Warnung landet im Installationsprotokoll. Eine offene untere Grenze ist dabei aussagekräftiger als eine exakte Version:

    {
  "engines": {
    "node": ">=20.0.0"
  }
}
  3. 3.

    Im eigenen Projekt verbindlich machen

    Erst engine-strict macht aus der Notiz eine Regel: Ist es gesetzt, weigert sich npm hartnäckig, ein Paket zu installieren, das sich als unvereinbar mit der aktuellen Node-Version ausweist. Die Einstellung gehört in eine .npmrc im Projekt, damit sie für alle gilt:

    echo "engine-strict=true" >> .npmrc
  4. 4.

    Wissen, dass --force die Regel wieder aufhebt

    engine-strict lässt sich per --force übergehen. In CI-Skripten heißt das: Wer dort irgendwann --force eingebaut hat, um ein anderes Problem loszuwerden, hat die Engine-Prüfung gleich mit abgeschaltet – ohne dass es jemand merkt.

  5. 5.

    Nicht dasselbe von os und cpu erwarten

    Die Felder os und cpu geben ebenfalls an, wo ein Modul laufen soll, inklusive Ausschluss über ein vorangestelltes Ausrufezeichen. Auch das ist Beschreibung der Zielplattform und ersetzt keine Prüfung, die den Build anhält.

Häufige Fragen (FAQ)

?Warum warnt npm nur, statt abzubrechen?

Weil das so vorgesehen ist. Die npm-Doku sagt, dass das Feld beratend ist und nur Warnungen erzeugt, solange der Nutzer die Konfiguration engine-strict nicht gesetzt hat. Verbindlichkeit ist hier eine Entscheidung des Installierenden, nicht des Paketautors.

?Reicht engine-strict, um schlechte Kombinationen sicher auszuschließen?

Nein. engine-strict lässt sich mit dem Schalter --force wieder aushebeln. Es ist eine Leitplanke gegen Versehen, keine Sperre gegen Absicht – und es hilft nur dort, wo es auch konfiguriert ist.

Belege

Diese Seite ist gegen die folgenden Primärquellen geprüft – Hersteller, Standard oder Gesetzestext. Wer es nicht glaubt, muss es nicht: Da steht, wo es nachzulesen ist.

  1. [1]
    npm Docs – package.json (Felder „engines“, „os“, „cpu“)

    docs.npmjs.com · abgerufen am

  2. [2]
    npm Docs – config (Eintrag „engine-strict“)

    docs.npmjs.com · abgerufen am

Zuletzt geprüft am . Dokumentation altert – ein Datum daneben ist der einzige ehrliche Umgang damit.

Auch zu finden unter

Verwandte Fehler