Jak zainstalować NVM dla Node.js na Ubuntu: Kompletny przewodnik techniczny

NVM (Node Version Manager) to skrypt powłoki zgodny z POSIX, który instaluje wiele izolowanych środowisk uruchomieniowych Node.js na jednej maszynie i zarządza nimi bez konieczności posiadania uprawnień roota ani modyfikowania ścieżek systemowych. Każda wersja Node.js znajduje się we własnym katalogu w `~/.nvm/versions/node/`, zapewniając pełną, wolną od konfliktów izolację między projektami.

Ten przewodnik przeprowadza przez instalację NVM na poziomie produkcyjnym na Ubuntu (20.04, 22.04 i 24.04), obejmując nie tylko podstawowe polecenia, ale także przypadki brzegowe plików profilu powłoki, automatyzację przepływu pracy `.nvmrc`, migrację pakietów globalnych oraz pułapki specyficzne dla serwerów, które większość poradników pomija.

Dlaczego NVM zamiast systemowego menedżera pakietów

Instalacja Node.js przez `apt` umieszcza jeden, ogólnosystemowy plik binarny w `/usr/bin/node`. Jego aktualizacja wpływa jednocześnie na każdą aplikację na hoście. Na współdzielonej maszynie deweloperskiej lub VPS obsługującym wiele projektów Node.js tworzy to niestabilne, trudne do odtworzenia środowiska.

NVM rozwiązuje ten problem, instalując każdą wersję Node.js w katalogu przestrzeni użytkownika i manipulując `PATH` na poziomie powłoki. Efektem jest kontrola wersji per użytkownik i per projekt bez żadnego wpływu na stan pakietów systemu operacyjnego.

NVM a inne menedżery wersji Node.js

NVM pozostaje najszerzej udokumentowaną i najlepiej wspieraną przez ekosystem opcją, co czyni go najbezpieczniejszym domyślnym wyborem dla zespołów i środowisk serwerowych, gdzie odtwarzalność jest ważniejsza niż surowa szybkość uruchamiania.

Wymagania wstępne

• Ubuntu 20.04, 22.04 lub 24.04 (wersja desktopowa lub serwerowa)
• Konto użytkownika bez uprawnień roota z uprawnieniami `sudo`
• Zainstalowany `curl` lub `wget` (oba są domyślnie obecne na większości obrazów Ubuntu)
• Podstawowa znajomość Bash lub Zsh

Aby potwierdzić typ powłoki i wersję Ubuntu przed rozpoczęciem:

“`bash

echo $SHELL

lsb_release -a

“`

Krok 1: Aktualizacja indeksu pakietów systemowych

Odśwież listy pakietów APT, aby upewnić się, że wszelkie zależności rozwiązywane podczas sesji są aktualne:

“`bash

sudo apt-get update && sudo apt-get upgrade -y

“`

Potwierdź również dostępność `curl`:

“`bash

curl –version || sudo apt-get install -y curl

“`

Krok 2: Pobieranie i uruchamianie skryptu instalacyjnego NVM

Oficjalny instalator NVM jest hostowany na GitHub. Klonuje repozytorium NVM do `~/.nvm` i dołącza niezbędny blok inicjalizacji powłoki do pliku profilu.

Opcja A — Używając curl (zalecane):

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Opcja B — Używając wget:

“`bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Zawsze sprawdzaj najnowszy tag wydania na stronie wydań NVM na GitHub przed uruchomieniem. Zastąp `v0.40.1` aktualnym stabilnym tagiem, jeśli opublikowano nowszą wersję.

Co faktycznie robi instalator:

1. Klonuje repozytorium NVM do `~/.nvm`
2. Wykrywa aktywną powłokę (`bash`, `zsh`, `ksh` lub `fish`)
3. Dołącza następujący blok inicjalizacji do odpowiedniego pliku profilu (`~/.bashrc`, `~/.zshrc`, `~/.profile` lub `~/.bash_profile`)

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

“`

Uwaga dotycząca bezpieczeństwa: Przekazywanie zdalnego skryptu bezpośrednio do `bash` jest powszechnym wzorcem, ale niesie ze sobą nieodłączne ryzyko. W przypadku serwerów produkcyjnych lub środowisk serwera dedykowanego najpierw pobierz skrypt, sprawdź go, a następnie wykonaj:

