Jak zainstalować i skonfigurować Node.js i NPM w systemie Windows

Node.js to otwartoźródłowe, wieloplatformowe środowisko uruchomieniowe JavaScript zbudowane na silniku V8 Chrome, które wykonuje kod JavaScript poza przeglądarką. NPM (Node Package Manager) to domyślny menedżer pakietów dołączony do Node.js, zapewniający dostęp do ponad dwóch milionów pakietów wielokrotnego użytku. Razem tworzą podstawowy łańcuch narzędzi do budowania aplikacji po stronie serwera, narzędzi CLI, REST API i pełnostackowych projektów JavaScript na Windows.

Ten przewodnik obejmuje kompletną instalację, weryfikację, konfigurację i przepływ pracy pierwszej aplikacji dla Node.js i NPM na Windows — w tym zarządzanie wersjami, rozwiązywanie problemów z PATH, zakres pakietów globalnych i lokalnych oraz kwestie produkcyjne, które większość poradników pomija.

Wybór właściwej wersji Node.js przed instalacją

Harmonogram wydań Node.js podąża za przewidywalnym rytmem, który bezpośrednio wpływa na Twój wybór:

Wersje LTS mają parzyste numery główne (np. 20.x, 22.x) i otrzymują krytyczne poprawki bezpieczeństwa przez 30 miesięcy. Wydania Current mają nieparzyste numery główne i przechodzą do statusu LTS po sześciu miesiącach, jeśli spełniają kryteria stabilności.

Dla większości programistów i wdrożeń serwerowych — w tym aplikacji hostowanych na VPS Hosting — LTS jest właściwym wyborem. Gałąź Current jest odpowiednia tylko wtedy, gdy konkretnie potrzebujesz funkcji V8 lub API Node.js, które nie trafiło jeszcze do aktywnej linii LTS.

NVM dla Windows: profesjonalna alternatywa dla bezpośredniej instalacji

Przed przystąpieniem do instalacji MSI zastanów się, czy potrzebujesz nvm-for-windows (Node Version Manager dla Windows). Bezpośredni instalator wiąże system z jedną wersją Node.js. NVM pozwala instalować wiele wersji obok siebie i przełączać się między nimi dla każdego projektu — co jest kluczowe przy utrzymywaniu starszych baz kodu obok nowoczesnych.

Zainstaluj nvm-for-windows z oficjalnej strony wydań GitHub, a następnie użyj:

“`

nvm install 20.14.0

nvm use 20.14.0

nvm list

“`

Jeśli zarządzasz jednym projektem lub uczysz się Node.js po raz pierwszy, instalator MSI jest wystarczający. W środowiskach profesjonalnych NVM jest zdecydowanie zalecany.

Krok 1: Pobierz instalator Node.js

1. Przejdź na oficjalną stronę Node.js pod adresem nodejs.org.
2. Wybierz zakładkę LTS i pobierz instalator Windows (`.msi`) dla swojej architektury. Niemal wszystkie nowoczesne maszyny z Windows są 64-bitowe (`node-v20.x.x-x64.msi`). Kompilacje ARM64 są dostępne dla urządzeń z Windows on ARM.
3. Przed uruchomieniem instalatora zweryfikuj sumę kontrolną SHA-256 pobranego pliku względem wartości opublikowanych na stronie pobierania Node.js. Ten krok jest niezbędny w każdym środowisku dbającym o bezpieczeństwo.

Aby zweryfikować sumę kontrolną w PowerShell:

“`powershell

Get-FileHash .node-v20.14.0-x64.msi -Algorithm SHA256

“`

Porównaj wynik z opublikowanym hashem. Niezgodność wskazuje na uszkodzone lub zmodyfikowane pobranie.

Krok 2: Zainstaluj Node.js i NPM

1. Kliknij dwukrotnie pobrany plik `.msi`, aby uruchomić Kreator instalacji.
2. Kliknij Dalej na ekranie powitalnym.
3. Zaakceptuj Umowę Licencyjną Użytkownika Końcowego i kliknij Dalej.
4. Domyślna ścieżka instalacji to `C:Program Filesnodejs`. Jeśli nie masz konkretnego powodu, aby ją zmienić (np. inny dysk ze względu na zarządzanie miejscem), pozostaw ją bez zmian.
5. Na ekranie Instalacja niestandardowa upewnij się, że zaznaczony jest menedżer pakietów npm. Jest on domyślnie włączony.
6. Na ekranie Narzędzia dla modułów natywnych zobaczysz opcję automatycznej instalacji Chocolatey, Python i Visual Studio Build Tools. Zaznacz to pole, jeśli przewidujesz instalację pakietów NPM zawierających natywne dodatki C++ (np. `bcrypt`, `sharp`, pakiety zależne od `node-gyp`). Ten krok instaluje kilka gigabajtów narzędzi — pomiń go, jeśli potrzebujesz tylko pakietów w czystym JavaScript.
7. Kliknij Zainstaluj, a następnie Zakończ.

