Dlaczego Next.js nie działa na zwykłym hostingu z cPanel i co wybrać zamiast niego?

Ktoś kończy stronę w Next.js, kupuje tani hosting www, loguje się do cPanelu, wrzuca projekt przez FTP do public_html i czeka, aż strona ruszy. Zamiast tego widzi biały ekran, 404, listę plików albo komunikat Apache. Czasem działa tylko strona główna, a każda podstrona po odświeżeniu się sypie.

To nie jest awaria Next.js. To zderzenie dwóch różnych modeli działania.

Klasyczny hosting z cPanel najczęściej serwuje pliki: HTML, CSS, JavaScript, obrazy, PHP i WordPressa. Pełna aplikacja Next.js może natomiast wymagać działającego procesu Node.js, routingu po stronie serwera, zmiennych środowiskowych, cache, SSR, ISR, route handlers, API, middleware/proxy i reverse proxy. FTP nie uruchamia aplikacji. FTP tylko kopiuje pliki.

Najpierw trzeba więc odpowiedzieć na jedno pytanie: czy ten projekt da się zamienić w statyczny eksport, czy musi działać jako aplikacja Node.js?

Next.js to nie zawsze zwykła strona do wrzucenia przez FTP

Zwykła strona HTML działa banalnie. Serwer dostaje żądanie o /kontakt.html, znajduje plik na dysku i odsyła go do przeglądarki. Niczego nie buduje, nie renderuje, nie trzyma procesu w pamięci. Dlatego klasyczny hosting radzi sobie z takim projektem dobrze: wrzucasz pliki, ustawiasz domenę, koniec.

Z Reactem bywa podobnie, jeżeli projekt jest typową aplikacją SPA. Po buildzie dostajesz statyczne pliki: HTML, JS, CSS i assety. Serwer nie musi rozumieć Reacta. On tylko podaje paczkę JavaScriptu, a aplikacja działa głównie w przeglądarce.

Next.js jest inny. To framework Reacta do budowania pełnych aplikacji webowych, a nie wyłącznie generator plików frontendowych. Może działać jako statyczna strona, ale może też renderować HTML na serwerze, obsługiwać requesty, trzymać cache, korzystać z funkcji serwerowych i działać jako aplikacja uruchamiana przez Node.js. Aktualne wymagania Next.js podają Node.js minimum 20.9, więc już sama wersja runtime’u potrafi odsiać część hostingów współdzielonych.

W praktyce masz kilka różnych scenariuszy:

• zwykły HTML — gotowe pliki leżą na serwerze;
• React SPA — serwer podaje statyczny build, logika działa w przeglądarce;
• Next.js jako static export — Next generuje HTML/CSS/JS podczas builda;
• SSG — strony powstają podczas budowania projektu;
• SSR — HTML powstaje przy konkretnym żądaniu użytkownika;
• ISR — statyczna strona może być odświeżana po wdrożeniu;
• pełna aplikacja Next.js — działa proces Node.js, zwykle za reverse proxy.

Największa pułapka jest przy folderze .next. Wielu początkujących traktuje go jak odpowiednik dist z klasycznego frontendu. To błąd. Folder .next nie jest paczką do skopiowania do public_html. To wynik builda używany przez środowisko Next.js.

Jeżeli projekt faktycznie da się wyeksportować statycznie, w konfiguracji ustawiasz output: 'export', uruchamiasz build i dostajesz katalog out. Dopiero zawartość katalogu out nadaje się do wrzucenia na zwykły hosting plików, także przez FTP. Next.js generuje wtedy statyczny eksport do folderu out, a taki wynik można hostować na serwerze obsługującym statyczne zasoby HTML/CSS/JS.

Przykład konfiguracji:

// next.config.js
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true
  }
}

module.exports = nextConfig

Ta konfiguracja nie zamienia każdej aplikacji Next.js w prostą stronę HTML. Static export odpada, gdy projekt używa funkcji wymagających serwera albo logiki niemożliwej do policzenia podczas builda. Problemem będą między innymi: API Routes, redirects, headers, proxy, ISR, domyślna optymalizacja obrazów, Draft Mode, getServerSideProps oraz getStaticPaths z fallbackiem.

Prosta zasada:

• masz katalog out — możesz myśleć o FTP, cPanelu, Cloudflare Pages albo innym hostingu statycznym;
• masz tylko .next — prawdopodobnie potrzebujesz środowiska uruchamiającego Next.js;
• używasz SSR, ISR, route handlers, cookies, auth, server actions, dynamicznych danych na request — nie traktuj tego jak zwykłej strony HTML.

