Rozwiązywanie problemów z Node.js

Niniejsza dokumentacja ma na celu pomoc deweloperom korzystającym z lokalnego środowiska ServBay w rozwiązywaniu typowych problemów napotykanych podczas pracy z pakietami Node.js.

Nie można znaleźć wersji polecenia Node.js/npm/pnpm/yarn

Jeśli podczas korzystania z Node.js, npm, pnpm lub yarn w ServBay pojawia się komunikat o błędzie podobny do poniższego, oznacza to, że system nie może odnaleźć określonej wersji wykonawczej Node.js, której próbujesz użyć:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

Zwykle przyczyną jest brak zainstalowanej żądanej wersji Node.js w ServBay albo to, że chcesz korzystać z wersji Node.js zainstalowanej za pomocą innych narzędzi (np. nvm czy homebrew), lecz z powodu problemów z konfiguracją środowiska ServBay nie potrafi ich odnaleźć.

Wskazówka

Po zainstalowaniu ServBay system ustawia aliasy skryptów (Script Alias), które nadają priorytet pakietom Node.js zainstalowanym w ServBay. Gdy wskazana wersja Node.js nie jest dostępna w ServBay, mechanizm automatycznie próbuje odnaleźć domyślną wersję zainstalowaną przez nvm, a następnie przez homebrew. Jeśli żadna z tych lokalizacji nie zawiera poszukiwanej wersji, pojawia się powyższy błąd.

Analiza przyczyn:

1. Wersja Node.js, której próbujesz użyć, nie jest zainstalowana w aplikacji ServBay.
2. Masz zainstalowane nvm lub homebrew i oczekujesz, by zarządzały one wersjami Node.js, ale z powodu nieprawidłowej konfiguracji środowiska powłoki (szczególnie zmiennych środowiskowych PATH lub NVM_BIN) mechanizm ServBay nie potrafi znaleźć tych zewnętrznych instalacji.

Rozwiązania:

Jeśli korzystasz z nvm i masz w nim zainstalowaną wersję Node.js, lecz nadal pojawia się ten błąd, częstym powodem jest brak lub niepoprawna konfiguracja zmiennej środowiskowej NVM_BIN w ustawieniach powłoki. nvm podczas instalacji zazwyczaj ustawia tę zmienną automatycznie — wskazuje ona miejsce, gdzie przechowywana jest wykonywalna wersja Node.js i jest kluczowa dla poprawnego działania nvm.

Należy sprawdzić i poprawić konfigurację pliku powłoki (np. ~/.zshrc, ~/.bash_profile itp.), upewniając się, że powiązane z nvm zmienne, w tym NVM_BIN, są odpowiednio ustawione i eksportowane. Następnie należy ponownie załadować konfigurację powłoki (poprzez source ~/.zshrc lub restart terminala). Po tych krokach mechanizm ServBay powinien prawidłowo wykrywać wersje Node.js zarządzane przez nvm.

Jeżeli nie używasz nvm ani homebrew, lub chcesz korzystać z wersji Node.js zarządzanych przez ServBay, upewnij się, że odpowiednia wersja Node.js została zainstalowana w sekcji „Pakiety” aplikacji ServBay.

Błąd "Unsupported architecture" podczas używania pakietów npm takich jak node-sass

W przypadku użytkowników macOS z procesorem Apple Silicon (np. M1, M2, M3, M4 – architektura Arm64), podczas korzystania ze starszych pakietów npm opierających się na natywnych modułach (jak m.in. node-sass) mogą pojawić się błędy typu Unsupported architecture (arm64). Wynika to z faktu, że wiele takich pakietów udostępnia gotowe binaria lub konfiguracje kompilacji wyłącznie dla architektury x86_64.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

Analiza przyczyn:

Część pakietów npm zawiera kod w C++ lub innym języku wymagającym kompilacji. Taki kod musi być skompilowany na konkretną architekturę procesora. Starsze wersje tych pakietów często nie oferują wsparcia lub prekompilowanych plików pod architekturę Arm64 (np. Apple Silicon).

Rozwiązania:

1. Zamiana na nowoczesne zamienniki wspierające Arm64 (zalecane):

   Najskuteczniejszym i rekomendowanym rozwiązaniem jest przejście na nowoczesne alternatywy z pełnym wsparciem dla Arm64. Przykładowo, zamiast przestarzałego i coraz rzadziej utrzymywanego node-sass należy użyć pakietu sass, który jest aktywnie rozwijany i kompatybilny z nowymi środowiskami. Większość współczesnych projektów front-endowych korzysta już z sass.

   npm uninstall node-sass
   npm install --save-dev sass

2. Instalacja wersji Node.js dla architektury x86_64 w ServBay i uruchomienie przez Rosetta 2 (niezalecane):

   ServBay pozwala zainstalować pakiety Node.js przeznaczone dla architektury x86_64. Na komputerach Mac z Apple Silicon umożliwia to uruchomienie Node.js i zależnych modułów natywnych x86_64 przez warstwę tłumaczenia Rosetta 2. Instalacji tej wersji można dokonać w sekcji „Pakiety” aplikacji ServBay.

   

   Uwaga: Takie rozwiązanie nie jest zalecane na dłuższą metę — zależność od emulacji Rosetta 2 może powodować spowolnienia wydajności i dodatkowe problemy z kompatybilnością w porównaniu z natywnym środowiskiem Arm64. Zalecamy korzystanie z rozwiązania nr 1.

---