Przewodnik: Jak skonfigurować niezależną wersję Node.js dla projektu w ServBay (macOS)

ServBay to zaawansowane lokalne środowisko programistyczne dla deweloperów webowych, oferujące kompleksowe rozwiązanie zintegrowane z wieloma językami programowania, bazami danych i serwerami webowymi. Jednym z głównych atutów ServBay jest natywne wsparcie oraz elastyczne zarządzanie wieloma wersjami Node.js. Dzięki prostemu plikowi konfiguracyjnemu możesz łatwo przypisać wymaganą wersję Node.js dla każdego projektu, bez polegania na zewnętrznych menedżerach wersji, takich jak NVM czy fnm, ani korzystania z kontenerów Docker. Upraszcza to workflow, eliminuje ryzyko konfliktów wersji oraz zanieczyszczenia globalnego środowiska.

W tym artykule dowiesz się, jak wykorzystać plik .servbay.config do projektowego zarządzania wersją Node.js w ServBay.

Dlaczego zarządzanie wersjami Node.js przez .servbay.config w ServBay?

Tradycyjne metody zarządzania wersjami Node.js, takie jak użycie NVM lub ręczna instalacja, mogą być kłopotliwe:

• Zanieczyszczenie i konflikty globalne: Instalacja wersji systemowo lub przełączanie wersji globalnie łatwo prowadzi do konfliktów zależności między projektami.
• Czasochłonny proces instalacji i kompilacji: Instalacja nowej wersji bądź przełączanie między architekturami (np. x86_64 a arm64) może wymagać ponownej kompilacji modułów — to złożone i czasochłonne.
• Wysoki narzut Dockera: Dla sytuacji wymagających jedynie konkretnej wersji Node.js, użycie pełnych kontenerów Docker bywa zbyt „ciężkie”.

ServBay wychodzi naprzeciw tym problemom dzięki preinstalowanym wersjom Node.js (aktualnie obsługuje wszystkie wersje główne i poboczne od v12 do v23; możesz zarządzać nimi w sekcji „Pakiety” aplikacji ServBay), a także za sprawą pliku .servbay.config:

• Błyskawiczne przełączanie: Wersje są już zainstalowane — zmiana odbywa się natychmiast.
• Izolacja projektowa: Konfiguracja dotyczy tylko katalogu projektu, zapewniając prawdziwą izolację wersji.
• Brak zanieczyszczeń globalnych: Nie zmienia globalnych ustawień systemu — środowisko pozostaje czyste.
• Integracja z ServBay: Pełna spójność z innymi komponentami ServBay (PHP, baza danych, serwer www itd.).

Wymagania wstępne

Zanim zaczniesz, upewnij się, że:

1. Masz zainstalowany i uruchomiony ServBay na macOS.
2. W sekcji „Pakiety” (Packages) aplikacji ServBay jest włączona wymagana wersja Node.js.
3. Posiadasz katalog projektu, który wymaga konkretnej wersji Node.js.

Podstawowe zasady działania

Gdy korzystasz z wbudowanego terminala ServBay, aplikacja monitoruje bieżący katalog. Przy użyciu komendy cd i wejściu do katalogu projektu, ServBay przeszukuje ten katalog oraz katalogi nadrzędne w poszukiwaniu pliku .servbay.config. Po znalezieniu pliku (wybierany jest najbliższy względem bieżącego katalogu), ServBay odczytuje konfiguracje i dynamicznie dostosowuje zmienne środowiskowe sesji terminala, np. modyfikuje ścieżkę PATH, by wskazywała na katalog z wybraną wersją Node.js określoną w .servbay.config.

Dzięki temu każda sesja w terminalu, otwarta w danym katalogu projektu, automatycznie korzysta z przypisanej tam wersji Node.js — nie musisz przełączać jej ręcznie.

Kroki konfiguracji

Skonfigurowanie niezależnej wersji Node.js dla projektu jest bardzo proste i składa się z dwóch kroków:

Krok 1: Utwórz i edytuj plik .servbay.config

W katalogu głównym projektu (zwykle tym, gdzie znajduje się package.json), stwórz nowy plik o nazwie .servbay.config.

Otwórz ten plik w ulubionym edytorze tekstu i dodaj poniższe linie:

# Określenie głównej wersji Node.js używanej przez projekt
# ServBay automatycznie wybierze najnowszą zainstalowaną wersję z tej serii głównej
NODE_VERSION=20

# Opcjonalnie: ustawienia rejestru npm lub pnpm do przyspieszenia instalacji zależności
# Jeśli jesteś w Chinach, zalecane jest użycie lokalnego mirrora
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Opcjonalnie: określenie katalogu cache npm lub pnpm
# Zalecane jest użycie katalogu tymczasowego ServBay, by uniknąć zapełnienia i zanieczyszczenia katalogu domowego
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Opis konfiguracji:

• NODE_VERSION: wymagane. Główna wersja Node.js wymagana przez projekt. Przykładowo, wpisanie 20 spowoduje użycie najnowszej dostępnej wersji z serii 20.x zainstalowanej w ServBay. Upewnij się, że dana wersja jest zainstalowana.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: opcjonalne. Rejestr (mirror) pakietów dla yarn lub npm. Szczególnie przydatne do przyspieszania instalacji zależności w słabym środowisku sieciowym.
• NPM_CONFIG_CACHE: opcjonalne. Katalog cache dla npm lub pnpm. Ustawienie go na katalog tymczasowy ServBay (/Applications/ServBay/tmp/npm/cache) pozwala centralizować cache i unikać bałaganu w systemie.

Zapisz i zamknij plik .servbay.config.

Krok 2: Zweryfikuj wersję w terminalu ServBay

1. Otwórz główne okno aplikacji ServBay.

