Anleitung: Eigenständige Node.js-Versionen pro Projekt mit ServBay konfigurieren (macOS)

ServBay ist eine leistungsstarke lokale Webentwicklungsumgebung, die speziell für Entwickler konzipiert wurde. Sie bietet eine All-in-One-Lösung und integriert verschiedene Programmiersprachen, Datenbanken sowie Webserver – einschließlich nativer Unterstützung und flexibler Verwaltung mehrerer Node.js-Versionen. Ein hervorgehobener Vorteil von ServBay ist die Möglichkeit, für jedes Projekt eigenständig und einfach die benötigte Node.js-Version mittels einer Konfigurationsdatei zu bestimmen – ganz ohne externe Version Manager wie NVM, fnm oder den Einsatz schwergewichtiger Docker-Container. So wird Ihr Workflow deutlich vereinfacht und globale Versionskonflikte werden von vornherein vermieden.

Im Folgenden erfahren Sie im Detail, wie Sie mit der .servbay.config-Datei projektbezogenes Node.js-Versionmanagement in ServBay umsetzen.

Warum Node.js-Versionen mit .servbay.config in ServBay verwalten?

Traditionelle Methoden wie NVM oder manuelles Installieren von Node.js bringen einige Nachteile mit sich:

• Globale Konflikte & Verunreinigung: Systemweite Installationen oder das globale Umschalten per Version-Manager führen häufig zu Abhängigkeitskonflikten zwischen Projekten.
• Zeitaufwendige (Re-)Kompilierung: Bei der Installation neuer Versionen oder dem Wechsel zwischen Architekturen (z. B. x86_64 und arm64) müssen oft Module neu kompiliert werden – das kostet Zeit und Nerven.
• Zu viel Overhead durch Docker-Container: Für einfache Anforderungen an bestimmte Node.js-Versionen sind komplette Docker-Setups unnötig komplex und schwergewichtig.

ServBay löst diese Probleme auf elegante Weise: Es bringt mehrere beliebte Node.js-Versionen bereits mit (aktuell v12 bis v23, detailliert einsehbar und verwaltbar im „Pakete“-Reiter der ServBay-App) und kombiniert das mit projektindividuellen Einstellungen aus der .servbay.config-Datei:

• Sofortiger Wechsel: Da alle Versionen vorinstalliert sind, ist der Wechsel fast augenblicklich möglich.
• Projektspezifische Isolation: Die Konfiguration gilt nur im jeweiligen Projektverzeichnis – echte Versionsisolation auf Projektebene.
• Kein globaler Eingriff: Am System selbst wird nichts verändert, Ihr System bleibt sauber.
• Nahtlose ServBay-Integration: Optimal verzahnt mit anderen von ServBay verwalteten Komponenten (wie PHP, Datenbanken, Webservern etc.).

Voraussetzungen

Bevor Sie beginnen, stellen Sie bitte sicher:

1. Sie haben ServBay erfolgreich auf macOS installiert und laufen.
2. Im Bereich „Pakete“ innerhalb der ServBay App ist die für Ihr Projekt benötigte Node.js-Version installiert und aktiviert.
3. Sie verfügen über ein Projektverzeichnis, für das eine spezifische Node.js-Version konfiguriert werden soll.

Grundprinzip

ServBay überwacht das aktuelle Verzeichnis in der integrierten Terminalumgebung. Beim Navigieren (cd Befehl) sucht ServBay im aktuellen und allen übergeordneten Verzeichnissen nach einer Datei namens .servbay.config. Sobald eine solche Datei gefunden wird (es zählt die dem aktuellen Verzeichnis am nächsten gelegene), liest ServBay die enthaltenen Einstellungen aus und passt die Umgebungsvariablen der aktuellen Sitzung entsprechend an – beispielsweise, indem PATH so gesetzt wird, dass auf die in .servbay.config angegebene Node.js-Version verwiesen wird.

