Next.js Uygulaması VPS’e Nasıl Deploy Edilir?

Next.js, React üzerine kurulu full-stack bir framework’tür ve geliştirme bittiğinde uygulamanızı gerçek kullanıcıların erişeceği bir sunucuda yayına almanız gerekir. Vercel dışındaki en yaygın ve en çok kontrol veren yol, uygulamayı kendi VPS/sunucunuza deploy etmektir. Next.js, Node.js destekleyen herhangi bir sunucuda “Node.js server” olarak çalışır: önce production derlemesi alınır, sonra Node sunucusu başlatılır ve genellikle PM2 ile kalıcı kılınıp Nginx reverse proxy ile yayınlanır. Bu rehberde tüm bu adımları sıfırdan, doğru sırayla ve production’da karşınıza çıkacak tuzaklarla birlikte anlatıyoruz.

Önemli bir noktayı en başta netleştirelim: Next.js’in sunucu tarafı render (SSR), Incremental Static Regeneration (ISR), Server Actions, akan (streaming) yanıtlar ve after() gibi özelliklerinin tamamı yalnızca canlı bir Node.js süreci üzerinde tam olarak çalışır. Bu nedenle gerçek bir uygulama için Node.js kurabileceğiniz, root erişiminiz olan bir VPS gerekir; statik bir hosting paketi çoğu durumda yeterli olmaz.

Ön Hazırlık: VPS ve Node.js Sürümü

Deploy öncesi sunucunuzun hazır olması gerekir. Next.js’in güncel sürümleri en az Node.js 20.9 gerektirir; daha eski bir sürümle next build hata verir veya beklenmedik davranır. Sunucuda Node sürümünü sabitlemek için nvm kullanmak ve package.json içindeki engines alanını doldurmak iyi bir alışkanlıktır.

node -v          # 20.9 veya uzeri olmali
nvm install 20   # gerekiyorsa nvm ile kur ve varsayilan yap
nvm alias default 20

Ayrıca sunucuda git kurulu olmalı ve uygulamanızı sunucuya çekmenin bir yolu olmalıdır. En temiz yöntem, kodu sunucuda git clone ile çekip bağımlılıkları orada kurmaktır; böylece yerel makinenizin node_modules klasörünü kopyalamak zorunda kalmazsınız.

Build ve Başlatma

package.json dosyanızda build ve start scriptleri bulunmalıdır. Kodu sunucuya çektikten sonra, proje dizininde şu komutları çalıştırın:

npm ci             # package-lock.json'a birebir uyan temiz kurulum
npm run build      # next build - production derlemesi olusturur
npm run start      # next start - varsayilan :3000 portunda sunar

Burada npm install yerine npm ci tercih edin: ci komutu package-lock.json dosyasına birebir uyar, mevcut node_modules klasörünü silip yeniden kurar ve böylece “benim makinemde çalışıyordu” tipi sürüm farklarını önler.

next start mutlaka next build‘ten sonra çalışır; build almadan production başlatılamaz. Bu yüzden her güncellemede önce yeni derleme alınır, sonra süreç yeniden başlatılır.

Çevre Değişkenleri (.env) ve Build Zamanı Tuzağı

En sık yapılan hatalardan biri çevre değişkenleridir. Next.js’te iki tür değişken vardır ve ne zaman okunduklari kritik önemdedir:

Yani veritabanı bağlantısı gibi gizli değerleri sadece sunucuda runtime’da sağlamanız yeterlidir; ancak istemci tarafında kullanılan NEXT_PUBLIC_ önekli değişkenler derleme sırasında kalıbın içine yazılır. Bunları build’den sonra değiştirip yalnızca süreci yeniden başlatırsanız değişiklik etkili olmaz.

Daha Yalın Dağıtım: output standalone

next.config.js dosyanıza output: "standalone" eklediğinizde Next.js, projeyi statik olarak analiz eder ve uygulamayı çalıştırmak için gereken minimum dosyaları .next/standalone klasörüne kopyalar. Bu paket, sunucuda node_modules kurmadan tek başına çalışabilir; özellikle Docker imajlarını çok küçültür.

// next.config.js
module.exports = {
  output: "standalone",
};

Tek pürüz: standalone çıktısı public/ ve .next/static klasörlerini otomatik kopyalamaz. Bu iki klasörü build sonrasında standalone dizinine elle (veya bir script ile) taşımanız, ardından node .next/standalone/server.js ile başlatmanız gerekir. Aksi hâlde sayfa açılır ama CSS ve görseller gelmez.