Instalator automatycznie rejestruje `node.exe` i `npm.cmd` w zmiennej środowiskowej `PATH` systemu w katalogu `C:Program Filesnodejs`.

Co instalator faktycznie robi z Twoim systemem

Zrozumienie efektów ubocznych zapobiega przyszłym problemom z debugowaniem:

• Dodaje `C:Program Filesnodejs` do systemowego PATH (dostępnego dla wszystkich użytkowników).
• Tworzy `C:Users<username>AppDataRoamingnpm` jako domyślny globalny prefiks pakietów.
• Rejestruje Node.js w rejestrze Windows pod `HKLMSOFTWARENode.js`.
• Instaluje `npx` (program uruchamiający pakiety NPM) obok `npm`.

Krok 3: Zweryfikuj instalację

Otwórz nowe okno Wiersza polecenia lub PowerShell. Słowo „nowe” ma znaczenie — istniejące sesje terminala buforują stary PATH i nie będą odzwierciedlać zmian wprowadzonych przez instalator.

“`

node -v

“`

Oczekiwany wynik: `v20.14.0` (lub zainstalowana wersja)

“`

npm -v

“`

Oczekiwany wynik: `10.x.x`

“`

npx -v

“`

Oczekiwany wynik: zgodny lub zbliżony do wersji npm

Jeśli `node` nie jest rozpoznawany, PATH nie został poprawnie zaktualizowany. Napraw to ręcznie:

1. Otwórz Właściwości systemu > Zaawansowane > Zmienne środowiskowe.
2. W sekcji Zmienne systemowe znajdź `Path` i kliknij Edytuj.
3. Dodaj `C:Program Filesnodejs`, jeśli go brakuje.
4. Kliknij OK, zamknij wszystkie okna terminala i otwórz je ponownie.

Diagnozowanie typowych problemów po instalacji

Problem: `npm` jest rozpoznawany, ale `node` nie (lub odwrotnie).

Przyczyna: Niekompletny wpis PATH lub konfliktująca instalacja z Chocolatey lub poprzedniej konfiguracji NVM.

Rozwiązanie: Uruchom `where node` i `where npm`, aby zidentyfikować, które pliki binarne są rozwiązywane. Usuń nieaktualne wpisy.

Problem: Błędy uprawnień `EACCES` podczas uruchamiania `npm install -g`.

Przyczyna: Katalog globalnego prefiksu nie ma uprawnień zapisu dla bieżącego użytkownika.

Rozwiązanie: Zmień globalny prefiks na katalog należący do użytkownika (omówione w Kroku 5).

Problem: `node` otwiera Microsoft Store zamiast uruchamiać Node.js.

Przyczyna: Windows 10/11 zawiera alias wykonywania aplikacji dla `node`, który przekierowuje do Store.

Rozwiązanie: Przejdź do Ustawienia > Aplikacje > Aliasy wykonywania aplikacji i wyłącz aliasy dla `python.exe` i `node.exe` (jeśli są obecne).

Krok 4: Zaktualizuj NPM do najnowszej wersji

Wersja NPM dołączona do instalatora Node.js jest zazwyczaj o jedną lub dwie wersje mniejsze od bieżącego wydania. Zaktualizuj ją natychmiast po instalacji:

“`

npm install -g npm@latest

“`

Flaga `-g` instaluje pakiet w globalnym katalogu prefiksu, udostępniając go w całym systemie. Po aktualizacji ponownie zweryfikuj:

“`

npm -v

“`

Ważny przypadek brzegowy: W Windows aktualizacja NPM globalnie może czasami pozostawić nieaktualny `npm.cmd` w `C:Program Filesnodejs` wskazujący na starą wersję, podczas gdy nowa wersja jest zainstalowana w `C:Users<username>AppDataRoamingnpm`. Jeśli `npm -v` nadal pokazuje starą wersję po aktualizacji, sprawdź, który plik binarny jest pierwszy w PATH:

“`

where npm

“`

Ścieżka pod `AppDataRoamingnpm` powinna pojawić się przed `C:Program Filesnodejs` w wynikach. Jeśli nie, odpowiednio zmień kolejność wpisów PATH.

Krok 5: Skonfiguruj NPM dla swojego środowiska

Konfiguracja NPM jest przechowywana w pliku `.npmrc`, który może istnieć na trzech poziomach: per-projekt, per-użytkownik (`C:Users<username>.npmrc`) i globalny (`C:Program Filesnodejsnode_modulesnpmnpmrc`). Ustawienia per-projekt zastępują ustawienia per-użytkownik, które zastępują ustawienia globalne.

Zmień globalny prefiks pakietów

Domyślny globalny prefiks (`AppDataRoamingnpm`) działa dla większości użytkowników, ale na współdzielonych serwerach lub gdy obowiązują limity dyskowe, możesz chcieć go przekierować:

“`

npm config set prefix "D:NodeGlobal"

“`

Po zmianie prefiksu dodaj nowy podkatalog `bin` do swojego PATH:

“`

setx PATH "%PATH%;D:NodeGlobal"

“`

Skonfiguruj prywatny lub lustrzany rejestr

Środowiska korporacyjne i serwery bez dostępu do internetu często używają prywatnego rejestru NPM (Verdaccio, Nexus, Artifactory):

“`

npm config set registry "https://your-private-registry.example.com/"

“`

Aby uwierzytelnić się w prywatnym rejestrze:

“`

npm login –registry=https://your-private-registry.example.com/

“`

Tylko dla pakietów z zakresem (np. `@mycompany/*`) możesz kierować tylko ten zakres do prywatnego rejestru, pozostawiając publiczny rejestr nienaruszonym:

“`

npm config set @mycompany:registry "https://your-private-registry.example.com/"

“`

Skonfiguruj proxy HTTP

Jeśli Twoja maszyna z Windows działa za korporacyjnym proxy:

“`

npm config set proxy "http://proxy.company.com:8080"

npm config set https-proxy "http://proxy.company.com:8080"

“`

Sprawdź wszystkie bieżące ustawienia

“`

npm config list

npm config list –json

“`

Flaga `–json` generuje konfigurację w formacie czytelnym maszynowo, przydatną do skryptowania i diagnostyki potoków CI/CD.

Przydatna dokumentacja konfiguracji NPM

Krok 6: Utwórz i uruchom aplikację Node.js

Zainicjuj projekt

“`

mkdir my-node-app

cd my-node-app

npm init -y

“`

`npm init -y` generuje `package.json` z wartościami domyślnymi pochodnymi od nazwy katalogu i konfiguracji użytkownika NPM. Plik `package.json` to manifest Twojej aplikacji — definiuje punkt wejścia, skrypty, zależności i metadane.

Zbuduj podstawowy serwer HTTP

Utwórz `app.js` w katalogu projektu:

“`javascript

// app.js

const http = require('http');

const hostname = '127.0.0.1';

const port = 3000;

const server = http.createServer((req, res) => {

res.statusCode = 200;

res.setHeader('Content-Type', 'text/plain');

res.end('Hello, World!n');

});

server.listen(port, hostname, () => {

console.log(`Server running at http://${hostname}:${port}/`);

});

“`

Uruchom go:

“`

node app.js

“`

Przejdź do `http://127.0.0.1:3000/` w przeglądarce. Powinieneś zobaczyć `Hello, World!`.

Uwaga techniczna: Node.js używa jednowątkowej pętli zdarzeń opartej na libuv do operacji I/O. Wywołanie zwrotne `http.createServer` uruchamia się przy każdym przychodzącym żądaniu bez blokowania pętli. Ta architektura sprawia, że Node.js jest bardzo wydajny dla obciążeń związanych z I/O, ale nieodpowiedni dla zadań intensywnie wykorzystujących CPU bez wątków roboczych lub procesów potomnych.

Dodaj framework Express

Express to de facto standardowy framework HTTP dla Node.js, zapewniający routing, obsługę middleware i przejrzystą abstrakcję żądania/odpowiedzi:

“`

npm install express

“`

