Node.js lokalny serwer – instrukcja krok po kroku

Node.js lokalny serwer – instrukcja krok po kroku

Node.js lokalny serwer to proces uruchomiony na Twoim komputerze, charakteryzujący się adresem loopback 127.0.0.1, portem testowym 3000 i obsługą żądań HTTP przez Node.js, npm oraz PowerShell. Microsoft Learn opisuje Test-NetConnection jako narzędzie obejmujące 4 typy diagnostyki: ping, test TCP, śledzenie trasy i diagnostykę wyboru trasy, więc już na starcie masz prosty sposób sprawdzenia, czy serwer odpowiada (źródło: Microsoft Learn, 2026). Jeśli dopiero zaczynasz, przeczytaj też co oznacza lokalny serwer Node.js, bo rozróżnienie między localhost, 127.0.0.1 i 0.0.0.0 zapobiega wielu błędom.

• Node.js – runtime JavaScript, który uruchamia plik server.mjs poza przeglądarką i tworzy proces serwera HTTP.
• npm – menedżer pakietów, który tworzy package.json, instaluje Express i uruchamia npm start lub npm run dev.
• PowerShell – domyślny terminal w Windows, w którym sprawdzisz node -v, npm -v, port 3000 i procesy blokujące serwer.
• localhost 3000 – typowy adres testowy dla aplikacji lokalnej, używany przez Node.js, Express, Vite i wiele paneli developerskich.
• 127.0.0.1 – bezpieczny adres lokalny IPv4, który nie wystawia panelu na inne urządzenia w sieci WiFi.

Przygotowanie środowiska

Przygotowanie środowiska to etap kontroli narzędzi, katalogu roboczego i pliku package.json, charakteryzujący się sprawdzeniem wersji Node.js, dostępnością npm i pracą poza katalogami systemowymi Windows. Z mojej praktyki administracyjnej najczęstsze problemy na tym kroku to brak wpisu w PATH po instalacji Node.js LTS, folder projektu w OneDrive oraz uruchamianie terminala bez ponownego otwarcia po instalatorze.

Jak sprawdzić instalację Node.js w PowerShell?

Otwórz PowerShell lub Windows Terminal i wpisz kolejno: node -v oraz npm -v. Poprawna odpowiedź wygląda podobnie do v22.11.0 dla Node.js i 10.9.0 dla npm, choć konkretne numery zależą od zainstalowanej wersji LTS.

1. node -v – polecenie zwraca wersję runtime Node.js, a błąd „The term node is not recognized” oznacza brak instalacji albo brak wpisu w PATH.
2. npm -v – polecenie sprawdza menedżer pakietów, który zwykle instaluje się razem z Node.js LTS.
3. where.exe node – polecenie w Windows pokazuje ścieżkę do node.exe, na przykład C:\Program Files\nodejs\node.exe.
4. Ponowne otwarcie terminala – po instalacji Node.js zamknij PowerShell i otwórz go ponownie, bo PATH bywa odświeżany dopiero dla nowej sesji.
5. Node.js LTS – do nauki lokalnego serwera wybieraj wersję LTS z nodejs.org, a nie przypadkową paczkę z nieznanego źródła.

Gdzie utworzyć folder projektu?

Utwórz projekt w katalogu użytkownika, na przykład C:\Users\Jan\projekty, a nie w C:\Windows, Program Files ani na pulpicie synchronizowanym przez OneDrive. W terminalu wykonaj: mkdir node-local-server, potem cd node-local-server. Jeśli OneDrive blokuje pliki node_modules, przenieś projekt poza synchronizację, bo instalacja pakietów tworzy setki małych plików.

Po co jest package.json?

W katalogu projektu wpisz npm init -y. Powstanie package.json, czyli plik opisujący projekt, zależności i skrypty uruchomieniowe. Na początku wystarczy domyślna konfiguracja, ale później dodasz do niej npm start, npm run dev i informację, że projekt używa modułów ESM.

Minimalny serwer bez frameworka

Minimalny serwer HTTP w Node.js to aplikacja oparta na wbudowanym module node:http, charakteryzująca się brakiem zewnętrznych zależności, ręczną obsługą odpowiedzi i prostym wywołaniem server.listen. Dokumentacja Node.js HTTP API pokazuje http.createServer jako podstawowy mechanizm tworzenia instancji http.Server (źródło: Node.js HTTP API, 2026).

„Returns a new instance of http.Server.” Node.js HTTP API, http.createServer, 2026

Jak napisać najprostszy plik server.mjs?

Utwórz plik server.mjs. Wklej do niego logikę: import http from 'node:http’; const host = '127.0.0.1′; const port = 3000; const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type’: 'text/plain; charset=utf-8′ }); res.end(’Serwer Node.js działa lokalnie.’); }); server.listen(port, host, () => { console.log(’Adres: http://’ + host + ’:’ + port); });. Ten przykład zwraca status 200, nagłówek Content-Type: text/plain; charset=utf-8 i krótki tekst odpowiedzi.

