Zacznij
Wszystkie wpisyPORADNIK · 7 MIN CZYTANIA

Wdróż aplikację Node.js na hostingu Rivervo (Next.js i Nuxt).

RT
Rivervo Team · Rivervo
·
29 kwietnia 2026
·
Zaktualizowano 13 listopada 2026
Node
ON SHARED HOSTING

Wiele osób zakłada, że aplikacje Node.js muszą działać na VPS. Nie muszą — każdy pakiet hostingu współdzielonego Rivervo ma w menu strony Node.js i Python, co uruchamia proces Phusion Passenger dla twojej aplikacji za tym samym front-endem Apache, który obsługuje twoje pozostałe strony.

Ten poradnik przeprowadza przez cały proces dla dwóch najpopularniejszych frameworków: Next.js i Nuxt 3. Efekt końcowy: twoja aplikacja pod https://twojadomena.pl (lub dowolną subdomeną), działająca w prawdziwym procesie Node.js, odporna na restarty serwera i restartowana jednym kliknięciem.

Jeśli nigdy wcześniej nie wdrażałeś aplikacji Node na hostingu współdzielonym, wszyscy utykają na pliku startowym — Passenger potrzebuje jednego skryptu wejściowego, który uruchamia framework. Poniżej dajemy gotowy plik dla każdego frameworka; skopiuj i wklej, bez zmian.

Czego potrzebujesz na start

  • Pakietu hostingowego Rivervo (dowolnego — aplikacje Node.js działają we wszystkich pakietach)
  • Node.js w wersji 20 lub nowszej lokalnie, aby zbudować aplikację
  • Zbudowanej aplikacji gotowej do wgrania (omówimy to dla każdego frameworka)
  • Dostępu do konta przez menedżer plików lub SFTP (oba działają)

Nie potrzebujesz roota, sudo, systemd ani konfiguracji reverse proxy. Passenger zajmuje się tym wszystkim.

Krok 1 — zbuduj aplikację lokalnie

Wgrywasz zbudowaną aplikację, a nie kod źródłowy. Panel instaluje zależności, ale nie skompiluje Reacta ani nie uruchomi buildu Vite. Zrób to najpierw na swoim komputerze.

Next.js:

npm ci
npm run build

W wyniku powstaje .next/ (zbudowana aplikacja). Nie uruchamiaj tu next start — za chwilę uruchomimy ją z pliku startowego.

Nuxt 3:

npm ci
npm run build

W wyniku powstaje .output/ (uniwersalny katalog buildu Nuxta). Tak samo — na razie niczego nie uruchamiaj.

Krok 2 — wgraj właściwe pliki

Nie musisz wgrywać node_modules/. Panel zainstaluje zależności za ciebie. Nie potrzebujesz też gita ani cache buildu.

Wgraj pliki na konto, najlepiej do ścieżki poza public_html (np. /home/<konto>/myapp/). Dlaczego poza? Bo Passenger automatycznie podpina public_html pod główny adres URL, a umieszczenie tam kodu aplikacji wystawia go publicznie.

FrameworkWgrajPomiń
Next.js.next/, public/, package.json, package-lock.json, next.config.js, twój server.cjs (poniżej)node_modules/, .git/, .env.local
Nuxt 3.output/, package.json, package-lock.json, twój server.cjs (poniżej)node_modules/, .nuxt/, .git/, źródłowe pages/, components/

Pliki możesz przesłać na dwa sposoby:

  • Strona → Pliki → wgraj plik zip → rozpakuj go to najprostsza droga przy niestabilnym połączeniu.
  • SFTP (FileZilla, Cyberduck, rsync) jest szybszy przy kolejnych wdrożeniach. Serwer, port, użytkownik i hasło są w Strona → SSH i SFTP.

Krok 3 — dodaj plik startowy

To plik, który Passenger wykonuje, gdy przychodzi żądanie. Umieść go obok package.json w folderze aplikacji.