Najprostszy test przed wyborem hostingu zrób na swoim komputerze. Ustaw eksport statyczny, uruchom npm run build i sprawdź wynik. Jeżeli proces przejdzie bez błędów, a w katalogu out masz komplet podstron, cPanel jako hosting plików wystarczy. Jeżeli Next.js zgłosi błędy i zażąda serwera, zapomnij o zwykłym FTP. Wtedy nie poprawiasz .htaccess, nie kopiujesz node_modules i nie próbujesz „dograć brakujących plików”. Zmieniasz sposób wdrożenia.

SSR, Node.js i cPanel — gdzie zaczyna się prawdziwy problem

cPanel sam w sobie nie jest problemem. Problemem jest typowy pakiet hostingu współdzielonego, na którym cPanel zarządza domenami, pocztą, plikami, bazami i PHP. Taki hosting świetnie nadaje się pod WordPressa, prostą stronę HTML albo statyczny frontend. Nie musi jednak pozwalać na stałe uruchomienie aplikacji Node.js.

Produkcyjny Next.js zwykle potrzebuje dwóch etapów:

npm run build
npm run start

next build przygotowuje aplikację produkcyjną, a next start uruchamia produkcyjny serwer Next.js. Te skrypty są standardowym elementem konfiguracji projektu Next.js.

FTP nie wykona żadnej z tych rzeczy. Nie zainstaluje zależności. Nie zbuduje aplikacji. Nie utrzyma procesu. Nie wystawi portu. Nie skonfiguruje reverse proxy. Nie zapisze sensownych logów. Nie zrestartuje aplikacji po błędzie.

Dlatego po wrzuceniu całego projektu do public_html pojawiają się typowe objawy:

• package.json leży na serwerze, ale nikt go nie uruchamia;
• folder .next istnieje, ale Apache albo LiteSpeed nie wiedzą, co z nim zrobić;
• dynamiczne podstrony zwracają 404;
• API routes albo route handlers nie odpowiadają;
• strona główna czasem działa, ale odświeżenie podstrony psuje routing;
• next/image nie optymalizuje obrazów;
• ISR nie odświeża treści;
• upload node_modules przez FTP kończy się limitem plików, błędami binarek albo chaosem w zależnościach.

W swojej praktyce wielokrotnie widziałem deweloperów, którzy kupowali „hosting z Node.js”, bo w ofercie było jedno magiczne słowo: Node. Dopiero później okazywało się, że Node jest stary, SSH niedostępne, proces ubijany po kilku minutach, a support rozumie przez Node.js prostą aplikację Express, nie pełne wdrożenie Next.js z SSR.

cPanel potrafi obsługiwać aplikacje Node.js, ale tylko wtedy, gdy dostawca hostingu włączy odpowiednie funkcje. Application Manager działa przez Phusion Passenger, który pełni rolę process managera, reverse proxy i narzędzia operacyjnego. Ta funkcja może być jednak włączona albo wyłączona przez administratora serwera w WHM.

I tu pojawia się techniczny szczegół, który w realnym wdrożeniu potrafi zablokować cały projekt. Phusion Passenger często oczekuje konkretnego pliku startowego, na przykład app.js albo server.js. Tymczasem standardowy Next.js uruchamia się przez komendę next start, czyli przez binarkę z node_modules/.bin/next, a nie przez prosty plik aplikacji Express. Passenger pozwala wskazać startup file, a przy aplikacjach Node jego przykłady idą właśnie w stronę pliku uruchamianego komendą node app.js.

Da się to czasem obejść custom serverem, wrapperem albo ręczną konfiguracją, ale to nie jest ten sam poziom prostoty co wrzucenie plików przez FTP. Przy hostingu współdzielonym dochodzą jeszcze limity RAM, CPU, dostęp do terminala, wersja Node.js, zmienne środowiskowe i sposób restartowania procesu.

Minimalna lista pytań do dostawcy hostingu wygląda tak:

• jaką wersję Node.js mogę wybrać?
• czy dostępny jest Node.js 20.9 lub nowszy?
• czy mam SSH/Terminal?
• czy mogę uruchomić npm install i npm run build?
• czy aplikacja może działać stale jako proces?
• czy jest Application Manager, Passenger, PM2 albo inny process manager?
• czy mogę ustawić zmienne środowiskowe?
• jaki jest limit RAM i CPU?
• gdzie są logi błędów?
• czy hosting obsłuży reverse proxy?
• czy support oficjalnie wspiera Next.js, czy tylko „Node.js ogólnie”?