Instaluje to Express lokalnie (do `node_modules/`) i rejestruje go jako zależność w `package.json`. Zaktualizuj `app.js`:

“`javascript

const express = require('express');

const app = express();

const port = 3000;

app.get('/', (req, res) => {

res.send('Hello from Express!');

});

app.listen(port, () => {

console.log(`Server running at http://localhost:${port}`);

});

“`

“`

node app.js

“`

Odwiedź `http://localhost:3000/`, aby potwierdzić odpowiedź.

Zrozumienie `node_modules` i `.gitignore`

Katalog `node_modules` może zawierać setki megabajtów plików. Nigdy nie dodawaj go do kontroli wersji. Utwórz plik `.gitignore`:

“`

node_modules/

.env

“`

Współpracownicy i potoki wdrożeniowe przywracają zależności, uruchamiając `npm install`, który odczytuje `package.json` i `package-lock.json`, aby odtworzyć dokładne drzewo zależności.

Krok 7: Zarządzanie pakietami — lokalne vs. globalne

Zrozumienie różnicy między lokalną a globalną instalacją pakietów jest jednym z najczęstszych źródeł zamieszania dla nowicjuszy w Node.js.

Kluczowa zasada: Jeśli pakiet dostarcza narzędzie wiersza poleceń, które chcesz mieć dostępne wszędzie (np. `nodemon`, `eslint`, `typescript`), zainstaluj go globalnie. Jeśli jest to biblioteka, którą Twoja aplikacja importuje za pomocą `require()` lub `import`, zainstaluj ją lokalnie.

Uruchamianie aplikacji w produkcji z PM2

Dla każdej aplikacji Node.js wdrożonej na serwerze — czy to na instancji VPS Hosting, czy na Serwerze Dedykowanym — bezpośrednie uruchamianie `node app.js` jest niewystarczające. Proces zakończy się, gdy terminal zostanie zamknięty lub wystąpi nieobsłużony wyjątek.

PM2 to standardowy menedżer procesów dla Node.js w środowisku produkcyjnym:

“`

npm install -g pm2

pm2 start app.js –name "my-app"

pm2 startup

pm2 save

“`

`pm2 startup` generuje polecenie konfigurujące PM2 do automatycznego restartu aplikacji po ponownym uruchomieniu systemu. `pm2 save` utrwala bieżącą listę procesów.

Krok 8: Wzmocnienie bezpieczeństwa i audyt

Przeprowadź audyt zależności

“`

npm audit

“`

NPM porównuje zainstalowane pakiety z bazą danych GitHub Advisory Database. Wszelkie znane podatności są raportowane z poziomami ważności (niski, umiarkowany, wysoki, krytyczny) i ścieżkami naprawy.

“`

npm audit fix

“`

Automatycznie aktualizuje to podatne pakiety do najbliższej nieprzerywającej poprawionej wersji. W przypadku zmian przerywających przejrzyj wyniki i zaktualizuj ręcznie.

Przypinaj wersje zależności

W `package.json` NPM domyślnie używa zakresów wersjonowania semantycznego (`^1.2.3` zezwala na aktualizacje minor i patch). W środowisku produkcyjnym przypinaj dokładne wersje, aby zapobiec niespodziankom w łańcuchu dostaw:

“`

npm config set save-exact true

“`

Lub ręcznie zastąp prefiksy `^` dokładnymi ciągami wersji w `package.json` i zatwierdź plik `package-lock.json`.

Unikaj uruchamiania NPM jako Administrator

Uruchamianie `npm install -g` z podwyższonymi uprawnieniami zapisuje pliki należące do konta Administratora, co może powodować błędy uprawnień przy kolejnych operacjach bez podwyższonych uprawnień. Skonfiguruj globalny prefiks należący do użytkownika (patrz Krok 5), aby całkowicie wyeliminować potrzebę podwyższonych uprawnień.

Wdrażanie aplikacji Node.js na serwerze

Lokalne tworzenie to tylko pierwszy etap. Wdrożenie produkcyjne wprowadza dodatkowe wymagania: zarządzanie procesami, odwrotne proxy, terminację TLS i zarządzanie zmiennymi środowiskowymi.

Typowy stos produkcyjny na linuksowym VPS Hosting łączy Node.js z Nginx jako odwrotnym proxy. Nginx obsługuje terminację TLS (używając certyfikatów od dostawcy takiego jak Certyfikaty SSL) i przekazuje żądania do procesu Node.js nasłuchującego na lokalnym porcie.