PM2 ile Kalıcı Çalıştırma

SSH oturumunuz kapandığında next start süreci de ölür. Uygulamanın sunucuda sürekli ayakta kalması, çökünce kendini yeniden başlatması ve sunucu yeniden başladığında otomatik açılması için bir süreç yöneticisi gerekir. Node.js dünyasında bunun standardı PM2‘dir.

npm install -g pm2

pm2 start npm --name nextapp -- start   # uygulamayi baslat
pm2 save                                # mevcut surec listesini kaydet
pm2 startup                             # sunucu acilisinda otomatik baslat

pm2 startup komutu size kopyalayıp çalıştırmanız gereken bir satır verir; bunu çalıştırdıktan sonra pm2 save dediğinizde sunucu her yeniden başladığında uygulamanız kendiliğinden ayağa kalkar.

Cluster Modu ve Sıfır Kesintili Güncelleme

VPS’inizde birden fazla CPU çekirdeği varsa, PM2 cluster modu ile uygulamanızı her çekirdek için bir kopya olacak şekilde çalıştırıp gelen trafiği otomatik dağıtabilirsiniz:

pm2 start npm --name nextapp -i max -- start   # tum cekirdekleri kullan
pm2 reload nextapp                             # sifir kesintili yeniden yukleme

pm2 reload, restart‘tan farklı olarak süreçleri sırayla yeniler: önce yeni süreç hazır olur, sonra eski süreç kapatılır. Bu sayede yeni sürüm yayınlarken tek bir istek bile düşmez. Güncelleme akışınız tipik olarak şu şekilde olur: git pull → npm ci → npm run build → pm2 reload nextapp.

Log Yönetimini Unutmayın

PM2 logları varsayılan olarak ~/.pm2/logs/ altında tutar ve bu dosyalar sınırsız büyüyebilir; zamanla disk dolabilir. Bunu önlemek için log döndürmeyi (logrotate) kurun:

pm2 install pm2-logrotate

Nginx Reverse Proxy ile Yayınlama

Next.js’i doğrudan 80/443 portuna bağlamak yerine 3000 portunda tutup önüne Nginx koymak production’da standart yaklaşımdır. Nginx iç portu gizler, statik istekleri verimli karşılar, aynı sunucuda birden fazla siteyi aynı anda yayınlamanıza imkan verir ve SSL’i tek bir katmanda sonlandırır.

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

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

X-Forwarded-Proto ve X-Real-IP başlıklarını eklemek önemlidir; aksi hâlde uygulamanız ziyaretçinin gerçek IP’sini ve bağlantının HTTPS olduğunu göremez. Yapılandırmayı test edip Nginx’i yeniden yükleyin:

nginx -t              # yapilandirmayi dogrula
systemctl reload nginx

HTTPS: Let’s Encrypt ile Ücretsiz SSL

HTTPS için Nginx katmanına Let’s Encrypt sertifikası ekleyin. Certbot, Nginx yapılandırmanızı otomatik güncelleyip 90 günlük sertifikayı süresiz olarak kendisi yeniler:

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

Alternatif olarak ticari bir SSL sertifikası da kullanabilirsiniz; kurumsal projelerde uzatılmış doğrulama (EV/OV) gerektiren durumlar için bu daha uygundur. Alanın DNS yönetimi ve alan adı işlemleri için alan adı sorgulama sayfasından ilerleyebilirsiniz.

Güvenlik ve Production Sertleştirmesi

Uygulama ayakta diye iş bitmiş sayılmaz; sunucuyu dışarıya açmadan önce birkaç temel önlemi almak gerekir:

• Güvenlik duvarı: Yalnızca 22 (SSH), 80 ve 443 portlarını dışarıya açın. 3000 portu yalnızca localhost üzerinden Nginx’e konuşmalı, internete kapalı olmalı.
• Root yerine ayrı kullanıcı: Uygulamayı root ile değil, sınırlı yetkili ayrı bir kullanıcı ile çalıştırın.
• SSH sertleştirme: Şifre yerine SSH anahtarı kullanın, gerekirse SSH portunu değiştirin.
• Otomatik güncelleme: İşletim sistemi güvenlik yamalarını düzenli uygulayın.

Deploy Yöntemleri Karşılaştırması

Next.js’i bir VPS’e taşımanın tek bir doğru yolu yoktur; ihtiyaca göre değişir. Aşağıdaki tablo en yaygın üç yaklaşımı özetler:

Dikkat Edilmesi Gerekenler