Dla Next.js — server.cjs

const next = require('next')
const http = require('http')
 
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
 
app.prepare().then(() => {
  http.createServer((req, res) => handle(req, res)).listen(port, () => {
    console.log(`Next.js server listening on port ${port}`)
  })
})

Co robi:

  • Ładuje Next i wskazuje mu bieżący katalog (w którym są .next/ i package.json).
  • Tworzy obsługę żądań z wewnętrznego routera Next.
  • Uruchamia serwer HTTP na porcie przydzielonym przez Passengera (process.env.PORT).
  • Do testów lokalnych używa portu 3000.

dev wynika automatycznie z NODE_ENV — ustaw w panelu tryb Produkcyjny (zrobimy to w kroku 4), a Next uruchomi się w trybie produkcyjnym.

Dla Nuxt 3 — server.cjs

import('./.output/server/index.mjs').then(({ createApp }) => {
  createApp().then(({ app }) => {
    const port = process.env.PORT || 3000
    app.listen(port, () => {
      console.log(`Nuxt server listening on port ${port}`)
    })
  })
})

Co robi:

  • Dynamicznie importuje .output/server/index.mjs Nuxta (punkt wejścia tworzony przez npm run build).
  • Używa createApp(), aby utworzyć instancję serwera H3.
  • Nasłuchuje na porcie przydzielonym przez Passengera.

Dynamiczny import() jest celowy — modułów .mjs nie można wczytać przez require(), ale plik .cjs może je zaimportować dynamicznie. To najczystszy wzorzec działający w launcherze Passengera.

Krok 4 — utwórz aplikację w panelu

Otwórz swój projekt → Strona → Node.js i Python → Aplikacja Node.js.

PoleWartość
Wersja20 lub nowsza
TrybProdukcyjny
Foldermyapp w folderze domowym (tam, gdzie wgrałeś pliki)
Adrestwojadomena.pl (albo subdomena, np. app.twojadomena.pl)
Plik startowyserver.cjs

Kliknij Utwórz. Środowisko Node.js powstaje w ~/nodevenv/myapp/20/.

Zainstaluj zależności

Gdy aplikacja zostanie utworzona, kliknij przy niej Zainstaluj zależności (npm install) i obserwuj wynik. Jeśli się nie powiedzie:

  • Sprawdź, czy package.json leży w katalogu głównym aplikacji (a nie głębiej).
  • Dla Next.js: upewnij się, że next jest w dependencies, a nie w devDependencies (instalacja produkcyjna pomija zależności deweloperskie).
  • Dla Nuxta: sam nuxt też powinien być zwykłą zależnością.

Dodaj zmienne środowiskowe

Ustawienia aplikacji → Zmienne środowiskowe → Dodaj zmienną. Tryb Produkcyjny sam ustawia NODE_ENV=production.

Jeśli aplikacja Next.js odczytuje wartości w czasie działania (adresy baz danych, klucze API), dodaj je tutaj. Nie wgrywaj pliku .env z sekretami — właściwym miejscem są zmienne środowiskowe aplikacji.

Zapisanie ustawień restartuje aplikację, więc nowe zmienne działają od razu.

Krok 5 — sprawdź

Otwórz adres aplikacji. Powinieneś zobaczyć swoją aplikację.

Jeśli widzisz stronę błędu Passengera, rozwiń ją i spójrz na dół — prawie zawsze jest tam czytelny stack trace. Dwa najczęstsze błędy:

Error: Cannot find module 'next' — npm install się nie wykonał albo wykonał się w złym folderze. Kliknij ponownie Zainstaluj zależności (npm install).

Error: ENOENT: no such file or directory, open '.next/...' — wgrałeś kod źródłowy, ale nie zbudowany katalog .next/. Zbuduj aplikację lokalnie i wgraj ją ponownie.

Jak wdrażać aktualizacje

