Jak zainstalować Node.js: Kompletny przewodnik techniczny dla wszystkich platform

Node.js to otwartoźródłowe, wieloplatformowe środowisko uruchomieniowe JavaScript zbudowane na silniku V8 Chrome, które wykonuje kod JavaScript poza środowiskiem przeglądarki. Jego nieblokujący, sterowany zdarzeniami model I/O sprawia, że jest dominującym wyborem do budowania wysokowydajnych API, aplikacji czasu rzeczywistego, mikroserwisów i narzędzi po stronie serwera. Prawidłowa instalacja Node.js — przy użyciu właściwej metody dla Twojego systemu operacyjnego i przepływu pracy — jest fundamentem stabilnego, odtwarzalnego środowiska programistycznego.

Ten przewodnik obejmuje wszystkie główne ścieżki instalacji: oficjalne instalatory, natywne menedżery pakietów systemu operacyjnego, binarne dystrybucje NodeSource oraz nvm (Node Version Manager). Omawia również zarządzanie wersjami, higienę globalnych pakietów i zagadnienia dotyczące serwerów produkcyjnych, które większość poradników całkowicie pomija.

Wybór właściwej metody instalacji

Zanim uruchomisz jakiekolwiek polecenie, zrozum, co każda metoda faktycznie daje — ponieważ zły wybór tworzy realne problemy operacyjne w przyszłości.

Kluczowa zasada decyzyjna: Na stacji roboczej programisty zawsze używaj nvm lub fnm. Na produkcyjnym serwerze Linux używaj repozytorium NodeSource lub obrazu kontenera. Nigdy nie używaj pakietu Node.js domyślnego menedżera pakietów systemu operacyjnego na Ubuntu/Debian — rutynowo dostarcza wersje opóźnione o lata względem aktualnego LTS.

Instalacja Node.js na Linux

Linux to miejsce, gdzie faktycznie działa większość produkcyjnych obciążeń Node.js. Prawidłowe wykonanie tego kroku ma tu większe znaczenie niż gdziekolwiek indziej. Jeśli wdrażasz na środowisko Hosting VPS, poniższe metody mają bezpośrednie zastosowanie do Twojego zdalnego serwera.

Metoda 1: Binarne dystrybucje NodeSource (zalecane dla serwerów)

NodeSource utrzymuje aktualne, podpisane pakiety .deb i .rpm, które precyzyjnie śledzą linie wydań LTS i Current Node.js. Jest to najbardziej niezawodne podejście dla produkcyjnych serwerów Linux.

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / CentOS / RHEL / Rocky Linux:

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

Po instalacji zweryfikuj zarówno środowisko uruchomieniowe, jak i dołączony menedżer pakietów:

node -v
npm -v

Krytyczna pułapka: Wzorzec curl | bash wykonuje zdalny skrypt jako root. W środowiskach wrażliwych na bezpieczeństwo najpierw pobierz skrypt, sprawdź go, a następnie wykonaj:

curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
less nodesource_setup.sh
sudo bash nodesource_setup.sh
sudo apt-get install -y nodejs

Metoda 2: nvm — Node Version Manager (zalecany dla programistów)

nvm instaluje Node.js całkowicie w Twoim katalogu domowym (~/.nvm), nie wymaga sudo i pozwala przełączać wersje per projekt lub per sesja powłoki. Jest to właściwe narzędzie dla każdej stacji roboczej lub serwera wielodostępnego, gdzie różne aplikacje wymagają różnych wersji Node.js.

Instalacja nvm:

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

Instalator dołącza niezbędną inicjalizację powłoki do ~/.bashrc, ~/.zshrc lub ~/.profile. Przeładuj powłokę:

source ~/.bashrc

Instalacja najnowszego wydania LTS:

nvm install --lts

Instalacja konkretnej wersji według numeru:

nvm install 20.14.0

Przełączanie między zainstalowanymi wersjami:

nvm use 18
nvm use 20

Ustawienie trwałego domyślnego dla nowych sesji powłoki:

nvm alias default 20

Lista wszystkich lokalnie zainstalowanych wersji:

nvm ls

Weryfikacja aktywnej wersji:

node -v
npm -v

Przypadek brzegowy — pliki .nvmrc: Umieść plik .nvmrc w katalogu głównym projektu zawierający tylko ciąg wersji (np. 20.14.0). Uruchomienie nvm use wewnątrz tego katalogu automatycznie wybiera właściwą wersję. Jest to niezbędne w środowiskach zespołowych, gdzie rozbieżności wersji powodują subtelne błędy.

echo "20.14.0" > .nvmrc
nvm use

Metoda 3: Systemowy menedżer pakietów (dopuszczalny dla narzędzi, nie dla produkcji)

