Next.js trên VPS hay sập? 7 lỗi thường gặp và cách xử lý nhanh

ps aux | grep next
   ss -tulpn | grep 3000

npm run build
   npm run start

server.listen(3000, '0.0.0.0')

4. Mở firewall:

ufw allow 80
   ufw allow 443
   ufw allow 3000
   ufw status

5. Nếu dùng Nginx, kiểm tra upstream:

proxy_pass http://127.0.0.1:3000;

Mẹo phòng tránh

– Không expose trực tiếp port app ra Internet nếu đã có Nginx.
– Chuẩn chuẩn nhất: Nginx nghe 80/443 → proxy về 127.0.0.1:3000.

2. Lỗi 502 Bad Gateway từ Nginx

Dấu hiệu

– Nginx hoạt động, nhưng truy cập web nhận 502 Bad Gateway.

Nguyên nhân

– Next.js process chết.
– App chưa start nhưng Nginx đã proxy.
– Sai proxy_pass.
– App crash do thiếu env, thiếu RAM, lỗi runtime.

Cách xử lý nhanh

Kiểm tra 3 lớp:

Lớp 1: Nginx

nginx -t
systemctl status nginx
tail -f /var/log/nginx/error.log

Lớp 2: App Node/Next.js

pm2 logs
journalctl -u your-app.service -f

Lớp 3: Port

curl http://127.0.0.1:3000

Nếu curl fail → lỗi app. Nếu curl ok nhưng ngoài web lỗi → lỗi Nginx.

Cấu hình Nginx cơ bản ổn định

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Mẹo phòng tránh

– Dùng pm2 hoặc systemd để app tự restart khi crash.
– Không chạy app bằng SSH session rồi đóng terminal.

3. Thiếu biến môi trường khi build hoặc runtime

Dấu hiệu

– Build fail: undefined.
– SSR lỗi Cannot read properties of undefined.
– App gọi API sai URL, auth fail, DB fail.

Nguyên nhân

– .env.local ở local có, VPS không có.
– Nhầm giữa env server-side và client-side.
– Quên prefix NEXT_PUBLIC_ cho biến cần dùng ở frontend.
– Update env nhưng chưa restart app.

Cách xử lý nhanh

1. Kiểm tra file env trên VPS.
2. In thử biến quan trọng:

echo $NODE_ENV

3. Với biến dùng trong browser:
– Phải là NEXT_PUBLIC_API_URL
4. Sau khi sửa env:

npm run build
   pm2 restart all

Lưu ý quan trọng

– NEXT_PUBLIC_* → đóng gói ra client.
– Biến bí mật như DB password, JWT secret → không dùng prefix này.

Mẹo phòng tránh

– Tạo file checklist env cho từng môi trường: dev, staging, production.
– Deploy xong luôn verify các biến tối quan trọng.

4. Build fail vì thiếu RAM hoặc VPS quá yếu

Dấu hiệu

– next build bị kill giữa chừng.
– Log có Killed.
– VPS treo, swap tăng mạnh, CPU full.

Nguyên nhân

– VPS RAM thấp: 512MB–1GB rất dễ fail.
– App nhiều page, nhiều package nặng.
– Chạy build cùng nhiều service khác.

Cách xử lý nhanh

Kiểm tra tài nguyên

free -h
top
df -h

Thêm swap tạm thời

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
free -h

Build production sạch

rm -rf .next
npm ci
npm run build

Mẹo phòng tránh

– VPS production cho Next.js nên có tối thiểu 2GB RAM nếu app SSR trung bình.
– Build ở CI/CD rồi chỉ đưa artifact lên VPS nếu hạ tầng yếu.
– Dọn log, cache, package thừa định kỳ.

5. Static file, ảnh, CSS không tải đúng

Dấu hiệu

– Giao diện vỡ.
– File trong /_next/static/... trả 404.
– Ảnh từ next/image không hiện.

Nguyên nhân

– Nginx cấu hình sai path/proxy.
– Deploy thiếu thư mục .next.
– Sai basePath hoặc assetPrefix.
– Domain ảnh ngoài chưa khai báo trong next.config.js.

Cách xử lý nhanh

1. Kiểm tra file build tồn tại:

ls -la .next

2. Nếu dùng next/image, khai báo domain:

images: {
     domains: ['example.com']
   }

3. Nếu app nằm sau subpath như /app, kiểm tra:
– basePath
– assetPrefix

4. Nếu Nginx có rule rewrite custom, test kỹ để không chặn /_next/static.

Mẹo phòng tránh