cPanel przy instalacji aplikacji Node.js zakłada pracę z terminalem, portem aplikacji, pakietami po stronie serwera i konfiguracją wykonaną przez hostingodawcę. Sam cPanel ostrzega też, że jego support nie pomaga w pisaniu ani debugowaniu aplikacji Node.js, a takie prace powinny wykonywać osoby z doświadczeniem administracyjnym.

Praktyczny wniosek jest prosty: Next.js na cPanelu może działać, ale nie w modelu „wrzucam projekt przez FTP i gotowe”. To wdrożenie aplikacji Node.js na hostingu, który akurat ma panel cPanel. Jeżeli dostawca nie potrafi jasno opisać procesu, wersji Node, limitów i mechanizmu utrzymania procesu, szkoda czasu na testowanie w ciemno.

Kiedy wystarczy eksport statyczny, a kiedy wybrać Vercel, Cloudflare, VPS albo Coolify

Najpierw usuń serwer, jeżeli da się go usunąć. To najlepsza decyzja dla prostych projektów.

Statyczny eksport wystarczy, gdy strona nie potrzebuje logiki po stronie serwera w czasie żądania. Typowe przypadki:

• strona firmowa;
• landing page;
• portfolio;
• dokumentacja;
• blog generowany z Markdowna;
• prosta strona z danymi pobieranymi podczas builda;
• formularz obsługiwany przez zewnętrzną usługę;
• frontend komunikujący się z gotowym API z przeglądarki.

Wtedy ścieżka jest konkretna: ustawiasz output: 'export', uruchamiasz build, bierzesz katalog out i wrzucasz jego zawartość na hosting. Nie .next. Nie cały projekt. Nie node_modules.

Static export odpada, gdy używasz SSR, ISR, API routes, route handlers zależnych od requestu, cookies po stronie serwera, sesji, autoryzacji serwerowej, dynamicznych nagłówków, proxy, middleware, webhooks, połączenia z bazą danych po stronie serwera albo domyślnej optymalizacji obrazów Next.js. Wtedy potrzebujesz środowiska, które potrafi uruchomić aplikację, a nie tylko podać pliki.

Przy self-hostingu Next.js sensownie stawia się go za reverse proxy, na przykład Nginxem. Reverse proxy przejmuje część zadań ochronnych i infrastrukturalnych: obsługę niepoprawnych requestów, limity payloadów, wolne połączenia, rate limiting i inne rzeczy, którymi nie powinien zajmować się sam proces Next.js.

1. Zwykły hosting www / cPanel — tylko dla statycznego eksportu albo świadomego Node.js

cPanel wybieraj wtedy, gdy projekt kończy się katalogiem out. To dobry wariant dla prostej strony, szczególnie gdy hosting już masz, domena jest podpięta, a treść nie wymaga SSR ani ISR.

Nie wybieraj zwykłego hostingu współdzielonego dla pełnej aplikacji Next.js, jeżeli nie masz potwierdzonego Node.js, SSH, zmiennych środowiskowych, process managera, kompatybilnej wersji runtime’u i jasnych limitów pamięci. To droga, która często kończy się półdziałającym wdrożeniem: strona główna działa, formularz nie, dynamiczne trasy zwracają 404, a support odpisuje, że „takie aplikacje nie są wspierane”.

2. Vercel — gdy chcesz uruchomić Next.js bez administracji serwerem

Vercel jest najprostszym wyborem dla wielu projektów Next.js. Podłączasz repozytorium, ustawiasz zmienne środowiskowe, robisz push i masz deploy. To dobry kierunek dla stron firmowych, SaaS-ów, paneli, projektów z SSR, ISR, preview deploymentami i zespołem, który nie chce utrzymywać VPS-a.

Na dzień 21 czerwca 2026 r. Vercel pokazuje plan Hobby jako darmowy, a plan Pro jako 20 USD miesięcznie + dodatkowe użycie, z kredytem użycia w tej samej kwocie.

Plusy Vercela:

• bardzo szybki deploy z Gita;
• dobre wsparcie dla funkcji Next.js;
• preview deploymenty dla branchy i pull requestów;
• wygodne zmienne środowiskowe;
• mniej pracy administracyjnej;
• łatwiejsza współpraca zespołu.

Minusy:

• przy większym ruchu trzeba pilnować rozliczania użycia;
• nietypowe procesy serwerowe mogą wymagać innego podejścia;
• część architektury wiąże projekt z platformą;
• długie zadania, własne daemony i niestandardowa infrastruktura nie zawsze pasują do tego modelu.

