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

P P T P Chung

Những lỗi thường gặp khi chạy Next.js trên VPS và cách xử lý nhanh

Deploy Next.js lên VPS nghe có vẻ “đơn giản”: build, chạy npm start, trỏ domain, xong. Thực tế khác hẳn. App chạy tốt ở local nhưng lên VPS lại dính đủ lỗi: cổng không mở, 502 Bad Gateway, thiếu biến môi trường, build fail vì thiếu RAM, static file không tải, SSR lỗi âm thầm, reverse proxy cấu hình sai → SEO, hiệu năng, trải nghiệm người dùng cùng bị ảnh hưởng.

Bài này tập trung vào các lỗi phổ biến nhất khi chạy Next.js trên VPS, vì sao chúng xảy ra, dấu hiệu nhận biết, cách xử lý nhanh và cách phòng tránh để hệ thống ổn định hơn.

1. App chạy local ổn, lên VPS lại không truy cập được

Dấu hiệu

– Truy cập domain/IP → timeout. – curl localhost:3000 trên VPS có phản hồi, nhưng ngoài Internet không vào được. – Nginx/Apache báo upstream unavailable.

Nguyên nhân thường gặp

– App chỉ bind vào 127.0.0.1, không lắng nghe 0.0.0.0. – Firewall VPS chặn port. – Security Group/cloud firewall chưa mở 80, 443, 3000. – Reverse proxy trỏ sai port.

Cách xử lý nhanh

1. Kiểm tra app có chạy thật không: 
ps aux | grep next
   ss -tulpn | grep 3000

2. Chạy đúng mode production:

npm run build
   npm run start

3. Nếu chạy custom server, bind:

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.

Tags: #next #nhanh #thuong #tren

Tác giả

P T P

Chia sẻ

Bài viết liên quan

Bình luận (0)

Email của bạn sẽ không được hiển thị công khai.

Chưa có bình luận. Hãy là người đầu tiên!