Пуснете Node.js приложението си на хостинга на Rivervo (Next.js и Nuxt).
Мнозина смятат, че Node.js приложенията трябва да живеят на VPS. Не е така — всеки план за споделен хостинг в Rivervo има Node.js и Python в менюто на уебсайта, което стартира процес на Phusion Passenger за вашето приложение зад същия Apache, който обслужва другите ви сайтове.
Това ръководство минава през целия процес за двете най-разпространени рамки: Next.js и Nuxt 3. Крайният резултат: приложението ви на https://firmata.bg (или на поддомейн), работещо в истински Node.js процес, оцеляващо при рестарти и рестартирано с едно щракване.
Ако никога не сте пускали Node приложение на споделен хостинг, мястото, където всички се затрудняват, е стартовият файл — Passenger иска един входен скрипт, който стартира рамката ви. По-долу даваме по един за всяка рамка; копирайте и поставете, без промени.
Какво ви трябва, преди да започнете
- План за хостинг в Rivervo (всеки — Node.js приложенията работят на всички планове)
- Node.js v20 или по-нова локално, за да изградите приложението
- Изграденият резултат, готов за качване (ще го разгледаме за всяка рамка)
- Достъп до акаунта през файловия мениджър или SFTP (и двата работят)
Не ви трябват root, sudo, systemd или настройка на reverse proxy. Passenger се грижи за всичко това.
Стъпка 1 — изградете приложението локално
Ще качите изградено приложение, а не изходния код. Панелът инсталира зависимостите, но няма да компилира React или да пусне Vite build. Направете това първо на своя компютър.
Next.js:
npm ci
npm run buildТова създава .next/ (изградения резултат). Не пускайте next start тук — след малко ще го стартираме от стартовия файл.
Nuxt 3:
npm ci
npm run buildТова създава .output/ (универсалната build директория на Nuxt). Същото — засега не пускайте нищо.
Стъпка 2 — качете правилните файлове
Не е нужно да качвате node_modules/. Панелът инсталира зависимостите вместо вас. Не ви трябват и git, нито build кешове.
Качете в акаунта си, за предпочитане в път извън public_html (напр. /home/<акаунт>/myapp/). Защо извън? Защото Passenger автоматично монтира public_html в корена на адреса и ако сложите кода на приложението там, той става видим.
| Рамка | Качете | Пропуснете |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, вашия server.cjs (по-долу) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, вашия server.cjs (по-долу) | node_modules/, .nuxt/, .git/, изходните pages/, components/ |
Два начина да прехвърлите файловете:
- Уебсайт → Файлове → качете zip → разархивирайте го е най-лесно при нестабилна връзка.
- SFTP (FileZilla, Cyberduck,
rsync) е по-бързо при повторни внедрявания. Сървърът, портът, потребителят и паролата са в Уебсайт → SSH и SFTP.
Стъпка 3 — добавете стартовия файл
Това е файлът, който Passenger изпълнява, когато дойде заявка. Сложете го до package.json в папката на приложението.
За 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}`)
})
})Какво прави:
- Зарежда Next и го насочва към текущата директория (където са
.next/иpackage.json). - Създава обработчик на заявки от вътрешния рутер на Next.
- Стартира HTTP сървър на порта, който Passenger задава (
process.env.PORT). - За локални тестове използва
3000.
dev се определя автоматично от NODE_ENV — задайте режим Production в панела (ще го направим в Стъпка 4) и Next работи в продукционен режим.
За 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}`)
})
})
})Какво прави:
- Динамично импортира
.output/server/index.mjsна Nuxt (входната точка, създадена отnpm run build). - Използва
createApp(), за да създаде инстанция на H3 сървъра. - Слуша на порта, зададен от Passenger.
Динамичният import() е нарочен — .mjs модулите не могат да се зареждат с require(), но .cjs файл може да ги импортира динамично. Това е най-чистият вариант, който работи в стартера на Passenger.
Стъпка 4 — създайте приложението в панела
Отворете проекта си → Уебсайт → Node.js и Python → Node.js приложение.
| Поле | Стойност |
|---|---|
| Версия | 20 или по-нова |
| Режим | Production |
| Папка | myapp в домашната ви папка (където качихте файловете) |
| Адрес | firmata.bg (или поддомейн като app.firmata.bg) |
| Стартов файл | server.cjs |
Натиснете Създаване. Под ~/nodevenv/myapp/20/ се създава Node.js среда.
Инсталирайте зависимостите
След като приложението е създадено, натиснете Инсталиране на зависимости (npm install) и следете изхода. Ако не успее:
- Проверете дали
package.jsonе в корена на приложението (а не вложен). - За Next.js: уверете се, че
nextе вdependencies, а не вdevDependencies(продукционната инсталация пропуска dev зависимостите). - За Nuxt: самият
nuxtсъщо трябва да е обикновена зависимост.
Добавете променливи на средата
Настройки на приложението → Променливи на средата → Добавяне на променлива. Режимът Production вече задава NODE_ENV=production.
За Next.js приложения, които четат стойности по време на работа (адреси на бази данни, API ключове), добавете ги тук. Не качвайте .env файл с тайни — променливите на средата на приложението са правилното място.
Запазването на настройките рестартира приложението, така че новите променливи влизат в сила веднага.
Стъпка 5 — проверете
Отворете адреса на приложението. Трябва да видите приложението си.
Ако видите страница с грешка на Passenger, разгънете я и погледнете най-долу — почти винаги има ясен stack trace. Двете най-чести грешки:
Error: Cannot find module 'next' — npm install не е изпълнен или е изпълнен в грешната папка. Натиснете отново Инсталиране на зависимости (npm install).
Error: ENOENT: no such file or directory, open '.next/...' — качили сте изходния код, но не и изградената директория .next/. Изградете локално и качете отново.
Как да внедрявате обновления
Повторете стъпки 1 и 2 и натиснете Рестарт на приложението. Конкретно:
1. Локален build npm run build
2. Качване .next/ или .output/, плюс променен код/настройки
3. Панел Рестартирайте приложениетоАко промените package.json, натиснете Инсталиране на зависимости (npm install) преди рестарта. Предпочитате командния ред? Уебсайт → Терминал: картата на приложението показва командата за влизане в средата му.
Чести капани
WebSockets: Passenger обработва HTTP/1.1 и HTTP/2. WebSocket upgrade работи за вградените маршрути на Next.js и Nuxt. Ако използвате отделен WebSocket сървър (ws, socket.io), той споделя същия порт и се стартира от същия server.cjs — без допълнителни настройки.
Качване на файлове / лимити на body-parser в next.config.js: стандартният лимит на Passenger за тялото на заявката е 10 MB. Ако качвате големи файлове, вдигнете passenger_max_request_size през .htaccess в public_html:
PassengerMaxRequestSize 52428800(50 MB в байтове.)
Cron задачи: ако приложението ви има нужда от фонови задачи (изпращане на бюлетини, планирани експорти), не ги пускайте в уеб процеса. Използвайте Уебсайт → Cron задачи, за да извиквате Node скрипт директно:
/home/<акаунт>/nodevenv/myapp/20/bin/node /home/<акаунт>/myapp/scripts/send-newsletter.jsПамет на процеса: Passenger рестартира приложението, ако надхвърли лимита на RAM за акаунта (зависи от плана). Типично Next.js / Nuxt приложение в покой е под 100 MB. Ако стигате лимитите, профилирайте с process.memoryUsage() и потърсете течове, преди да решите, че ви трябва по-голям план.
Собствени домейни и HTTPS: адресът, който задавате за приложението, е това, към което Passenger се свързва. SSL е автоматичен — без допълнителни настройки. За друг домейн или поддомейн първо го добавете в Уебсайт → Домейни, после го изберете като адрес на приложението.
Версия на Node: списъкът Версия показва всички инсталирани версии; сменете я в Настройки на приложението.
Кога да не използвате споделен хостинг за Node
Казано направо — Node.js на споделен хостинг работи чудесно за портфолио сайтове, блогове, маркетингови страници, малки SaaS интерфейси и вътрешни инструменти. Затруднява се при:
- API с голям поток (>50 заявки/сек постоянно) — ще усетите лимита на CPU за акаунта
- Приложения с много WebSockets и хиляди едновременни връзки
- Приложения, които стартират работни процеси (опашки, скрейпъри) — лимитът на процеси за акаунта на Passenger прави това неудобно
- Всичко, което иска systemd, Docker или root достъп
За тях нашият VPS е правилният избор — пълен root, собствено ядро, пуска каквото поискате. Но за повечето Next.js и Nuxt приложения без огромен трафик това ръководство е всичко, което ви трябва.
Накратко
npm run buildлокално- Качете
.next/(Next) или.output/(Nuxt) +package.json+server.cjs - Уебсайт → Node.js и Python → Node.js приложение → папката, стартов файл
server.cjs, режим Production - Инсталиране на зависимости (npm install), после Рестарт
Ако нещо не работи както трябва, отворете тикет — поставете страницата с грешката на Passenger и ще ви посочим реда.
— Екипът на Rivervo