Lorixen.
DE

Node.js-Version im Projekt festlegen: .nvmrc und engines

Kurz gesagt: „Bei mir läuft es“ ist einer der teuersten Sätze in der Webentwicklung. Wenn die Website oder Web-App auf dem Laptop der Entwicklerin einwandfrei baut, auf dem Server aber mit seltsamen Fehlern abbricht, steckt häufig eine unterschiedliche Node.js-Version dahinter. Die Lösung kostet wenig: Legen Sie die Version im Projekt selbst fest, in einer kleinen Datei wie .nvmrc und im Feld engines der package.json, und lassen Sie Build-Server und Hosting dieselbe Angabe lesen. So arbeiten alle mit derselben Grundlage, und ein Wechsel der Version wird zu einer bewussten, sichtbaren Entscheidung.

Woran Sie das Problem erkennen

Unterschiedliche Node-Versionen äußern sich selten mit einer klaren Meldung. Typische Anzeichen sind:

  • Ein Build schlägt auf dem Server fehl, lokal aber nicht.
  • Nach dem Einspielen von Abhängigkeiten tauchen Fehler bei nativen Paketen auf, etwa bei Bildverarbeitung.
  • Eine neue Person im Team bekommt das Projekt nicht zum Laufen, obwohl sie die Anleitung genau befolgt.
  • Die Lockdatei ändert sich bei verschiedenen Personen ständig, obwohl niemand Pakete aktualisiert hat.
  • Ein Hosting-Anbieter stellt seine Standardversion um, und plötzlich bricht die Veröffentlichung ab.

Ein Beispiel zur Veranschaulichung: Eine kleine Agentur in Leipzig betreut die Website eines Möbelhändlers. Eine Entwicklerin arbeitet mit einer neuen Node-Version, ihr Kollege mit einer älteren, der Build-Server mit der Voreinstellung des Anbieters. Monatelang geht das gut, bis ein Paket eine Funktion nutzt, die es in der älteren Version nicht gibt. Der Fehler taucht nur bei einem von drei Beteiligten auf, und die Suche kostet einen halben Tag.

Schritt 1: Die Version in einer Datei festhalten

Viele Werkzeuge zur Verwaltung von Node-Versionen lesen eine Datei im Projektordner. Am weitesten verbreitet ist .nvmrc. Laut der Dokumentation von nvm können Sie im Stammverzeichnis des Projekts eine .nvmrc mit einer Versionsnummer anlegen. Danach verwenden Befehle wie nvm use und nvm install die dort angegebene Version, wenn auf der Kommandozeile keine andere genannt ist.

Der Inhalt ist eine einzige Zeile, zum Beispiel die Hauptversion, die Sie einsetzen. Ob Sie nur die Hauptversion oder eine exakte Version eintragen, ist eine Abwägung:

  • Nur die Hauptversion: Kleinere Sicherheitsupdates kommen automatisch, das Verhalten bleibt in der Regel gleich.
  • Exakte Version: Höchste Reproduzierbarkeit, aber Sie müssen Updates selbst nachziehen.

Für die meisten Websites und kleineren Web-Apps ist die Hauptversion ein guter Mittelweg. Setzen Sie auf Versionen mit Langzeitunterstützung, damit Sie nicht ständig wechseln müssen.

Manche Teams nutzen andere Werkzeuge, die eigene Dateien lesen, etwa .node-version oder .tool-versions. Wichtig ist, dass es genau eine verbindliche Angabe gibt. Wenn Sie mehrere Dateien pflegen müssen, halten Sie sie gemeinsam aktuell.

Schritt 2: engines in der package.json ergänzen

Die package.json kennt das Feld engines, in dem Sie angeben, mit welchen Node-Versionen das Projekt funktioniert. Laut npm-Dokumentation ist dieses Feld allerdings nur ein Hinweis: Solange die Einstellung engine-strict nicht gesetzt ist, erzeugt eine abweichende Version nur Warnungen.

Wer die Angabe verbindlich machen will, setzt in der Projektdatei .npmrc die Einstellung engine-strict=true. Dann bricht die Installation ab, wenn die laufende Node-Version nicht passt. Das ist streng, verhindert aber zuverlässig, dass jemand unbemerkt mit der falschen Version arbeitet.

Achten Sie darauf, dass engines und .nvmrc zusammenpassen. Eine .nvmrc mit einer Version, die engines ausschließt, sorgt für Verwirrung.

Schritt 3: Build-Server und Hosting angleichen