“`bash

curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh

cat install_nvm.sh # review before running

bash install_nvm.sh

“`

Krok 3: Aktywacja NVM w bieżącej sesji powłoki

Instalator modyfikuje Twój profil, ale zmiany te wchodzą w życie dopiero w nowych sesjach powłoki. Aby aktywować NVM natychmiast bez otwierania nowego terminala:

Dla Bash:

“`bash

source ~/.bashrc

“`

Dla Zsh:

“`bash

source ~/.zshrc

“`

Ręczne ładowanie (działa w każdej powłoce):

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

“`

Częsta pułapka: plik profilu nie jest ładowany w powłokach nieinteraktywnych

W Ubuntu `~/.bashrc` jest ładowany tylko dla interaktywnych powłok bez logowania. Jeśli łączysz się przez SSH (powłoka logowania), Bash zamiast tego odczytuje `~/.bash_profile` lub `~/.profile`. Jeśli NVM nie jest znaleziony po zalogowaniu przez SSH, dodaj blok ładowania do `~/.bash_profile`:

“`bash

echo 'source ~/.bashrc' >> ~/.bash_profile

source ~/.bash_profile

“`

Jest to jeden z najczęściej spotykanych problemów podczas konfigurowania NVM na zdalnych serwerach.

Krok 4: Weryfikacja instalacji NVM

“`bash

nvm –version

“`

Oczekiwane wyjście (numer wersji może się różnić):

“`

0.40.1

“`

Jeśli polecenie zwraca `nvm: command not found`, profil powłoki nie został poprawnie załadowany. Ponownie uruchom polecenie ładowania z Kroku 3 i sprawdź, czy blok inicjalizacji istnieje w pliku profilu:

“`bash

grep -n 'NVM_DIR' ~/.bashrc

“`

Krok 5: Instalacja Node.js przy użyciu NVM

Instalacja najnowszego wydania LTS (zalecane dla produkcji)

“`bash

nvm install –lts

“`

Flaga `–lts` instaluje najnowsze wydanie Long-Term Support, które otrzymuje poprawki bezpieczeństwa przez 30 miesięcy. W przypadku obciążeń produkcyjnych na VPS z cPanel lub dowolnym środowisku serwerowym, LTS jest zdecydowanie preferowane nad bieżącym wydaniem.

Instalacja absolutnie najnowszego wydania

“`bash

nvm install node

“`

Instalacja konkretnej wersji

“`bash

nvm install 20.14.0

“`

Lista wszystkich dostępnych zdalnych wersji

“`bash

nvm ls-remote

“`

Aby filtrować tylko wersje LTS:

“`bash

nvm ls-remote –lts

“`

Krok 6: Weryfikacja aktywnych wersji Node.js i npm

“`bash

node -v

npm -v

“`

Potwierdź również ścieżkę binarną, aby upewnić się, że nie używasz przypadkowo ogólnosystemowej instalacji Node.js:

“`bash

which node

Expected: /home/<username>/.nvm/versions/node/v20.14.0/bin/node

“`

Krok 7: Zarządzanie wieloma wersjami Node.js

Lista wszystkich lokalnie zainstalowanych wersji

“`bash

nvm ls

“`

Przykładowe wyjście:

“`

-> v20.14.0

v18.20.3

v16.20.2