Dadurch werden in jeder terminalbasierten Projektsitzung automatisch und projektabhängig die passenden Node.js-Versionen geladen – ganz ohne manuelles Umschalten.

Schritt-für-Schritt-Anleitung

Die projektbasierte Node.js-Konfiguration ist simpel. Es braucht nur zwei Schritte:

Schritt 1: .servbay.config-Datei im Projektverzeichnis anlegen und bearbeiten

Legen Sie im Wurzelverzeichnis Ihres Projekts (meist dort, wo sich auch die package.json befindet) eine neue Datei namens .servbay.config an.

Öffnen Sie diese Datei in einem Editor Ihrer Wahl und fügen Sie folgenden Inhalt hinzu:

# Hauptversionsnummer von Node.js für dieses Projekt festlegen
# ServBay verwendet automatisch die neueste installierte Nebenversion dieser Hauptversion
NODE_VERSION=20

# Optional: npm- oder pnpm-Registry für schnellere Abhängigkeitsinstallationen setzen
# In China wird der Gebrauch lokaler Mirrors empfohlen
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Optional: Cache-Verzeichnis für npm oder pnpm definieren
# Empfohlen: Das ServBay-Temporärverzeichnis nutzen, um Systemplatz zu sparen
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Erläuterung der Konfigurationsoptionen:

• NODE_VERSION: Pflichtfeld. Gibt die gewünschte Node.js-Hauptversion für das Projekt an. Beispiel: 20 sorgt dafür, dass ServBay die neueste installierte 20.x-Version verwendet. Die gewählte Version muss vorinstalliert sein.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Optional. Adresse eines Mirror-Registrys zur Installation von Paketen. Besonders nützlich bei langsamen Netzwerken.
• NPM_CONFIG_CACHE: Optional. Setzt das Cache-Verzeichnis für npm/pnpm. Das vorgeschlagene temporäre ServBay-Verzeichnis hält Ihr System sauber.

Speichern und schließen Sie die .servbay.config-Datei anschließend.

Schritt 2: Version im ServBay-Terminal überprüfen

1. Öffnen Sie die ServBay-Hauptanwendung.

2. Klicken Sie auf „Terminal“, um das integrierte ServBay-Terminal zu starten.

3. Wechseln Sie mit cd ins Projektverzeichnis:

   cd /Applications/ServBay/www/your-project-name

   (Ersetzen Sie /Applications/ServBay/www/your-project-name durch Ihren tatsächlichen Projektpfad.)

4. Geben Sie node -v ein, um die aktive Node.js-Version zu prüfen:

   node -v

   Die Ausgabe sollte mit der in .servbay.config festgelegten Version übereinstimmen (z. B. v20.x.x).

5. Mit npm -v (bzw. pnpm -v, yarn -v) überprüfen Sie auf Wunsch, ob auch die Paketmanager den korrekten Kontext nutzen.

Nun nutzt jedes Kommando im Projektverzeichnis (Node.js, npm/pnpm/yarn) automatisch die in .servbay.config definierte Version und deren Runtime.

Anwendungsbeispiel

Das folgende Beispiel zeigt, wie .servbay.config Node.js-Versionen beim Wechseln zwischen Projekten automatisch anpasst.

Angenommen, Sie haben zwei Projekte: project-a benötigt Node.js v18, project-b Node.js v20.

1. Projektverzeichnisse und Konfigurationsdateien anlegen:

   # Beispielprojekte im ServBay-www-Ordner erstellen
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # .servbay.config für project-a auf Node.js v18 setzen
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # .servbay.config für project-b auf Node.js v20 setzen
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Wechsel und Prüfung im ServBay-Terminal:

   Starten Sie das ServBay-Terminal und führen Sie folgende Befehle aus:

   # In project-a wechseln
   cd /Applications/ServBay/www/project-a
   # Node.js-Version prüfen
   node -v
   # Erwartete Ausgabe: v18.x.x
   
   # In project-b wechseln
   cd ../project-b
   # Node.js-Version prüfen
   node -v
   # Erwartete Ausgabe: v20.x.x
   
   # Zurück zu project-a
   cd ../project-a
   # Node.js-Version prüfen
   node -v
   # Erwartete Ausgabe: v18.x.x