Moja decyzja graniczna jest prosta: jeżeli projekt ma być typową aplikacją Next.js i nie masz konkretnego powodu, żeby utrzymywać własny serwer, zaczynaj od Vercela. Godziny walki z przypadkowym hostingiem współdzielonym kosztują więcej niż pierwszy miesiąc planu Pro.

3. Cloudflare — dla statycznych stron i projektów pasujących do Workers

Cloudflare ma dwie różne ścieżki.

Pierwsza to Cloudflare Pages dla statycznych eksportów. Przy takim wdrożeniu wybierasz preset Next.js Static HTML Export, build command npx next build, a katalog wyjściowy to out.

Druga ścieżka to Cloudflare Workers z adapterem OpenNext. Tu wchodzą pełniejsze projekty Next.js: App Router, Pages Router, route handlers, SSG, SSR, ISR, Server Actions, streaming i middleware. Trzeba jednak pamiętać, że aplikacja działa w runtime workerd, a nie w klasycznym Node.js; Cloudflare zaleca testowanie przez preview, bo to środowisko jest bliższe produkcji niż zwykły dev server Next.js.

Cenowo Workers ma plan darmowy, a plan Paid ma minimalną opłatę 5 USD miesięcznie za konto. Ten płatny próg obejmuje między innymi Workers, Pages Functions, KV, Hyperdrive i Durable Objects, z dalszym rozliczaniem użycia ponad limity.

Cloudflare wybieraj, gdy:

• strona statyczna ma działać szybko globalnie;
• i tak używasz Cloudflare dla DNS, CDN i zabezpieczeń;
• projekt pasuje do Workers;
• akceptujesz różnice między Workers a klasycznym Node.js;
• umiesz sprawdzić kompatybilność paczek przed migracją.

Nie wybieraj Cloudflare w ciemno, jeżeli projekt zależy od paczek mocno przywiązanych do Node.js, systemu plików albo specyficznych API serwerowych. Najpierw uruchom preview w runtime Cloudflare i dopiero po tym podejmuj decyzję.

4. VPS — gdy chcesz pełną kontrolę i bierzesz odpowiedzialność za serwer

VPS ma sens, gdy potrzebujesz własnego środowiska: Docker, Nginx, procesy Node.js, WebSockety, cron, kolejki, baza danych, własne logi, przewidywalny koszt i pełna kontrola nad konfiguracją.

To nie jest jednak „tani Vercel”. VPS oznacza odpowiedzialność za:

• aktualizacje systemu;
• firewall;
• SSL;
• reverse proxy;
• deploy;
• monitoring;
• backupy;
• logi;
• limity pamięci;
• restart po awarii;
• bezpieczeństwo SSH.

Dla konkretu: DigitalOcean Basic Droplets pokazują warianty od 4 USD miesięcznie za 512 MiB RAM i 1 vCPU, 6 USD miesięcznie za 1 GiB RAM i 1 vCPU oraz 12 USD miesięcznie za 2 GiB RAM i 1 vCPU. DigitalOcean opisuje Droplets jako IaaS, czyli dostajesz wirtualny sprzęt, ale za system operacyjny, aplikacje i dane odpowiadasz sam.

Osobiście przy Next.js nie schodzę produkcyjnie poniżej 1–2 GiB RAM, chyba że to bardzo mała statyczna aplikacja albo środowisko testowe. Mniejsze instancje potrafią wyłożyć się już na npm run build, szczególnie gdy projekt ma dużo zależności, generuje wiele podstron albo używa ciężkich paczek.

VPS wybieraj wtedy, gdy kontrola jest ważniejsza niż wygoda. Jeżeli nie chcesz dotykać Nginxa, certyfikatów, logów, aktualizacji i restartów, nie zaczynaj od czystego VPS-a.

5. Coolify — gdy chcesz własny serwer, ale bez ręcznego składania całego deployu

Coolify rozwiązuje problem, który pojawia się po pierwszym zderzeniu Next.js z cPanelem: aplikacja potrzebuje procesu, reverse proxy, zmiennych, logów, deployu, SSL i restartu. Coolify robi z tego panel zamiast ręcznej układanki.

To open source’owy PaaS do self-hostingu aplikacji, baz danych i usług. Obsługuje wdrożenia z Gita, serwery przez SSH, Docker-kompatybilne usługi, automatyczne certyfikaty Let’s Encrypt, backupy i monitoring.