Dla zespołów preferujących zarządzane środowisko panelu sterowania, VPS z cPanel zapewnia zarządzanie aplikacjami Node.js przez interfejs cPanel, upraszczając wdrożenie bez konieczności bezpośredniej konfiguracji SSH.

Konfiguracja specyficzna dla środowiska (dane uwierzytelniające bazy danych, klucze API, numery portów) nigdy nie powinna być zakodowana na stałe. Użyj pliku `.env` z pakietem `dotenv`:

“`

npm install dotenv

“`

“`javascript

require('dotenv').config();

const port = process.env.PORT || 3000;

“`

Macierz decyzyjna: kiedy używać której metody instalacji

Kluczowe wnioski techniczne

• Zawsze instaluj wersję LTS dla środowisk produkcyjnych i zespołowych. Używaj wydania Current tylko wtedy, gdy wymagana jest konkretna funkcja V8 lub API Node.js.
• Używaj nvm-for-windows w każdym środowisku, gdzie musi współistnieć wiele wersji Node.js.
• Weryfikuj sumę kontrolną SHA-256 instalatora przed jego uruchomieniem.
• Zmień globalny prefiks NPM na katalog należący do użytkownika, aby uniknąć błędów uprawnień i wyeliminować potrzebę podwyższonych uprawnień.
• Nigdy nie dodawaj `node_modules/` do kontroli wersji. Zawsze zatwierdzaj `package-lock.json`.
• Uruchamiaj `npm audit` po każdym `npm install` w potokach produkcyjnych.
• Używaj PM2 do zarządzania procesami przy każdym wdrożeniu serwerowym — nigdy nie uruchamiaj `node app.js` bezpośrednio w środowisku produkcyjnym.
• Terminuj TLS na warstwie odwrotnego proxy (Nginx, Caddy), a nie wewnątrz procesu Node.js, dla lepszej wydajności i zarządzania certyfikatami.
• Przechowuj sekrety w zmiennych środowiskowych ładowanych przez `dotenv`, nigdy w kodzie źródłowym.

Często zadawane pytania

Jaka jest różnica między Node.js LTS a Current na Windows?

Wersje LTS otrzymują poprawki bezpieczeństwa i stabilności przez 30 miesięcy i mają parzyste numery główne (18, 20, 22). Wersje Current zawierają najnowsze funkcje języka i środowiska uruchomieniowego, ale są wspierane tylko przez sześć miesięcy przed przejściem do LTS lub wycofaniem. W przypadku produkcyjnych wdrożeń na Windows zawsze używaj LTS.

Dlaczego `npm install -g` kończy się błędem uprawnień na Windows?

Domyślny globalny prefiks (`C:Users<username>AppDataRoamingnpm`) czasami nie ma uprawnień zapisu z powodu zasad UAC lub poprzednich instalacji uruchomionych jako Administrator. Rozwiązaniem jest uruchomienie terminala jako Administrator (niezalecane długoterminowo) lub ponowna konfiguracja globalnego prefiksu na katalog należący do Twojego konta użytkownika za pomocą `npm config set prefix "C:yourpath"`.

Czy mogę uruchamiać wiele wersji Node.js jednocześnie na Windows?

Tak, używając nvm-for-windows. Zainstaluj go, a następnie użyj `nvm install <version>` i `nvm use <version>`, aby przełączyć aktywne środowisko uruchomieniowe. Każda wersja utrzymuje własny globalny katalog pakietów, zapobiegając konfliktom między wersjami.

Czym jest `package-lock.json` i czy powinienem go zatwierdzać?

`package-lock.json` to dokładny, deterministyczny zapis całego drzewa zależności rozwiązanego podczas `npm install`. Zapewnia, że każdy programista i każde uruchomienie CI/CD instaluje identyczne wersje pakietów. Zawsze zatwierdzaj go do kontroli wersji i nigdy nie edytuj ręcznie.

Jak automatycznie uruchomić aplikację Node.js przy starcie Windows bez serwera?

Na maszynach deweloperskich użyj PM2 z `pm2 startup` i `pm2 save`. Do integracji z usługami Windows narzędzia takie jak `node-windows` opakowują proces Node.js jako natywną usługę Windows, umożliwiając zarządzanie przez przystawkę MMC Usługi oraz automatyczny restart po awarii lub ponownym uruchomieniu.