• next start her zaman next build‘ten sonra çalışır; aksi hâlde hata alırsınız.
• Uygulamayı 3000 portunda bırakın; HTTPS’i Nginx’te sonlandırın, doğrudan 443’e bağlamayın.
• Daha hafif dağıtım için output: "standalone" seçeneğini değerlendirin; bu durumda public/ ve .next/static klasörlerini elle kopyalamayı unutmayın.
• Ortam değişkenlerini production’a uygun ayarlayın; NEXT_PUBLIC_* değişkenleri build zamanında tanımlı olmalıdır.
• PM2 loglarını logrotate ile sınırlandırın, aksi hâlde disk zamanla dolar.
• 3000 portunu güvenlik duvarında internete kapatın; yalnızca localhost’tan erişim açın.

Next.js gibi Node.js tabanlı uygulamalar sürekli çalışan bir sunucu üzerinde yaşar; bu yüzden altyapının kararlılığı doğrudan uygulamanızın erişilebilirliğine yansır. Alastyr’ın VPS/sunucu çözümleri İzmir’deki kendi veri merkezimizde, N+1 yedekli altyapıda ve %99.9 çalışma süresi taahhüdüyle barındırılır; root erişimi, NVMe SSD depolama ve 7/24 destek ile Node.js uygulamanızı kesintisiz yayında tutarsınız. Daha büyük ve değişken yükler için esnek ölçekleme isteyenler bulut sunucu seçeneğini de değerlendirebilir.

Sıkça Sorulan Sorular

Next.js’i nerede barındırabilirim?

Node.js çalıştırabilen herhangi bir VPS veya sunucuda barındırabilirsiniz; bu durumda SSR, ISR, Server Actions dahil tüm Next.js özellikleri desteklenir. Yalnızca tamamen statik bir siteniz varsa statik bir barındırma da yeterli olur.

Next.js için hangi Node.js sürümü gerekir?

Next.js’in güncel sürümleri en az Node.js 20.9 gerektirir. Daha eski bir sürümle build alamazsınız; bu yüzden sunucuda Node sürümünü nvm ile sabitlemek ve package.json içindeki engines alanını doldurmak iyi bir pratiktir.

PM2 şart mı?

Teknik olarak şart değil ama production için şiddetle önerilir. PM2 uygulamayı arka planda tutar, çökerse otomatik yeniden başlatır, sunucu açılışında kendiliğinden ayağa kaldırır ve cluster modu ile çoklu çekirdek kullanmanıza imkan verir. Alternatifi systemd servisi yazmaktır; ancak PM2 çoğu proje için daha pratiktir.

output: standalone ne işe yarar?

Bu seçenek, uygulamayı çalıştırmak için gereken minimum dosyaları .next/standalone klasörüne çıkarır ve sunucuda node_modules kurmadan çalışmanızı sağlar. Özellikle Docker imajlarını çok küçülür. Tek dikkat noktası, public ve .next/static klasörlerinin otomatik kopyalanmaması; bunları elle taşımanız gerekir.

SSL’i nasıl eklerim?

En yaygın yöntem, Nginx katmanında certbot ile ücretsiz Let’s Encrypt sertifikası kurmaktır; certbot sertifikayı otomatik yeniler. Kurumsal projelerde uzatılmış doğrulama gerekiyorsa ticari bir SSL sertifikası da tercih edilebilir.

Uygulama hangi portta çalışır?

Next.js varsayılan olarak 3000 portunda sunum yapar. Bu portu internete kapalı tutup önüne Nginx koyar, ziyaretçileri 80 ve 443 portları üzerinden bu sürece yönlendirirsiniz.

Yeni sürüm yayınlarken siteyi kapatmam gerekir mi?

Hayır. PM2 cluster modunda pm2 reload komutu süreçleri sırayla yeniler; önce yeni süreç hazır olur, sonra eski kapatılır. Böylece güncelleme sırasında tek bir istek bile düşmez.

Statik export yapabilir miyim?

Evet, SSR ve dinamik özellik kullanmayan tamamen statik siteler için output: export ile statik HTML üretip bir CDN’e veya basit bir web sunucusuna deploy edebilirsiniz. Ancak Server Actions, ISR gibi özellikler kullanıyorsanız statik export uygun değildir.

3000 portunu dışarıya açmalı mıyım?

Hayır. 3000 portu yalnızca localhost üzerinden Nginx ile konuşmalı ve güvenlik duvarında internete kapalı olmalıdır. Dışarıya yalnızca 22 (SSH), 80 ve 443 portlarını açmanız önerilir.