Bắt đầu
Tất cả bài viếtHƯỚNG DẪN · 9 PHÚT ĐỌC

Triển khai ứng dụng Node.js trên hosting Rivervo (Next.js & Nuxt).

RT
Rivervo Team · Rivervo
·
29 tháng 4, 2026
·
Cập nhật 13 tháng 11, 2026
Node
ON SHARED HOSTING

Nhiều người nghĩ ứng dụng Node.js phải chạy trên VPS. Không phải vậy — mọi gói shared hosting của Rivervo đều có mục Node.js và Python trong menu website, khởi chạy một tiến trình Phusion Passenger cho ứng dụng của bạn, phía sau cùng front-end Apache đang phục vụ các website khác của bạn.

Bài hướng dẫn này đi qua toàn bộ quy trình cho hai framework phổ biến nhất: Next.js và Nuxt 3. Kết quả cuối cùng: ứng dụng của bạn chạy tại https://tenmiencuaban.vn (hoặc một tên miền con bất kỳ), trên một tiến trình Node.js thật, tự chạy lại sau khi khởi động lại máy chủ, khởi động lại được chỉ với một cú nhấp.

Nếu bạn chưa từng triển khai ứng dụng Node lên shared hosting, phần ai cũng vướng là tệp khởi động — Passenger cần một script đầu vào duy nhất để khởi chạy framework. Bên dưới có sẵn một tệp cho mỗi framework; chỉ cần sao chép, không phải sửa.

Cần chuẩn bị gì trước khi bắt đầu

  • Một gói hosting Rivervo (gói nào cũng được — ứng dụng Node.js chạy trên mọi gói)
  • Node.js v20 trở lên trên máy của bạn để build ứng dụng
  • Bản build sẵn sàng để tải lên (hướng dẫn riêng cho từng framework bên dưới)
  • Quyền truy cập trình quản lý tệp hoặc SFTP vào tài khoản (cách nào cũng được)

Bạn không cần root, sudo, systemd hay cấu hình reverse proxy. Passenger lo tất cả.

Bước 1 — Build ứng dụng trên máy

Bạn sẽ tải lên ứng dụng đã build, không phải mã nguồn. Bảng điều khiển có cài dependency nhưng không biên dịch React hay chạy Vite build. Hãy làm việc đó trên máy của bạn trước.

Next.js:

npm ci
npm run build

Lệnh này tạo ra .next/ (kết quả build). Đừng chạy next start ở đây — lát nữa chúng ta sẽ khởi chạy từ tệp khởi động.

Nuxt 3:

npm ci
npm run build

Lệnh này tạo ra .output/ (thư mục build chung của Nuxt). Tương tự — chưa chạy gì cả.

Bước 2 — Tải lên đúng tệp

Bạn không cần tải lên node_modules/. Bảng điều khiển sẽ cài dependency cho bạn. Bạn cũng không cần git hay cache build.

Tải lên tài khoản của bạn, tốt nhất vào một đường dẫn bên ngoài public_html (ví dụ /home/<account>/myapp/). Vì sao bên ngoài? Vì Passenger sẽ tự gắn public_html vào gốc URL, và đặt mã ứng dụng trong đó sẽ làm lộ mã.

FrameworkTải lênBỏ qua
Next.js.next/, public/, package.json, package-lock.json, next.config.js, tệp server.cjs của bạn (bên dưới)node_modules/, .git/, .env.local
Nuxt 3.output/, package.json, package-lock.json, tệp server.cjs của bạn (bên dưới)node_modules/, .nuxt/, .git/, mã nguồn pages/, components/

Có hai cách đưa tệp lên:

  • Website → Tệp → tải lên tệp zip → giải nén là cách dễ nhất nếu kết nối mạng chập chờn.
  • SFTP (FileZilla, Cyberduck, rsync) nhanh hơn khi triển khai nhiều lần. Máy chủ, cổng, tên người dùng và mật khẩu có trong Website → SSH và SFTP.

Bước 3 — Thêm tệp khởi động

Đây là tệp Passenger chạy khi có request đến. Đặt nó cạnh package.json trong thư mục ứng dụng.

Cho 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}`)
  })
})

Tệp này làm gì:

  • Tải Next và trỏ nó tới thư mục hiện tại (nơi có .next/ và package.json).
  • Tạo bộ xử lý request từ router nội bộ của Next.
  • Khởi động máy chủ HTTP trên cổng Passenger cấp (process.env.PORT).
  • Dùng cổng 3000 khi chạy thử trên máy.

dev được suy ra tự động từ NODE_ENV — chọn chế độ Production trong bảng điều khiển (sẽ làm ở Bước 4) và Next sẽ chạy ở chế độ production.

Cho 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}`)
    })
  })
})

Tệp này làm gì:

  • Import động .output/server/index.mjs của Nuxt (điểm vào do npm run build tạo ra).
  • Dùng createApp() để tạo instance máy chủ H3.
  • Lắng nghe trên cổng Passenger cấp.

Việc dùng import() động là có chủ đích — module .mjs không thể require(), nhưng tệp .cjs có thể import động chúng. Đây là cách gọn nhất chạy được trong trình khởi chạy của Passenger.

Bước 4 — Tạo ứng dụng trong bảng điều khiển

Mở dự án của bạn → Website → Node.js và Python → Ứng dụng Node.js.

TrườngGiá trị
Phiên bản20 trở lên
Chế độProduction
Thư mụcmyapp trong thư mục home (nơi bạn đã tải tệp lên)
Địa chỉtenmiencuaban.vn (hoặc tên miền con như app.tenmiencuaban.vn)
Tệp khởi độngserver.cjs

Bấm Tạo. Môi trường Node.js được tạo trong ~/nodevenv/myapp/20/.