default -> lts/* (-> v20.14.0)

node -> stable (-> v20.14.0) (default)

lts/* -> lts/iron (-> v20.14.0)

“`

Przełączanie między wersjami

“`bash

nvm use 18.20.3

“`

Ta zmiana dotyczy tylko bieżącej sesji terminala. Otwarcie nowego terminala przywraca domyślny alias.

Sprawdzanie aktualnie aktywnej wersji

“`bash

nvm current

“`

Krok 8: Ustawianie trwałej domyślnej wersji Node.js

Aby ustawić konkretną wersję jako domyślną dla wszystkich nowych sesji powłoki:

“`bash

nvm alias default 20.14.0

“`

Możesz również nadać alias linii wydania zamiast konkretnej wersji patch, co automatycznie śledzi aktualizacje w tej linii:

“`bash

nvm alias default lts/*

“`

Krok 9: Automatyzacja przełączania wersji za pomocą `.nvmrc`

Jest to jedna z najpotężniejszych i najrzadziej używanych funkcji NVM. Umieść plik `.nvmrc` w katalogu głównym projektu zawierający wymaganą wersję Node.js:

“`bash

echo "20.14.0" > /path/to/your/project/.nvmrc

“`

Następnie, gdy przejdziesz `cd` do tego katalogu:

“`bash

nvm use

Found '/path/to/your/project/.nvmrc' with version <20.14.0>

Now using node v20.14.0

“`

Automatyczne przełączanie wersji przy zmianie katalogu

Dodaj poniższe do swojego `~/.bashrc` (lub `~/.zshrc`), aby automatycznie wyzwalać `nvm use` za każdym razem, gdy wejdziesz do katalogu zawierającego plik `.nvmrc`:

Dla Bash:

“`bash

cdnvm() {

command cd "$@" || return $?

nvm_path="$(nvm_find_up .nvmrc | command tr -d 'n')"

if [[ ! $nvm_path = *[^[:space:]]* ]]; then

declare default_version

default_version="$(nvm version default)"

if [[ $default_version == "N/A" ]]; then

nvm use default

elif [[ $(nvm current) != "$default_version" ]]; then

nvm use default

fi

elif [[ -r "$nvm_path/.nvmrc" && -r "$nvm_path" ]]; then

declare nvm_version

nvm_version=$(<"$nvm_path/.nvmrc")

declare locally_resolved_nvm_version

locally_resolved_nvm_version="$(nvm ls –no-colors "$nvm_version" | command tail -1 | command tr -d '->*' | command tr -d '[:space:]')"

if [[ "$locally_resolved_nvm_version" == "N/A" ]]; then

nvm install "$nvm_version"

elif [[ $(nvm current) != "$locally_resolved_nvm_version" ]]; then

nvm use "$nvm_version"

fi

fi

}

alias cd='cdnvm'

“`

Ten wzorzec jest szczególnie cenny w potokach CI/CD i środowiskach zespołowych, gdzie wielu deweloperów pracuje nad projektami z różnymi wymaganiami dotyczącymi środowiska uruchomieniowego.

Krok 10: Zarządzanie globalnymi pakietami npm między wersjami

Każda wersja Node.js zainstalowana przez NVM ma własny izolowany katalog `node_modules` dla globalnie zainstalowanych pakietów. Oznacza to, że narzędzia takie jak `pm2`, `yarn` lub `typescript` zainstalowane globalnie w wersji `v18` nie są dostępne w wersji `v20`.

Instalacja pakietu globalnego dla aktywnej wersji

“`bash

npm install -g yarn

npm install -g pm2

npm install -g typescript

“`

Migracja pakietów globalnych podczas instalacji nowej wersji

NVM udostępnia wbudowaną flagę do kopiowania wszystkich pakietów globalnych z jednej wersji do nowej instalacji:

“`bash

nvm install 20.14.0 –reinstall-packages-from=18.20.3

“`

Jest to kluczowe podczas aktualizacji wersji Node.js na serwerze obsługującym trwałe procesy zarządzane przez PM2 lub podobne narzędzia.

Lista globalnie zainstalowanych pakietów dla bieżącej wersji

“`bash

npm list -g –depth=0

“`

Krok 11: Odinstalowywanie wersji Node.js

Przed odinstalowaniem przełącz się z wersji, którą chcesz usunąć:

“`bash

nvm use 20.14.0

nvm uninstall 16.20.2

“`

Nie można odinstalować aktualnie aktywnej wersji. Próba wykonania tej operacji zwraca błąd.

Zaawansowane: Używanie NVM w środowiskach nieinteraktywnych (CI/CD, Cron, Systemd)

NVM opiera się na plikach inicjalizacji powłoki, które nie są ładowane w powłokach nieinteraktywnych. Powoduje to błędy `node: command not found` w zadaniach cron, plikach jednostek systemd i niektórych środowiskach CI.

Rozwiązanie 1: Użyj pełnej ścieżki binarnej

“`bash

/home/username/.nvm/versions/node/v20.14.0/bin/node /path/to/app.js

“`

Rozwiązanie 2: Załaduj NVM jawnie w skryptach

“`bash

#!/bin/bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm use 20.14.0

node /path/to/app.js

“`

Rozwiązanie 3: Utwórz dowiązanie symboliczne dla dostępu ogólnosystemowego (używaj ostrożnie)

“`bash

sudo ln -s /home/username/.nvm/versions/node/v20.14.0/bin/node /usr/local/bin/node

“`

To podejście poświęca izolację per użytkownik, ale jest czasem konieczne dla usług systemd działających jako dedykowany użytkownik usługi.

NVM na hostingu współdzielonym vs. VPS vs. serwery dedykowane

Dla zespołów uruchamiających aplikacje Node.js obok innych usług, VPS zapewnia kontrolę na poziomie powłoki, której wymaga NVM, bez narzutu związanego z zarządzaniem fizycznym sprzętem.

Praktyczna lista kontrolna kluczowych wniosków

Użyj tego jako odniesienia do wdrożenia i konfiguracji:

• Sprawdź typ powłoki (`echo $SHELL`) przed instalacją — Zsh i Bash wymagają różnych plików profilu
• Zawsze używaj `–lts` dla produkcyjnych instalacji Node.js; zarezerwuj `node` (najnowszy) dla prac eksperymentalnych
• Zatwierdź `.nvmrc` do kontroli wersji, aby każdy członek zespołu i runner CI używał identycznej wersji środowiska uruchomieniowego
• Używaj `–reinstall-packages-from` podczas aktualizacji wersji Node.js, aby uniknąć ręcznej ponownej instalacji narzędzi globalnych
• Ładuj NVM jawnie w każdym skrypcie nieinteraktywnym (cron, systemd, potoki CI) — nigdy nie zakładaj, że profil powłoki został załadowany
• Audytuj pakiety globalne per wersja za pomocą `npm list -g –depth=0` po przełączeniu wersji, aby wcześnie wykryć brakujące zależności
• Przypinaj dokładne wersje w `.nvmrc` (np. `20.14.0`) zamiast aliasów (np. `lts`) dla maksymalnej odtwarzalności w produkcji
• Sprawdzaj `which node` po przełączeniu wersji, aby potwierdzić, że nie używasz przypadkowo binarnego pliku zainstalowanego systemowo

Często zadawane pytania

Czy NVM wymaga sudo lub dostępu roota do instalacji Node.js?

Nie. NVM instaluje wszystko w `~/.nvm` w katalogu domowym bieżącego użytkownika. Do instalowania lub przełączania wersji Node.js nie są potrzebne uprawnienia roota. Jest to jedna z jego głównych zalet w porównaniu z systemowymi menedżerami pakietów.

Dlaczego po instalacji pojawia się `nvm: command not found`?

Blok inicjalizacji NVM został dodany do profilu powłoki, ale profil nie został ponownie załadowany w bieżącej sesji. Uruchom `source ~/.bashrc` (Bash) lub `source ~/.zshrc` (Zsh). Jeśli błąd utrzymuje się po otwarciu nowego terminala, sprawdź, czy blok inicjalizacji został faktycznie zapisany do właściwego pliku za pomocą `grep NVM_DIR ~/.bashrc`.

Czy wielu użytkowników na tym samym serwerze może mieć różne wersje Node.js przez NVM?

Tak. Ponieważ NVM instaluje do katalogu domowego każdego użytkownika (`~/.nvm`), każdy użytkownik utrzymuje całkowicie niezależny zestaw wersji Node.js i pakietów globalnych. Jest to właściwa architektura dla serwerów wielodostępnych.

Co dzieje się z globalnie zainstalowanymi pakietami npm, gdy przełączam wersje Node.js za pomocą NVM?

Każda wersja Node.js ma własny izolowany katalog pakietów globalnych. Pakiety zainstalowane globalnie w jednej wersji nie są widoczne w innej. Użyj `nvm install <new-version> –reinstall-packages-from=<old-version>`, aby automatycznie je zmigrować.

Czy NVM nadaje się do uruchamiania aplikacji Node.js w produkcji na serwerze?

NVM doskonale nadaje się do zarządzania używaną wersją Node.js, ale do zarządzania procesami w produkcji należy połączyć go z menedżerem procesów takim jak PM2 lub używać plików jednostek systemd. Upewnij się, że te środowiska nieinteraktywne jawnie ładują NVM lub odwołują się do pełnej ścieżki binarnej, jak opisano w sekcji CI/CD powyżej.