Hướng dẫn deploy source Node.js/Next.js lên hosting cPanel chi tiết từ A–Z

Nội dung bạn sẽ đạt được

 

• Hiểu toàn bộ quy trình deploy Node.js/Next.js trên cPanel

 

• Biết cách tạo môi trường Node.js bằng Setup Node.js App

• Upload source đúng thư mục và cài dependencies

• Khởi chạy ứng dụng và kiểm tra hoạt động trên domain thực tế

 

7 bước triển khai Node.js/Next.js trên cPanel

 

Bước 1: Mở Setup Node.js App trong cPanel

 

Đăng nhập vào cPanel → tìm mục Setup Node.js App trong phần Software để bắt đầu cấu hình môi trường Node.js.

 

 

Bước 2: Tạo ứng dụng Node.js

 

Nhấn Create Application và điền các thông tin sau:

 

• Node.js version → chọn version phù hợp với project

• Application mode → chọn Development (test) hoặc Production (chạy thật). Ví dụ chọn Development

• Application root → thư mục chứa source code

• Application URL → domain hoặc subdomain chạy app

• Application startup file → file khởi động (thường là app.js, server.js hoặc index.js)

• Passenger log file → giữ mặc định nếu không có nhu cầu chỉnh

 

Sau khi điền xong → nhấn Create

 

 

 

Bước 3: Kích hoạt môi trường ảo bằng Terminal

 

Sau khi tạo app, cPanel sẽ cung cấp một lệnh để vào môi trường Node.

 

• Copy lệnh đó

• Mở Terminal trong cPanel

• Dán lệnh → Enter

 

Mục đích: kích hoạt môi trường để cài package bằng npm.

 

Bước 4: Restart ứng dụng và test domain

 

Quay lại Setup Node.js App → nhấn Restart để reload môi trường.

 

Sau đó mở domain/subdomain đã cấu hình để kiểm tra bước đầu.

 

 

Bước 5: Upload source code lên hosting

 

Vào File Manager → điều hướng tới thư mục đã đặt ở Application root.

 

Upload toàn bộ source Node.js/Next.js gồm:

 

• package.json

• package-lock.json (nếu có)

• thư mục pages, app, src, public …

 

Kiểm tra lại để đảm bảo không thiếu file.

 

 

Bước 6: Cài thư viện và chạy ứng dụng

 

Quay lại Setup Node.js App:

 

• Nhấn Run NPM Install để cài dependencies

• Nhấn Run JS Script để khởi động ứng dụng

 

Với Next.js, script thường là:

Hoặc nếu dùng chế độ dev:

Bước 7: Kiểm tra kết quả

 

Mở trình duyệt → truy cập đúng Application URL đã cấu hình.

 

Nếu mọi thứ đúng, ứng dụng Node.js/Next.js sẽ hoạt động trên hosting.

 

Lưu ý quan trọng khi deploy Next.js trên cPanel

 

• Nên dùng Production mode khi chạy thật để tối ưu hiệu năng

• Next.js cần chạy npm run build trước khi start

• Không nên upload thư mục node_modules → dùng npm install trên server

• Kiểm tra version Node.js phải tương thích với Next.js

 

• Nếu lỗi trắng trang → kiểm tra Passenger log

 

Một số lỗi thường gặp

 

Lỗi 503 hoặc không truy cập được

→ Chưa restart app hoặc sai startup file

 

Lỗi thiếu module

→ Chưa chạy npm install

 

Next.js chỉ hiện thư mục public

→ Chưa build project

 

Sai port

→ Không cần set port thủ công vì Passenger tự handle