Domyślne repozytoria apt lub dnf dostarczają wersje Node.js, które są często przestarzałe. Używaj tego tylko dla niekrytycznych narzędzi:

sudo apt-get update
sudo apt-get install -y nodejs npm

Na Fedora / RHEL 9+:

sudo dnf install nodejs

Instalacja Node.js na macOS

Metoda 1: Homebrew (zalecane)

Homebrew jest de facto menedżerem pakietów dla środowisk programistycznych macOS. Jeśli Homebrew nie jest jeszcze zainstalowany, postępuj zgodnie z instrukcjami na brew.sh.

brew install node

Aby zainstalować konkretną wersję główną (np. Node.js 20 LTS):

brew install node@20
brew link --overwrite node@20

Weryfikacja:

node -v
npm -v

Pułapka Homebrew: brew upgrade node zaktualizuje do najnowszej wersji, co może zepsuć projekty przypięte do starszego wydania. Jeśli zarządzasz wieloma projektami, używaj nvm również na macOS — przepływ pracy jest identyczny jak na Linux.

Metoda 2: nvm na macOS

Polecenia instalacji i użytkowania nvm są identyczne jak na Linux. Użytkownicy macOS z Zsh (domyślnym od Catalina) powinni potwierdzić, że ~/.zshrc zawiera blok inicjalizacji nvm po instalacji:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

Metoda 3: Oficjalny instalator .pkg

Pobierz instalator .pkg z nodejs.org, uruchom go i postępuj zgodnie z kreatorem. Jest to najprostsza ścieżka dla użytkowników, którzy potrzebują jednej wersji Node.js i nie planują jej zmieniać. Po instalacji otwórz Terminal i potwierdź:

node -v
npm -v

Instalacja Node.js na Windows

Metoda 1: Oficjalny instalator .msi

Pobierz instalator Windows (.msi) z nodejs.org. Wybierz kompilację LTS dla pracy zbliżonej do produkcji lub Current do eksperymentowania z najnowszymi funkcjami. Instalator automatycznie rejestruje Node.js w systemowym PATH.

Po instalacji otwórz Wiersz polecenia lub PowerShell i zweryfikuj:

node -v
npm -v

Ważne: Podczas kreatora instalatora istnieje opcjonalny krok instalacji Chocolatey i narzędzi do kompilacji dla natywnych modułów (dodatki C++). Włącz to, jeśli zależności Twojego projektu zawierają pakiety takie jak bcrypt, sharp lub moduły zależne od node-gyp. Pominięcie tego powoduje później niejasne błędy kompilacji.

Metoda 2: Chocolatey

Chocolatey to menedżer pakietów Windows umożliwiający skryptowane, powtarzalne instalacje — cenny przy konfiguracji maszyn programistycznych.

Otwórz podwyższony (Administrator) Wiersz polecenia lub PowerShell:

choco install nodejs-lts

Weryfikacja:

node -v
npm -v

Metoda 3: nvm-windows

Należy pamiętać, że nvm dla Linux/macOS nie działa na Windows. Odpowiednikiem dla Windows jest nvm-windows, oddzielny projekt z podobnym interfejsem.

Pobierz instalator ze strony wydań GitHub nvm-windows. Po instalacji:

nvm install lts
nvm use lts
node -v

Windows Subsystem for Linux (WSL2): Programiści wykonujący poważną pracę z Node.js na Windows powinni zdecydowanie rozważyć WSL2 z Ubuntu. Wewnątrz WSL2 instalacja Linux nvm działa identycznie jak na natywnym Linux, a doświadczenie programistyczne jest znacznie bardziej spójne ze środowiskami serwerów produkcyjnych.

Zrozumienie LTS vs. Current: którą wersję zainstalować

Node.js podąża za przewidywalnym harmonogramem wydań, który bezpośrednio wpływa na to, którą wersję powinieneś wdrożyć.

Zasada ogólna: Zawsze wdrażaj LTS na produkcji. Używaj Current tylko w izolowanych środowiskach programistycznych, gdy musisz testować zgodność z nadchodzącymi funkcjami Node.js.

Aktualizowanie Node.js

Przestarzałe wersje Node.js narażają Twoją aplikację na znane luki silnika V8, przestarzałe konfiguracje TLS i zepsutą zgodność zależności. Traktuj aktualizacje Node.js jako konserwację bezpieczeństwa, a nie opcjonalne ulepszenia.

Z nvm (wszystkie platformy):

nvm install --lts
nvm reinstall-packages <old-version>
nvm alias default node

Polecenie nvm reinstall-packages migruje globalnie zainstalowane pakiety ze starej wersji do nowej — szczegół, który większość przewodników pomija, a który oszczędza znaczną ilość czasu.