Ceny są proste: self-hosted Coolify jest darmowy, poza kosztem Twojego serwera. Coolify Cloud kosztuje 5 USD miesięcznie jako baza z możliwością podłączenia 2 serwerów, a każdy dodatkowy serwer to 3 USD miesięcznie. Aplikacje nadal działają na Twoich serwerach, nie na infrastrukturze Coolify.

Coolify wybieraj, gdy:

• masz VPS albo planujesz go kupić;
• hostujesz kilka projektów;
• chcesz deploy z Gita;
• używasz Dockera albo Docker Compose;
• chcesz trzymać aplikacje, bazy i usługi w jednym panelu;
• koszt platform typu Vercel robi się mniej przewidywalny;
• akceptujesz odpowiedzialność za serwer, ale nie chcesz robić wszystkiego ręcznie.

Najrozsądniejsza kolejność decyzji wygląda tak:

1. Jeżeli projekt da się zbudować jako static export, użyj katalogu out i hostuj go na cPanelu, Cloudflare Pages albo innym hostingu statycznym.
2. Jeżeli projekt używa typowych funkcji Next.js po stronie serwera, wybierz Vercel, chyba że masz konkretny powód, żeby tego nie robić.
3. Jeżeli siedzisz w ekosystemie Cloudflare i projekt pasuje do Workers, rozważ Cloudflare Workers + OpenNext.
4. Jeżeli chcesz kontrolę, Docker, kilka aplikacji i przewidywalny serwer, wybierz VPS + Coolify.
5. Jeżeli masz tylko tani hosting współdzielony, nie próbuj robić z niego serwera aplikacyjnego. Najpierw sprawdź, czy projekt można wyeksportować statycznie.

Pierwszy błąd do usunięcia jest zawsze ten sam: nie zaczynaj od FTP. Zacznij od odpowiedzi, czy aplikacja potrzebuje runtime’u Node.js. Dopiero potem wybieraj hosting.

FAQ: najczęstsze pytania o hosting Next.js

Czy Next.js działa na cPanelu?
Tak, ale w dwóch scenariuszach. Jako statyczny eksport działa jak zwykłe pliki HTML/CSS/JS i można go hostować na klasycznym serwerze. Jako pełna aplikacja wymaga Node.js, procesu serwerowego, kompatybilnej wersji runtime’u, zmiennych środowiskowych i mechanizmu typu Application Manager/Passenger. Sam napis „cPanel” nie gwarantuje obsługi Next.js.

Czy Next.js można wrzucić przez FTP?
Tak, ale tylko zawartość katalogu out po wykonaniu statycznego eksportu. Wrzucenie całego projektu, folderu .next, package.json albo node_modules do public_html nie jest poprawnym wdrożeniem pełnej aplikacji Next.js.

Dlaczego folder .next nie działa po wrzuceniu na hosting?
Bo .next jest wynikiem builda używanym przez środowisko Next.js, a nie gotową paczką plików dla Apache. Jeżeli nie masz katalogu out, zwykły hosting plików najczęściej nie wystarczy.

Czy Next.js wymaga VPS-a?
Nie zawsze. Prosta strona może działać jako statyczny eksport bez VPS-a. Pełna aplikacja może działać na Vercelu albo Cloudflare Workers. VPS wybieraj wtedy, gdy chcesz własny proces Node.js, Dockera, kilka aplikacji na jednej maszynie, własne logi, cron, WebSockety albo niestandardową konfigurację.

Czy hosting współdzielony z Node.js wystarczy pod Next.js?
Czasem tak, ale tylko po sprawdzeniu konkretów: wersji Node.js, dostępu do SSH, możliwości wykonania builda, process managera, limitu RAM/CPU, zmiennych środowiskowych i wsparcia dla długodziałającej aplikacji. Przy aktualnym Next.js szczególnie ważne jest Node.js 20.9 lub nowszy.

Co wybrać zamiast zwykłego cPanelu?
Dla strony statycznej: cPanel jako hosting plików albo Cloudflare Pages. Dla typowej aplikacji Next.js z SSR, ISR i funkcjami serwerowymi: Vercel. Dla projektu pasującego do edge i Workers: Cloudflare Workers z OpenNext. Dla pełnej kontroli i kilku aplikacji: VPS z Coolify.

Od czego zacząć przed zakupem hostingu?
Od testu lokalnego. Ustaw output: 'export', uruchom npm run build i sprawdź, czy powstał katalog out z kompletem podstron. Jeżeli tak, zwykły hosting plików wystarczy. Jeżeli build wymaga serwera albo wywala błędy przez funkcje dynamiczne, wybierz środowisko dla aplikacji Node.js, a nie FTP.