Die beste Datei nützt nichts, wenn der Build-Server sie ignoriert. Prüfen Sie, wo Ihr Projekt gebaut wird, und stellen Sie dort ein, dass dieselbe Angabe gelesen wird.

Für GitHub Actions bietet die offizielle Aktion setup-node die Option node-version-file. Laut ihrer Dokumentation kann sie die Version unter anderem aus package.json, .nvmrc oder .node-version lesen. Damit bauen Ihre automatisierten Abläufe mit genau der Version, die auch im Projekt steht.

Viele Hosting-Plattformen für Websites und Web-Apps lesen ebenfalls eine dieser Dateien oder das Feld engines, andere erwarten eine Einstellung im Kundenbereich. Schauen Sie in die Dokumentation Ihres Anbieters und dokumentieren Sie im Projekt, wo die Version festgelegt wird. Wenn Sie einen eigenen Server betreiben, gehört die Node-Version in Ihre Einrichtungsanleitung oder Ihr Einrichtungsskript.

Schritt 4: Das Team mitnehmen

Damit alle die Datei auch nutzen, braucht es wenig:

  1. Ein kurzer Abschnitt in der Projektanleitung: „Node-Version steht in .nvmrc. Vor dem Arbeiten nvm use ausführen.“
  2. Optional eine Einrichtung im Terminal, die beim Wechsel in den Projektordner automatisch die richtige Version aktiviert. Die nvm-Dokumentation beschreibt dafür Beispiele für verbreitete Shells.
  3. Eine Prüfung im Build, die die Version ausgibt. So sehen Sie in jedem Protokoll, womit gebaut wurde.

Was nach einem Wechsel oft vergessen wird

Nach dem Wechsel der Node-Version sollten Sie den Ordner mit den installierten Abhängigkeiten löschen und alles neu installieren. Pakete mit nativen Bestandteilen werden für eine bestimmte Node-Version gebaut und funktionieren mit einer anderen unter Umständen nicht. Ein sauberer Neuaufbau erspart Fehlermeldungen, die auf den ersten Blick nichts mit der Version zu tun haben.

Denken Sie außerdem an Stellen außerhalb des eigentlichen Projekts: geplante Aufgaben auf dem Server, die ein Skript mit Node ausführen, kleine Hilfsprogramme für Importe oder Bildoptimierung, Vorschau-Umgebungen beim Hosting-Anbieter. Eine kurze Liste aller Orte, an denen Node läuft, gehört in die Projektdokumentation. Beim nächsten Wechsel arbeiten Sie diese Liste einfach ab.

Versionswechsel als eigene Aufgabe planen

Mit einer festgelegten Version wird ein Wechsel zu einer kleinen, planbaren Aufgabe. Legen Sie dafür einen eigenen Zweig an, ändern Sie .nvmrc und engines, installieren Sie die Abhängigkeiten neu und lassen Sie Build und Tests laufen. Prüfen Sie zusätzlich die wichtigsten Seiten der Website oder die Kernabläufe der App von Hand.

Planen Sie solche Wechsel rechtzeitig, bevor die Unterstützung der eingesetzten Version endet. Der Node.js-Veröffentlichungsplan nennt die Zeiträume für jede Hauptversion. Ein Eintrag im Wartungskalender, etwa zweimal im Jahr, verhindert, dass Sie unter Zeitdruck wechseln müssen.

Häufige Fragen

Reicht es, die Version in der Projektanleitung zu notieren?

Es ist besser als nichts, aber leicht zu übersehen. Eine Datei, die Werkzeuge automatisch lesen, wirkt zuverlässiger.

Sollte ich engine-strict immer aktivieren?

Für eigene Website- und App-Projekte ist es oft sinnvoll. Wenn mehrere Personen mit unterschiedlichen Projekten arbeiten, kann es anfangs Rückfragen geben. Erklären Sie die Einstellung in der Projektanleitung.

Was ist mit Docker?

Wenn Ihr Projekt in einem Container gebaut wird, legt das Basis-Image die Node-Version fest. Wählen Sie dort dieselbe Hauptversion wie in .nvmrc, damit lokale Arbeit und Container übereinstimmen.

Muss die Version auf dem Server exakt gleich sein?

Die Hauptversion sollte übereinstimmen. Kleinere Abweichungen innerhalb einer Hauptversion sind meist unproblematisch, sollten aber im Build-Protokoll sichtbar sein.

Wenn Builds bei Ihnen auf manchen Rechnern laufen und auf anderen nicht, bringen wir Ordnung in die Umgebung: Projektumgebung prüfen lassen.

Quellen

WhatsAppTermin buchen