Wie im Beispiel zu sehen, erkennt ServBay den Verzeichniswechsel und aktiviert automatisch die in .servbay.config festgelegte NODE_VERSION – nahtlos und ohne weiteres Zutun.

Die folgende Abbildung veranschaulicht, wie sich die Node.js-Version beim Wechseln des Projektverzeichnisses automatisch entsprechend der .servbay.config ändert (dies ist ein Beispielbild, das tatsächliche Interface kann abweichen):

Hinweise

• Die .servbay.config-Datei muss sich im Projekt- oder einem übergeordneten Verzeichnis befinden. ServBay sucht nach der Datei aufwärts im Verzeichnisbaum und verwendet die nächstgelegene Instanz davon.
• Arbeiten Sie immer im integrierten ServBay-Terminal oder in einem externen Terminal, das korrekt auf die ServBay-Umgebungsvariablen eingestellt ist.
• Die durch NODE_VERSION vorgegebene Version muss in der ServBay-App installiert und aktiviert sein – sonst kann ServBay entweder auf eine Standardversion zurückfallen oder Node.js nicht finden.
• Einstellungen in .servbay.config beeinflussen nur die aktuelle Terminalsitzung und Kindprozesse – das System oder andere Prozesse außerhalb von ServBay bleiben unbeeinflusst.

FAQ – Häufig gestellte Fragen

F: Was passiert, wenn im Projektverzeichnis keine .servbay.config liegt?

A: Ist keine .servbay.config auffindbar (weder dort noch in Elternverzeichnissen), verwendet ServBay die globale Einstellung oder die standardmäßig aktivierte Node.js-Version (in der Regel die als „Standard“ markierte Version in ServBay).

F: Wie kann ich herausfinden, welche Node.js-Versionen ServBay unterstützt?

A: Öffnen Sie die ServBay-App und navigieren Sie im linken Menü zum Abschnitt „Pakete“. Hier sehen Sie die komplette Auflistung aller verfügbaren und installierten Softwarepakete, inklusive aller Node.js-Versionen. Sie können gezielt Versionen aktivieren oder deaktivieren.

F: Wirkt sich die .servbay.config-Konfiguration systemweit aus?

A: Nein. Einstellungen in .servbay.config gelten immer nur in der aktuellen ServBay-Terminalsitzung oder für Prozesse mit ServBay-Umgebungsvariablen. Ihr System bleibt unverändert – das ist ein zentraler Mechanismus für echte Projektisolation in ServBay.

F: Lassen sich über NODE_VERSION hinaus weitere ServBay-relevante Einstellungen in .servbay.config setzen?

A: Ja, .servbay.config fungiert als projektweite Umgebungsvariablendatei für ServBay. Sie können hier neben Node.js-Versionen beliebige unterstützte Umgebungsvariablen hinterlegen, die dann beim Ausführen von Befehlen im Projekt wirksam sind. Umfang und Möglichkeiten wachsen stetig mit neuen ServBay-Versionen, aber das Setzen von Umgebungsvariablen ist der Kern dieser Funktion.

Fazit

Mit der .servbay.config-Datei von ServBay weisen Sie Ihren lokalen Entwicklungsprojekten mühelos und effizient individuelle Node.js-Versionen zu. Dieses Vorgehen ist im Vergleich zu traditionellen Versionmanagern oder Container-Lösungen deutlich leichter, schlanker und integriert sich nahtlos in die ServBay-Umgebung. So erschaffen Sie stabile, kollaborative Workflows ohne Versionsärger oder Systemverunreinigung. Nutzen Sie noch heute .servbay.config in Ihrem Projekt und erleben Sie den Komfort von ServBay!