Cài dependency

Sau khi tạo ứng dụng, bấm Cài dependency (npm install) trên ứng dụng và theo dõi kết quả. Nếu lỗi:

  • Kiểm tra package.json nằm ở thư mục gốc của ứng dụng (không nằm trong thư mục con).
  • Với Next.js: xác nhận next nằm trong dependencies, không phải devDependencies (cài đặt production bỏ qua dev dependency).
  • Với Nuxt: bản thân nuxt cũng phải là dependency thông thường.

Thêm biến môi trường

Trong Cài đặt của ứng dụng → Biến môi trường → Thêm biến. Chế độ Production đã tự đặt NODE_ENV=production.

Với ứng dụng Next.js đọc giá trị lúc chạy (URL cơ sở dữ liệu, API key), hãy thêm chúng ở đây. Đừng đưa tệp .env chứa thông tin bí mật lên — biến môi trường của ứng dụng mới là nơi phù hợp.

Lưu cài đặt sẽ khởi động lại ứng dụng, nên biến mới có hiệu lực ngay.

Bước 5 — Kiểm tra

Mở URL ứng dụng. Bạn sẽ thấy ứng dụng của mình.

Nếu thấy trang lỗi của Passenger, hãy mở rộng và xem phần cuối — hầu như luôn có stack trace rõ ràng. Hai lỗi phổ biến nhất:

Error: Cannot find module 'next' — npm install chưa chạy, hoặc chạy sai thư mục. Bấm lại Cài dependency (npm install).

Error: ENOENT: no such file or directory, open '.next/...' — bạn đã tải mã nguồn lên nhưng chưa tải thư mục .next/ đã build. Build trên máy và tải lên lại.

Cách triển khai bản cập nhật

Lặp lại bước 1, 2 và bấm Khởi động lại trên ứng dụng. Cụ thể:

1. Build trên máy      npm run build
2. Tải lên            .next/ hoặc .output/, cùng mã nguồn/cấu hình đã thay đổi
3. Bảng điều khiển    Khởi động lại ứng dụng

Nếu bạn thay đổi package.json, hãy bấm Cài dependency (npm install) trước khi khởi động lại. Thích dùng dòng lệnh hơn? Website → Terminal: thẻ ứng dụng hiển thị lệnh để vào môi trường của nó.

Lỗi thường gặp

WebSocket: Passenger hỗ trợ HTTP/1.1 và HTTP/2. Nâng cấp WebSocket hoạt động với các route có sẵn của Next.js và Nuxt. Nếu bạn dùng máy chủ WebSocket riêng (ws, socket.io), nó dùng chung cổng và khởi động qua cùng tệp server.cjs — không cần cấu hình thêm.

Tải tệp lên / giới hạn body-parser trong next.config.js: giới hạn mặc định cho nội dung request của Passenger là 10 MB. Nếu cần tải tệp lớn, hãy tăng passenger_max_request_size qua .htaccess trong public_html:

PassengerMaxRequestSize 52428800

(50 MB tính bằng byte.)

Cron job: nếu ứng dụng cần tác vụ nền (gửi bản tin, xuất dữ liệu theo lịch), đừng chạy chúng trong tiến trình web. Dùng Website → Cron job để gọi trực tiếp một script Node:

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

Bộ nhớ tiến trình: Passenger khởi động lại ứng dụng nếu vượt giới hạn RAM của tài khoản (tùy gói). Một ứng dụng Next.js / Nuxt thông thường khi rảnh dùng dưới 100 MB. Nếu chạm giới hạn, hãy đo bằng process.memoryUsage() và tìm rò rỉ bộ nhớ trước khi cho rằng cần gói lớn hơn.

Tên miền riêng và HTTPS: địa chỉ bạn đặt cho ứng dụng là địa chỉ Passenger gắn vào. SSL được cấp tự động — không cần cấu hình thêm. Với tên miền khác hoặc tên miền con, hãy thêm vào Website → Tên miền trước, rồi chọn làm địa chỉ của ứng dụng.

Phiên bản Node: danh sách Phiên bản hiển thị mọi phiên bản đã cài; đổi trong Cài đặt của ứng dụng.

Khi nào không nên dùng shared hosting cho Node

Nói thẳng — Node.js trên shared hosting chạy rất tốt cho website portfolio, blog, trang marketing, front-end SaaS nhỏ, công cụ nội bộ. Nó gặp khó với:

  • API lưu lượng cao (>50 req/giây liên tục) — bạn sẽ chạm giới hạn CPU của tài khoản
  • Ứng dụng dùng nhiều WebSocket với hàng nghìn kết nối đồng thời
  • Ứng dụng tạo thêm tiến trình worker (queue worker, scraper) — giới hạn số tiến trình mỗi tài khoản của Passenger khiến việc này bất tiện
  • Bất cứ thứ gì cần systemd, Docker hay quyền root

Với những trường hợp đó, VPS của chúng tôi là lựa chọn đúng — toàn quyền root, kernel riêng, chạy gì cũng được. Nhưng với phần lớn ứng dụng Next.js và Nuxt không phải gánh lưu lượng khổng lồ, bài hướng dẫn này là đủ.

Tóm tắt

  1. npm run build trên máy
  2. Tải lên .next/ (Next) hoặc .output/ (Nuxt) + package.json + server.cjs
  3. Website → Node.js và Python → Ứng dụng Node.js → thư mục, tệp khởi động server.cjs, chế độ Production
  4. Cài dependency (npm install), rồi Khởi động lại

Nếu có gì bất thường, hãy mở ticket — dán trang lỗi của Passenger và chúng tôi sẽ chỉ ra dòng gây lỗi.

— Đội ngũ Rivervo