Z NodeSource na Debian/Ubuntu:

sudo apt-get update && sudo apt-get upgrade nodejs

Z Homebrew na macOS:

brew update && brew upgrade node

Z Chocolatey na Windows:

choco upgrade nodejs-lts

Zarządzanie globalnymi pakietami npm

Globalne pakiety npm instalują narzędzia CLI dostępne w całym systemie. Utrzymuj minimalną listę globalnych instalacji — narzędzia specyficzne dla projektu należą do devDependencies, a nie do globalnych instalacji, aby zapewnić odtwarzalne kompilacje w różnych środowiskach.

Instalacja globalnego pakietu:

npm install -g yarn
npm install -g pm2
npm install -g typescript

Lista wszystkich globalnie zainstalowanych pakietów:

npm list -g --depth=0

Usunięcie globalnego pakietu:

npm uninstall -g yarn

Popularne globalnie istotne pakiety produkcyjne:

• pm2 — Menedżer procesów dla aplikacji Node.js; obsługuje klastrowanie, automatyczny restart i zarządzanie logami na serwerach Linux
• typescript — Kompilator TypeScript (tsc)
• nodemon — Obserwator plików programistycznych, który automatycznie restartuje proces Node.js przy zmianach kodu
• dotenv-cli — Ładuje pliki .env dla konfiguracji specyficznej dla środowiska

nvm i globalne pakiety: Gdy przełączasz wersje Node.js za pomocą nvm, globalne pakiety zainstalowane w poprzedniej wersji nie są automatycznie dostępne. Zainstaluj je ponownie lub użyj nvm reinstall-packages <previous-version> do ich migracji.

Po instalacji: konfiguracja npm dla środowisk produkcyjnych

Czysta instalacja Node.js wymaga kilku dodatkowych kroków konfiguracyjnych, zanim będzie gotowa do produkcji.

Ustawienie rejestru npm (opcjonalne, dla prywatnych rejestrów lub mirrorów):

npm config set registry https://registry.npmjs.org/

Konfiguracja katalogu pamięci podręcznej npm (istotne na serwerach z ograniczoną przestrzenią /tmp):

npm config set cache /path/to/custom/cache

Wyłączenie generowania package-lock.json (tylko jeśli Twój zespół używa wyłącznie yarn.lock):

npm config set package-lock false

Ustawienie zmiennej środowiskowej Node.js dla produkcji:

export NODE_ENV=production

Dodaj to do /etc/environment lub pliku jednostki systemd Twojej aplikacji na serwerach Linux, aby zapewnić aktywację optymalizacji produkcyjnych przez Express.js, Next.js i inne frameworki.

Jeśli uruchamiasz aplikacje Node.js na Serwerze Dedykowanym, skonfiguruj pm2 jako usługę systemd, aby zagwarantować restart aplikacji po ponownym uruchomieniu serwera:

pm2 start app.js --name "my-app"
pm2 startup systemd
pm2 save

Uruchamianie Node.js za odwrotnym proxy

Na serwerach produkcyjnych aplikacje Node.js nigdy nie powinny być bezpośrednio wystawione na porcie 80 lub 443. Używaj Nginx lub Apache jako odwrotnego proxy i kończ TLS na warstwie proxy. Jest to krytyczna decyzja architektoniczna, którą krok instalacji bezpośrednio umożliwia.

Minimalna konfiguracja Nginx dla aplikacji Node.js działającej na porcie 3000:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Połącz to z ważnym certyfikatem TLS. Certyfikaty SSL są niezbędne dla każdej aplikacji Node.js obsługującej dane użytkowników, tokeny uwierzytelniania lub żądania API — nie są opcjonalne. Let’s Encrypt przez certbot jest standardową bezpłatną opcją; certyfikaty komercyjne są odpowiednie dla wdrożeń korporacyjnych.

Node.js na hostingu współdzielonym vs. VPS

Pytanie, które pojawia się często: czy Node.js może działać na hostingu współdzielonym?

Standardowe środowiska Hostingu Współdzielonego nie obsługują Node.js w żaden znaczący sposób. Hosting współdzielony jest zaprojektowany dla aplikacji PHP i nie zapewnia dostępu do powłoki, trwałego zarządzania procesami ani możliwości wiązania z niestandardowymi portami — a wszystkiego tego wymaga Node.js.

Dla każdego prawdziwego wdrożenia Node.js potrzebujesz co najmniej planu Hostingu VPS. VPS daje Ci dostęp root, trwały menedżer procesów jak pm2 i pełną kontrolę nad wersją Node.js i konfiguracją środowiska uruchomieniowego. Jeśli potrzebujesz zarządzanego panelu sterowania obok środowiska Node.js, VPS z cPanel zapewnia złoty środek między surowym dostępem VPS a hostingiem zarządzanym.