• server.mjs – rozszerzenie mjs pozwala używać import http from 'node:http’ bez dodatkowej konfiguracji CommonJS.
• node:http – wbudowany moduł Node.js obsługuje żądania HTTP bez instalowania Express, Fastify ani innych frameworków.
• status 200 – odpowiedź 200 informuje przeglądarkę i curl, że żądanie zakończyło się poprawnie.
• Content-Type – nagłówek text/plain; charset=utf-8 zabezpiecza polskie znaki przed błędnym kodowaniem.
• console.log – log w callbacku listen pokazuje dokładny adres, więc nie zgadujesz, czy użyć localhost, 127.0.0.1 czy innego portu.

Jak uruchomić plik mjs?

W tym samym katalogu wpisz node server.mjs. Jeśli terminal pokazuje „Adres: http://127.0.0.1:3000”, proces działa i czeka na żądania. Po zmianie kodu zatrzymaj go przez Ctrl+C i uruchom ponownie, chyba że używasz node –watch albo nodemon.

Jaki adres wpisać w przeglądarce?

Dla hosta 127.0.0.1 wpisz dokładnie http://127.0.0.1:3000. Adres http://localhost:3000 też zwykle działa, ale w niektórych konfiguracjach Windows localhost może najpierw wskazywać IPv6 ::1, podczas gdy serwer słucha tylko na IPv4. Jeśli widzisz ERR_CONNECTION_REFUSED, sprawdź proces i host, a potem przejdź do naprawa problemów z localhost w Node.js.

Wariant z Express i plikami statycznymi

Wariant z Express to lokalny serwer Node.js oparty na frameworku webowym, charakteryzujący się krótszym routingiem, obsługą middleware i prostym serwowaniem katalogu public. Express jest wygodny, gdy budujesz API, formularz HTML, mały panel administracyjny, webhook testowy albo lokalny prototyp aplikacji.

„Fast, unopinionated, minimalist web framework for Node.js.” Express documentation, 2026

Jak zainstalować Express przez npm?

W katalogu projektu wpisz npm install express. npm dopisze paczkę do dependencies w package.json i utworzy katalog node_modules. Jeśli instalacja zatrzyma się na błędach dostępu, zamknij edytor, sprawdź antywirusa i upewnij się, że projekt nie leży w folderze synchronizowanym przez OneDrive.

1. npm install express – polecenie pobiera Express z rejestru npm i zapisuje go jako zależność projektu.
2. node_modules – katalog zawiera pliki pakietów i nie powinien być ręcznie edytowany ani przenoszony między komputerami.
3. package-lock.json – plik blokady stabilizuje wersje zależności, żeby instalacja była powtarzalna na innym komputerze.
4. dependencies – sekcja w package.json informuje, że Express jest wymagany do działania aplikacji.
5. npm audit – komunikaty audytu czytaj ostrożnie, bo w projekcie lokalnym ryzyko jest inne niż w publicznej aplikacji produkcyjnej.

Jak wygląda endpoint GET /?