– Không tự tối ưu Nginx quá sớm nếu chưa hiểu flow static của Next.js.
– Sau mỗi deploy, test ngay:
– trang chủ
– 1 trang SSR
– 1 ảnh
– 1 file CSS/JS

6. Lỗi permission: app không đọc/ghi được file

Dấu hiệu

– Upload fail.
– Log fail.
– PM2/systemd không đọc được thư mục dự án.
– Build fail do quyền sở hữu sai.

Nguyên nhân

– Copy file bằng root, chạy app bằng user khác.
– Thư mục dự án, log, upload không cùng owner.

Cách xử lý nhanh

whoami
ls -la
chown -R www-data:www-data /var/www/your-app
chmod -R 755 /var/www/your-app

Nếu app cần ghi vào thư mục upload/cache, cấp đúng quyền riêng thư mục đó, không mở toàn bộ dự án quá rộng.

Mẹo phòng tránh

– Chọn 1 user chạy app cố định.
– Hạn chế deploy bằng root nếu không cần.

7. App chết sau khi logout SSH

Dấu hiệu

– Vừa chạy npm start xong web hoạt động.
– Đóng terminal/thoát SSH → web chết.

Nguyên nhân

– Process đang gắn với shell hiện tại.

Cách xử lý nhanh

Dùng process manager.

Với PM2

npm install -g pm2
pm2 start npm --name "next-app" -- start
pm2 save
pm2 startup

Hoặc systemd

– Tạo service để tự start khi reboot.
– Dễ quản lý log, restart policy.

Mẹo phòng tránh

– Production → luôn dùng pm2 hoặc systemd.
– Không chạy app thủ công dài hạn.

8. SSL, HTTPS, redirect loop

Dấu hiệu

– Trình duyệt báo không an toàn.
– HTTP ↔ HTTPS redirect lặp vô hạn.
– Cookie auth hoạt động sai.

Nguyên nhân

– Cert chưa cài đúng.
– Reverse proxy không gửi header chuẩn.
– App hiểu request là HTTP dù ngoài là HTTPS.

Cách xử lý nhanh

Cài SSL với Let’s Encrypt:

apt install certbot python3-certbot-nginx
certbot --nginx -d yourdomain.com -d www.yourdomain.com

Đảm bảo Nginx có:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;

Mẹo phòng tránh

– Test login/logout sau khi bật HTTPS.
– Kiểm tra cookie secure trong production.

9. Hiệu năng kém: CPU cao, phản hồi chậm

Dấu hiệu

– TTFB cao.
– VPS CPU spike khi nhiều request.
– Trang SSR chậm rõ rệt.

Nguyên nhân

– Quá nhiều SSR nặng.
– Query DB/API chậm.
– Không cache.
– VPS cấu hình yếu so với traffic.

Cách xử lý nhanh

– Dùng next build chuẩn production.
– Ưu tiên SSG/ISR cho trang ít thay đổi.
– Cache ở Nginx/CDN khi phù hợp.
– Giảm log debug.
– Profile các API/server component chậm.

Mẹo phòng tránh

– Không dùng SSR cho mọi trang.
– Theo dõi tài nguyên:

htop
  pm2 monit

Checklist xử lý nhanh khi Next.js lỗi trên VPS

Khi web “sập”, đi theo thứ tự này:

1. App còn chạy không?

pm2 status
   ss -tulpn | grep 3000

2. Build có thành công không?

ls .next

3. Env đủ chưa?
4. Nginx đúng config chưa?

nginx -t

5. Log báo gì?

pm2 logs
   tail -f /var/log/nginx/error.log

6. RAM/CPU/Disk ổn không?

free -h
   df -h
   top

Kết luận

Phần lớn lỗi khi chạy Next.js trên VPS không nằm ở framework, mà ở “vùng tiếp giáp” giữa app và hạ tầng: reverse proxy, port, env, RAM, quyền file, SSL, process manager. Hiểu đúng các điểm này → thời gian xử lý sự cố giảm rất mạnh.

Cách tiếp cận thực tế nhất: chuẩn hóa quy trình deploy, luôn dùng pm2 hoặc systemd, kiểm tra log theo lớp app → port → proxy → domain, và giữ một checklist debug ngắn cho production. Làm được vậy, Next.js trên VPS hoàn toàn có thể ổn định, nhanh, dễ vận hành, kể cả với đội nhỏ hoặc dự án tự quản trị.

Nếu muốn, tôi có thể viết tiếp một bài companion: “Quy trình deploy Next.js lên VPS với Nginx + PM2 + SSL từ A-Z” dạng thực chiến.