2. Kliknij „Terminal” (Terminal), aby uruchomić terminal wbudowany w ServBay.

3. Przejdź do katalogu swojego projektu za pomocą cd:

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

   (Zamień /Applications/ServBay/www/your-project-name na właściwą ścieżkę swojego projektu)

4. Uruchom polecenie node -v, aby sprawdzić bieżącą aktywną wersję Node.js.

   node -v

   Wynik powinien wskazywać wersję Node.js zdefiniowaną w .servbay.config (np. v20.x.x).

5. Możesz także wywołać npm -v (lub pnpm -v, yarn -v), by upewnić się, że menedżer pakietów także korzysta z prawidłowej wersji Node.js.

Od tej pory każda komenda Node.js lub npm/pnpm/yarn wykonywana w tej ścieżce projektu będzie odbywać się w środowisku skonfigurowanym przez .servbay.config.

Przykład działania

Oto przykład, jak .servbay.config umożliwia automatyczne przełączanie wersji Node.js pomiędzy projektami.

Załóżmy, że masz dwa projekty: project-a wymaga Node.js v18, a project-b wymaga Node.js v20.

1. Utwórz katalogi projektów i pliki konfiguracyjne:

   # Utworzenie katalogów przykładowych projektów w www ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Dla project-a utwórz .servbay.config z Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Dla project-b utwórz .servbay.config z Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Zweryfikuj przełączanie się w terminalu ServBay:

   Otwórz terminal ServBay i wykonaj poniższe polecenia:

   # Przejdź do katalogu project-a
   cd /Applications/ServBay/www/project-a
   # Sprawdź wersję Node.js
   node -v
   # Oczekiwany wynik: v18.x.x
   
   # Przejdź do katalogu project-b
   cd ../project-b
   # Sprawdź wersję Node.js
   node -v
   # Oczekiwany wynik: v20.x.x
   
   # Wróć do katalogu project-a
   cd ../project-a
   # Sprawdź wersję Node.js
   node -v
   # Oczekiwany wynik: v18.x.x

Jak widać na przykładzie, ServBay automatycznie ładuje i stosuje ustawienia NODE_VERSION z najbliższego pliku .servbay.config, umożliwiając szybkie, bezproblemowe przełączanie wersji między projektami.

Poniżej ilustracja pokazująca, jak wersja Node.js automatycznie się zmienia wraz z przełączaniem się między katalogami różnych projektów (obraz przykładowy, rzeczywisty interfejs może wyglądać nieco inaczej):

Wskazówki i uwagi

• Plik .servbay.config musi być umieszczony w katalogu projektu lub jednym z katalogów nadrzędnych. ServBay szuka pliku w górę drzewa katalogów, wykorzystując pierwszy znaleziony (najbliższy) plik.
• Pracuj w terminalu zintegrowanym ServBay lub w zewnętrznym terminalu, który używa poprawnie skonfigurowanych zmiennych środowiskowych ServBay.
• Wartość NODE_VERSION musi odpowiadać wersji zainstalowanej i aktywowanej w aplikacji ServBay. Jeśli wskazana wersja nie jest dostępna, ServBay może przełączyć się na wersję domyślną lub nie znaleźć polecenia Node.js.
• Konfiguracja z .servbay.config działa tylko w bieżącej sesji terminala i jej podprocesach — nie wpływa na środowisko globalne systemu czy na inne procesy poza ServBay.

FAQ

Q: Co się stanie, jeśli w katalogu projektu nie ma pliku .servbay.config?

A: Jeśli ServBay nie znajdzie pliku .servbay.config w katalogu bieżącym ani w katalogach nadrzędnych, użyje ustawień globalnych lub domyślnej wersji Node.js (zwykle tej oznaczonej jako „domyślna” w ServBay).

Q: Jak sprawdzić, które wersje Node.js obsługuje ServBay?

A: Otwórz aplikację ServBay i przejdź do sekcji „Pakiety” (Packages) w lewym menu. Tam zobaczysz wszystkie dostępne oraz zainstalowane wersje pakietów, w tym różnych wersji Node.js. Możesz aktywować lub dezaktywować wybrane wersje.

Q: Czy ustawienia z .servbay.config wpłyną na cały mój system?

A: Nie. Konfiguracja z pliku .servbay.config jest tymczasowa i dotyczy wyłącznie bieżącej sesji terminala ServBay lub procesów wykorzystujących zmienne środowiskowe ServBay. Nie zmienia globalnych zmiennych systemowych ani nie wpływa na programy uruchamiane poza środowiskiem ServBay. Taka izolacja to jeden z kluczowych mechanizmów ServBay.

Q: Czy poza NODE_VERSION można w .servbay.config ustawić inne zmienne ServBay?

A: Tak, plik .servbay.config jest uniwersalnym mechanizmem ServBay do konfigurowania zmiennych środowiskowych dla projektu. Oprócz ustawień powiązanych z Node.js, możesz tu przypisywać inne zmienne, które będą aktywne dla poleceń uruchamianych z katalogu projektu. Obsługiwane opcje mogą się zmieniać w kolejnych wersjach ServBay, ale podstawową funkcją jest możliwość ustawiania dowolnych zmiennych środowiskowych.

Podsumowanie

Dzięki wykorzystaniu pliku .servbay.config w ServBay możesz w łatwy i skuteczny sposób przypisać i zarządzać niezależnymi wersjami Node.js dla każdego projektu lokalnego. To rozwiązanie jest lżejsze i wygodniejsze od tradycyjnych menedżerów wersji czy kontenerów, doskonale wpisuje się w zintegrowane środowisko ServBay i pozwala budować stabilniejszy, bardziej współdzielony workflow programistyczny. Zacznij korzystać z .servbay.config w swoich projektach i przekonaj się, jak wygodny jest ServBay!