Instalacja Node.js i npm na Debianie

Node.js to środowisko uruchomieniowe, na którym działa mnóstwo aplikacji webowych, interfejsów API i botów Discord. Na własnym serwerze zainstalujesz je w kilka minut. W tym poradniku skonfigurujesz Node.js razem z npm na Debianie 13, Debianie 12 i Debianie 11. Na Ubuntu działają te same polecenia.

Kluczowy jest wybór właściwej wersji. Popularne kiedyś poradniki dla Node.js 10 i Node.js 12 są już nieaktualne: obie wersje od lat nie dostają aktualizacji bezpieczeństwa i nie powinny działać na żadnym serwerze.

Którą wersję Node.js zainstalować?

Nowa wersja główna Node.js ukazuje się dwa razy w roku. Tylko parzyste numery wersji trafiają do linii LTS (Long Term Support) i są potem utrzymywane przez około trzy lata. Wersje nieparzyste to krótko żyjące linie rozwojowe, nieprzeznaczone do systemów produkcyjnych.

• Node.js 24 LTS („Krypton”): aktualna rekomendacja dla nowych projektów i serwerów produkcyjnych.
• Node.js 22 LTS: nadal szeroko stosowany, sensowny wybór, jeśli aplikacja wyraźnie wymaga tej wersji.
• Node.js 10 i 12: bez wsparcia odpowiednio od 2021 i 2022 roku. Już ich nie używaj.

W razie wątpliwości sprawdź wymagania swojej aplikacji. Wiele projektów podaje wymaganą wersję w polu „engines” pliku package.json.

Wymagania wstępne

• Dostęp root do twojego serwera VPS lub serwera root przez SSH.
• Aktualny Debian. Najpierw zaktualizuj system:

apt update && apt upgrade -y

Do pobrania repozytorium potrzebujesz jeszcze kilku standardowych narzędzi:

apt install -y ca-certificates curl gnupg

Wariant 1: Node.js z repozytoriów Debiana

Najprostsza droga prowadzi przez repozytoria dostarczane razem z systemem:

apt install nodejs npm -y

Zaleta: aktualizacje przychodzą automatycznie razem z pozostałymi aktualizacjami systemu. Wada: pakiety Debiana są zwykle o jedną lub dwie wersje główne w tyle za aktualną linią LTS. Którą wersję masz do dyspozycji, sprawdzisz przed instalacją poleceniem:

apt-cache policy nodejs

Stan na lipiec 2026, repozytoria dostarczają: Debian 13 „Trixie” Node.js 20.19, Debian 12 „Bookworm” Node.js 18.20, Ubuntu 24.04 Node.js 18.19, Ubuntu 22.04 Node.js 12.22. Jeśli ci to wystarcza, na tym kończysz. Jeśli potrzebujesz aktualnej linii LTS, wybierz wariant 2.

Wariant 2: instalacja Node.js 24 LTS przez NodeSource

NodeSource udostępnia oficjalne repozytoria dla Debiana i Ubuntu. Dostaniesz dzięki temu dokładnie tę wersję główną, o którą ci chodzi, i nadal będziesz otrzymywać aktualizacje przez apt.

Dodanie klucza podpisu

Wcześniejsza droga przez apt-key odpadła. Od Debiana 11 klucze podpisu należą do osobnego katalogu w /etc/apt/keyrings/:

mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

Dodanie repozytorium i instalacja

Następnie dodaj repozytorium. Za pomocą zmiennej ustawiasz wersję główną, tutaj 24:

NODE_MAJOR=24
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

Dla Node.js 22 ustaw zamiast tego NODE_MAJOR=22. Potem następuje właściwa instalacja:

apt update
apt install nodejs -y

npm jest już zawarty w pakiecie NodeSource. Nie instaluj tutaj dodatkowo pakietu Debiana „npm”, bo powstanie konflikt pakietów.

Krótka droga przez skrypt instalacyjny

NodeSource oferuje dodatkowo skrypt, który łączy oba powyższe kroki:

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install nodejs -y

Wygodne, ale uruchamiasz z prawami root skrypt pobrany z sieci. Na serwerach produkcyjnych czystszym wyborem jest droga przez klucz i repozytorium.

Sprawdzenie instalacji

Na koniec sprawdź obie wersje:

node --version
npm --version

Jeśli przy node pojawi się wynik zaczynający się od v22., a przy npm numer wersji, instalacja się powiodła.

Jeśli chcesz używać yarn albo pnpm: oba włączysz przez Corepack, który jest częścią Node.js, osobna instalacja nie jest potrzebna:

corepack enable

Równoległa praca kilku wersji Node.js

Jeśli na jednym serwerze prowadzisz kilka aplikacji o różnych wymaganiach, pomoże Node Version Manager (nvm). Instaluje on Node.js w katalogu użytkownika, dzięki czemu kilka wersji może działać obok siebie, a przełączanie odbywa się osobno dla każdego projektu.

Po instalacji nvm (trzymaj się przy tym instrukcji z oficjalnego projektu) wystarczą te polecenia:

nvm install 24
nvm use 24
nvm alias default 24

Ważne: nvm należy zawsze do pojedynczego użytkownika. Usługi systemowe działające jako inny użytkownik nie znajdą tej instalacji Node.js. Dla usług pewniejszą drogą jest instalacja z pakietu.

Przejście na nowszą wersję

Jeśli później czeka cię zmiana na nową linię LTS, po prostu zmień numer wersji w repozytorium i zaktualizuj system:

NODE_MAJOR=24
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
apt update && apt install nodejs -y

Po skoku wersji przetestuj swoją aplikację. Między dwiema wersjami głównymi interfejsy mogą się zmienić, a starsze moduły natywne trzeba czasem zbudować na nowo.

Częste błędy

• „E: Unable to locate package nodejs”: po dodaniu repozytorium zabrakło polecenia apt update.
• Konflikt pakietów między nodejs a npm: obok pakietu NodeSource został zainstalowany pakiet Debiana „npm”. Usuń go poleceniem apt remove npm, odpowiednią wersję dostarcza już sam Node.js.
• „NO_PUBKEY” albo „signatures couldn't be verified”: klucz podpisu nie leży w /etc/apt/keyrings/ albo wiersz repozytorium nie zawiera pasującego odwołania signed-by.
• Nadal wyświetlana jest stara wersja: w systemie zostały resztki wcześniejszej instalacji. Usuń stare pliki w /etc/apt/sources.list.d/, które wskazują na nodesource, a potem zainstaluj ponownie.
• Pakiet npm przerywa kompilację: dla modułów natywnych brakuje narzędzi do budowania. Zainstaluj je poleceniem apt install -y build-essential python3.