Powtórz kroki 1 i 2, a potem kliknij przy aplikacji Uruchom ponownie. Konkretnie:

1. Build locally    npm run build
2. Upload          .next/ or .output/, plus any changed source/config
3. Panel          Restart the app

Jeśli zmieniasz package.json, przed ponownym uruchomieniem kliknij Zainstaluj zależności (npm install). Wolisz wiersz poleceń? Strona → Terminal: karta aplikacji pokazuje polecenie, które przenosi do jej środowiska.

Typowe pułapki

WebSockety: Passenger obsługuje HTTP/1.1 i HTTP/2. Upgrade do WebSocket działa dla wbudowanych tras Next.js i Nuxta. Jeśli używasz osobnego serwera WebSocket (ws, socket.io), korzysta on z tego samego portu i uruchamia się przez ten sam server.cjs — bez dodatkowej konfiguracji.

Wgrywanie plików / limity body-parser w next.config.js: domyślny limit rozmiaru żądania w Passengerze to 10 MB. Jeśli wgrywasz duże pliki, podnieś passenger_max_request_size przez .htaccess w public_html:

PassengerMaxRequestSize 52428800

(50 MB w bajtach).

Zadania cron: jeśli aplikacja potrzebuje zadań w tle (wysyłka newslettera, zaplanowane eksporty), nie uruchamiaj ich w procesie WWW. Użyj Strona → Zadania cron, aby wywołać skrypt Node bezpośrednio:

/home/<konto>/nodevenv/myapp/20/bin/node /home/<konto>/myapp/scripts/send-newsletter.js

Pamięć procesu: Passenger restartuje aplikację, jeśli przekroczy limit RAM dla konta (zależy od pakietu). Typowa aplikacja Next.js / Nuxt w spoczynku zużywa poniżej 100 MB. Jeśli dochodzisz do limitów, sprawdź process.memoryUsage() i poszukaj wycieków, zanim uznasz, że potrzebujesz większego pakietu.

Własne domeny i HTTPS: adres ustawiony dla aplikacji jest tym, pod który Passenger się podpina. SSL działa automatycznie — bez dodatkowej konfiguracji. Inną domenę lub subdomenę najpierw dodaj w Strona → Domeny, a potem wybierz ją jako adres aplikacji.

Wersja Node: lista Wersja pokazuje wszystkie zainstalowane wersje; zmienisz ją w Ustawieniach aplikacji.

Kiedy nie używać hostingu współdzielonego dla Node

Mówiąc wprost — Node.js na hostingu współdzielonym świetnie sprawdza się przy portfolio, blogach, stronach marketingowych, niewielkich front-endach SaaS i narzędziach wewnętrznych. Gorzej radzi sobie z:

  • API o dużej przepustowości (stale >50 żądań/s) — odczujesz limit CPU na konto
  • Aplikacjami opartymi na WebSocketach z tysiącami równoczesnych połączeń
  • Aplikacjami, które uruchamiają procesy robocze (obsługa kolejek, scrapery) — limit procesów na konto w Passengerze utrudnia to
  • Wszystkim, co wymaga systemd, Dockera lub dostępu root

W takich przypadkach właściwym wyborem jest nasz VPS — pełny root, własne jądro, uruchomisz na nim, co chcesz. Ale dla większości aplikacji Next.js i Nuxt bez ogromnego ruchu ten poradnik wystarczy.

W skrócie

  1. npm run build lokalnie
  2. Wgraj .next/ (Next) lub .output/ (Nuxt) + package.json + server.cjs
  3. Strona → Node.js i Python → Aplikacja Node.js → folder, plik startowy server.cjs, tryb Produkcyjny
  4. Zainstaluj zależności (npm install), potem Uruchom ponownie

Jeśli coś nie działa, otwórz zgłoszenie — wklej stronę błędu Passengera, a wskażemy konkretną linię.

— Zespół Rivervo