W pliku server.mjs możesz użyć: import express from 'express’; const app = express(); const port = Number(process.env.PORT ?? 3000); app.get(’/’, (req, res) => { res.type(’text/plain; charset=utf-8′).send(’Express localhost działa.’); }); app.listen(port, '127.0.0.1′, () => console.log(’http://127.0.0.1:’ + port));. Endpoint GET / odpowiada na stronę główną, a Express sam upraszcza obsługę nagłówków i wysyłanie treści.

Jak serwować index.html z folderu public?

Utwórz folder public i plik public/index.html. Następnie dodaj app.use(express.static(’public’)). Wtedy http://127.0.0.1:3000/index.html zwróci plik statyczny, a Express nada się do testowania prostego frontendu, dokumentacji HTML albo panelu narzędziowego bez konfiguracji Nginx.

Jak dodać npm start i tryb dev?

Do package.json dodaj skrypty: start jako node server.mjs oraz dev jako node –watch server.mjs. Możesz też użyć npm pkg set scripts.start=”node server.mjs” scripts.dev=”node –watch server.mjs”. Szczegółowe różnice między start, dev i build opisuje temat podstawy npm scripts.

Wariant	Kiedy użyć	Komenda	Główna zaleta
node:http	Najprostszy test HTTP bez zależności.	node server.mjs	Zero instalacji pakietów i pełna kontrola odpowiedzi.
Express	API, routing, formularze i pliki statyczne.	npm install express, potem npm start	Krótszy kod i gotowy model middleware.
node –watch	Prosty tryb dev w nowych wersjach Node.js.	node –watch server.mjs	Automatyczny restart po zmianie pliku.
nodemon	Starsze projekty albo bardziej rozbudowane reguły obserwowania.	npm install –save-dev nodemon	Elastyczna konfiguracja restartów i ignorowanych katalogów.

Jak wybrać port i adres nasłuchiwania?

Port i adres nasłuchiwania to ustawienia sieciowe procesu Node.js, charakteryzujące się numerem TCP, interfejsem hosta i zakresem dostępności aplikacji. W praktyce 127.0.0.1:3000 jest bezpiecznym startem, a 0.0.0.0 traktuj jako tryb testu w sieci LAN, nie jako domyślne ustawienie.

Jaki port wybrać na start?

Dla pierwszego projektu wybierz port 3000. Jeśli port jest zajęty przez inny proces, użyj 3001, 5173 albo 8080. Port 5173 często zajmuje Vite, 4200 Angular CLI, 5000 różne narzędzia developerskie, a 80 i 443 wymagają ostrożności, bo mogą kolidować z IIS, Dockerem albo serwerami systemowymi.

• 3000 – popularny port dla Express localhost i prostych tutoriali Node.js.
• 3001 – dobry zapasowy port, gdy pierwszy serwer nadal działa w drugim terminalu.
• 5173 – domyślnie spotykany przy Vite, więc nie zakładaj, że jest wolny.
• 8080 – klasyczny port HTTP alternatywny, wygodny dla paneli testowych i proxy.
• 80 – port produkcyjny HTTP, którego nie używaj do nauki bez potrzeby administracyjnej.
• 443 – port HTTPS, który wymaga certyfikatów i nie jest potrzebny do podstawowego lokalnego testu.

Czym różni się 127.0.0.1 od 0.0.0.0?

127.0.0.1 oznacza lokalny interfejs loopback i jest widoczny tylko z tego komputera. 0.0.0.0 oznacza nasłuchiwanie na wszystkich interfejsach, więc aplikacja może być dostępna z telefonu, tabletu albo innego laptopa w tej samej sieci WiFi. Nie używaj 0.0.0.0, jeśli panel pokazuje tokeny API, dane testowe, ciasteczka sesji albo formularz administracyjny bez logowania.

Jak ustawić port przez zmienną środowiskową?

W kodzie użyj Number(process.env.PORT ?? 3000), a w PowerShell ustaw port poleceniem $env:PORT=3001, potem npm start. Zmienna środowiskowa pozwala uruchomić ten sam kod na porcie 3000 lokalnie, 3001 w drugim oknie i innym porcie w kontenerze Docker bez edycji pliku server.mjs.

Test, zatrzymanie i podstawowe zabezpieczenia

Test lokalnego serwera to kontrola odpowiedzi HTTP, procesu Node.js i portu TCP, charakteryzująca się sprawdzeniem przeglądarki, curl.exe, Test-NetConnection oraz logów w terminalu. W ostatnim roku najczęściej widziałem trzy objawy: EADDRINUSE przez drugi proces, brak restartu po zmianie kodu i pomyłkę między localhost a 127.0.0.1.

„The Test-NetConnection cmdlet displays diagnostic information for a connection.” Microsoft Learn, Test-NetConnection, 2026

Jak sprawdzić, czy serwer działa?

Najpierw otwórz http://127.0.0.1:3000 w przeglądarce. Potem wykonaj curl.exe http://127.0.0.1:3000 i Test-NetConnection 127.0.0.1 -Port 3000. Microsoft Learn wskazuje, że parametr -Port testuje łączność TCP z podanym portem zdalnego komputera, więc dla localhost otrzymasz jasne TcpTestSucceeded: True albo False (źródło: Microsoft Learn, 2026).

1. Przeglądarka – szybki test pokazuje treść odpowiedzi, ale może ukryć problem cache przy plikach statycznych.
2. curl.exe – polecenie zwraca surową odpowiedź HTTP i omija część zachowań przeglądarki.
3. Test-NetConnection – cmdlet PowerShell sprawdza, czy port TCP 3000 przyjmuje połączenie.
4. Log terminala – brak błędów po server.listen oznacza, że proces nadal działa i nasłuchuje.
5. Kod statusu 200 – status potwierdza poprawną odpowiedź aplikacji, a nie tylko otwarty port.

Jak zatrzymać serwer Node.js?

W aktywnym terminalu naciśnij Ctrl+C. PowerShell przerwie proces Node.js i zwolni port. Jeśli zamkniesz terminal krzyżykiem, efekt zwykle będzie taki sam, ale przy pracy z wieloma oknami lepiej używać Ctrl+C, bo widzisz komunikaty i nie zabijasz przypadkowo innego zadania.

Jak rozpoznać zajęty port 3000?

Błąd EADDRINUSE oznacza, że port jest już zajęty. Wpisz netstat -ano | findstr :3000, odczytaj PID, a potem sprawdź tasklist /FI „PID eq 1234”. Dopiero po potwierdzeniu procesu użyj taskkill /PID 1234 /F. Dokładniejszą procedurę znajdziesz w materiale jak sprawdzić zajęty port 3000 w Windows.

Kiedy nie używać 0.0.0.0?

Nie ustawiaj 0.0.0.0, gdy aplikacja wyświetla prywatne klucze, tokeny JWT, dane z formularzy, panel admina, eksport CSV albo lokalne pliki użytkownika. Jeśli musisz sprawdzić stronę na telefonie, użyj zaufanej sieci, tymczasowego portu, wyłącz test po zakończeniu i nie zapisuj prawdziwych haseł w kodzie. Przy 127.0.0.1 zapora Windows zwykle nie musi pytać o dopuszczenie ruchu, bo połączenie nie wychodzi poza komputer.

• Tokeny API – nie powinny pojawiać się w panelu dostępnym z sieci LAN bez logowania.
• Dane testowe – nawet przykładowe rekordy klientów mogą naruszać poufność, jeśli są realne.
• Firewall Windows – monit zapory przy 0.0.0.0 oznacza, że proces chce przyjmować połączenia z sieci.
• Sieć publiczna – hotelowe WiFi i sieć firmowa nie są dobrym miejscem na wystawianie lokalnego panelu.
• Ctrl+C po teście – zatrzymanie procesu zwalnia port i kończy ekspozycję aplikacji.

Najczęściej zadawane pytania

Czy do lokalnego serwera Node.js potrzebuję Express?

Nie, prosty serwer uruchomisz na wbudowanym module node:http. Express przydaje się dopiero wtedy, gdy potrzebujesz routingu, API, plików statycznych, formularzy albo middleware. Do pierwszego testu wystarczy server.mjs i polecenie node server.mjs.

Jaki port wybrać dla lokalnego serwera?

Na start wybierz 3000, 3001, 5173 albo 8080, o ile port jest wolny. Jeśli pojawi się EADDRINUSE, nie zmieniaj losowo wielu rzeczy naraz: najpierw sprawdź netstat -ano | findstr :3000. Potem zatrzymaj właściwy proces albo ustaw PORT=3001.

Czy node –watch zastępuje nodemon?

W wielu prostych projektach tak, bo node –watch restartuje proces po zmianach plików. Nodemon nadal jest wygodny, gdy projekt ma starszą wersję Node.js, niestandardowe rozszerzenia albo katalogi, które trzeba ignorować. Dla pierwszego lokalnego serwera zacznij od node –watch server.mjs.

Dlaczego po zmianie kodu strona się nie zmienia?

Proces Node.js mógł nadal działać na starej wersji kodu. Zatrzymaj go przez Ctrl+C i uruchom ponownie albo użyj npm run dev z node –watch. Przy plikach HTML odśwież stronę z pominięciem cache, na przykład Ctrl+F5 w Windows.

Czy lokalny serwer może być dostępny z telefonu?

Tak, ale serwer musi słuchać na 0.0.0.0 albo adresie IP karty sieciowej, a firewall Windows musi dopuścić ruch. Telefon musi być w tej samej sieci WiFi i w przeglądarce wpisujesz adres komputera, na przykład http://192.168.1.20:3000. Używaj tego tylko w zaufanej sieci i wyłącz serwer po teście.

Czym różni się localhost od 127.0.0.1?

localhost to nazwa, która jest tłumaczona przez system na adres lokalny, najczęściej 127.0.0.1 albo ::1. 127.0.0.1 to konkretny adres IPv4 loopback. Jeśli serwer słucha tylko na 127.0.0.1, a przeglądarka próbuje ::1, wpisanie pełnego http://127.0.0.1:3000 może rozwiązać problem.

Czy npm init -y jest obowiązkowe?

Dla czystego node:http nie jest absolutnie obowiązkowe, bo możesz uruchomić node server.mjs bez package.json. W praktyce warto je wykonać, bo package.json porządkuje projekt i pozwala dodać npm start. Przy Express package.json jest już naturalnym miejscem na zależności i skrypty.

Źródła i literatura

1. Node.js Documentation, HTTP API, http.createServer i server.listen, https://nodejs.org/api/http.html, dostęp 2026.
2. Express documentation, Node.js web application framework, https://expressjs.com/, dostęp 2026.
3. Microsoft Learn, Test-NetConnection, NetTCPIP module, https://learn.microsoft.com/en-us/powershell/module/nettcpip/test-netconnection, dostęp 2026.
4. Node.js Documentation, Command-line options i node –watch, https://nodejs.org/api/cli.html, dostęp 2026.
5. npm Documentation, package.json i npm scripts, https://docs.npmjs.com/cli/using-npm/scripts, dostęp 2026.