Dla intensywnych obliczeniowo obciążeń Node.js — wnioskowanie uczenia maszynowego, transkodowanie wideo lub przetwarzanie danych na dużą skalę — standardowy VPS może być niewystarczający. Hosting GPU zapewnia akcelerację sprzętową, której procesy Node.js ograniczone przez CPU nie mogą osiągnąć samodzielnie.

Lista kontrolna kluczowych wniosków technicznych

Użyj tego jako listy kontrolnej weryfikacji przed wdrożeniem:

• Wybór wersji: Potwierdź, że uruchamiasz aktywne wydanie LTS (node -v powinno zwracać parzystą wersję główną w aktywnym oknie wsparcia)
• Metoda instalacji odpowiada środowisku: nvm na maszynach programistycznych; NodeSource lub kontener na serwerach
• Wersja npm jest aktualna: Uruchom npm install -g npm@latest po instalacji Node.js — dołączone npm często nie jest najnowsze
• NODE_ENV jest ustawione: Zweryfikuj, że echo $NODE_ENV zwraca production we wszystkich środowiskach serwerowych
• Menedżer procesów jest skonfigurowany: pm2 list pokazuje działającą aplikację i pm2 startup zostało wykonane
• Odwrotne proxy jest na miejscu: Node.js nie jest bezpośrednio wystawiony na porcie 80/443
• TLS jest kończony na proxy: Ważny certyfikat jest zainstalowany i przekierowania HTTPS są wymuszane
• Lista globalnych pakietów jest minimalna: npm list -g --depth=0 pokazuje tylko niezbędne narzędzia CLI
• .nvmrc jest zacommitowany do repozytorium: Zapewnia, że wszyscy członkowie zespołu i potoki CI używają tej samej wersji Node.js
• Aktualizacje bezpieczeństwa są zautomatyzowane: Zadanie cron lub potok CI sprawdza nowe poprawki LTS co miesiąc

FAQ

Jaka jest różnica między Node.js LTS a Current i którą powinienem zainstalować?

Wydania LTS (Long Term Support) to parzyste wersje główne (18, 20, 22) wspierane przez 30 miesięcy z poprawkami bezpieczeństwa i stabilności. Wydania Current to nieparzyste wersje główne wspierane tylko przez 6 miesięcy. Zainstaluj LTS dla każdej produkcji lub pracy zespołowej. Używaj Current tylko do krótkoterminowego eksperymentowania z funkcjami.

Dlaczego nvm pokazuje „command not found” po instalacji?

Instalator nvm dołącza kod inicjalizacyjny do pliku RC Twojej powłoki (~/.bashrc lub ~/.zshrc), ale bieżąca sesja terminala nie przeładowała go. Uruchom source ~/.bashrc (lub source ~/.zshrc dla Zsh) lub otwórz nowe okno terminala. Jeśli problem nadal występuje, ręcznie sprawdź, czy blok inicjalizacji nvm istnieje na końcu Twojego pliku RC.

Czy mogę uruchamiać wiele wersji Node.js jednocześnie na tym samym serwerze?

Tak, z nvm. Każda wersja jest instalowana we własnym katalogu pod ~/.nvm/versions/. Możesz przełączać aktywną wersję per sesja powłoki za pomocą nvm use <version> lub per projekt używając pliku .nvmrc. Różne procesy działające na różnych wersjach Node.js mogą współistnieć bez konfliktu.

Dlaczego nie powinienem instalować Node.js z domyślnego repozytorium apt Ubuntu/Debian?

Domyślne repozytoria Ubuntu i Debian dostarczają wersje Node.js, które często są dwie do czterech wersji głównych za aktualnym LTS. Na przykład Ubuntu 22.04 domyślnie dostarcza Node.js 12 — wersję, która osiągnęła koniec życia w 2022 roku. Zawsze używaj repozytorium NodeSource lub nvm, aby uzyskać obsługiwane, aktualne wydanie.

Jak całkowicie odinstalować Node.js i zacząć od nowa?

Metoda zależy od sposobu instalacji. Dla instalacji NodeSource: sudo apt-get remove nodejs && sudo apt-get autoremove. Dla nvm: nvm uninstall <version> dla konkretnych wersji lub usuń cały katalog ~/.nvm i usuń linie inicjalizacyjne z pliku RC. Dla Homebrew: brew uninstall node. Dla oficjalnego instalatora na macOS/Windows użyj standardowego dezinstalatora aplikacji systemu i ręcznie usuń wszelkie pozostałe katalogi pod /usr/local/lib/node_modules lub %AppData%npm.