Wdróż aplikację Node.js na hostingu Rivervo (Next.js i Nuxt).
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 buildW wyniku powstaje .next/ (zbudowana aplikacja). Nie uruchamiaj tu next start — za chwilę uruchomimy ją z pliku startowego.
Nuxt 3:
npm ci
npm run buildW 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.
| Framework | Wgraj | Pomiń |
|---|---|---|
| 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/ipackage.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.mjsNuxta (punkt wejścia tworzony przeznpm 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.
| Pole | Wartość |
|---|---|
| Wersja | 20 lub nowsza |
| Tryb | Produkcyjny |
| Folder | myapp w folderze domowym (tam, gdzie wgrałeś pliki) |
| Adres | twojadomena.pl (albo subdomena, np. app.twojadomena.pl) |
| Plik startowy | server.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.jsonleży w katalogu głównym aplikacji (a nie głębiej). - Dla Next.js: upewnij się, że
nextjest wdependencies, a nie wdevDependencies(instalacja produkcyjna pomija zależności deweloperskie). - Dla Nuxta: sam
nuxtteż 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 appJeś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.jsPamięć 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
npm run buildlokalnie- Wgraj
.next/(Next) lub.output/(Nuxt) +package.json+server.cjs - Strona → Node.js i Python → Aplikacja Node.js → folder, plik startowy
server.cjs, tryb Produkcyjny - 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