Започнете
Всички статииРЪКОВОДСТВА · 7 МИН. ЧЕТЕНЕ

Пуснете Node.js приложението си на хостинга на Rivervo (Next.js и Nuxt).

RT
Rivervo Team · Rivervo
·
29 април 2026 г.
·
Обновено 13 ноември 2026 г.
Node
ON SHARED HOSTING

Мнозина смятат, че 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 приложения без огромен трафик това ръководство е всичко, което ви трябва.

Накратко

  1. npm run build локално
  2. Качете .next/ (Next) или .output/ (Nuxt) + package.json + server.cjs
  3. Уебсайт → Node.js и Python → Node.js приложение → папката, стартов файл server.cjs, режим Production
  4. Инсталиране на зависимости (npm install), после Рестарт

Ако нещо не работи както трябва, отворете тикет — поставете страницата с грешката на Passenger и ще ви посочим реда.

— Екипът на Rivervo