Next.js Dağıtım ve HMR Hata Ayıklama Rehberi: Production ve Dev Ortamı Çözümleri

Modern web uygulamanızı sunucuya taşımak veya geliştirme aşamasında anlık kod güncellemelerinin takılmasıyla uğraşmak, yazılım geliştiricilerin en sık karşılaştığı zorluklardandır. React ekosisteminin en güçlü çerçevelerinden biri olan Next.js, sunucu taraflı işleme (SSR), statik site oluşturma (SSG) ve hibrit yapısıyla muazzam bir performans sunar. Ancak sunucu yapılandırmaları, konteyner mimarileri ve canlı geliştirme sunucusu ayarları karmaşıklaştıkça Next.js dağıtım ve HMR hata ayıklama süreçleri kritik bir uzmanlık alanı haline gelir.

Özellikle Next.js 15 ile Web Uygulaması Geliştirme: Başlangıç Rehberi içeriğimizde ele aldığımız temel mimariyi production ortamına taşırken Docker, Nginx, Vercel veya özel VPS altyapılarında beklenmedik kesintiler yaşanabilir. Geliştirme ortamında kod değişikliklerinizin tarayıcıya anında yansımaması (Hot Module Replacement - HMR kopmaları) veya canlı ortamda ortaya çıkan Hydration Mismatch hataları projenizin teslim süresini ve kalitesini doğrudan etkiler. Bu rehberde, 2026 standartlarında bir Next.js uygulamasını sıfırdan sorunsuz bir şekilde yayınlamayı ve HMR tıkanıklıklarını adım adım çözmeyi uygulamalı örneklerle inceleyeceğiz.

Next.js Dağıtım Stratejileri ve Platform Karşılaştırması

Next.js projenizi canlıya alırken seçebileceğiniz üç temel dağıtım mimarisi bulunmaktadır: Sunucusuz (Serverless/Edge) platformlar, Docker tabanlı Self-Hosted (Kendi Sunucunda Barındırma) altyapıları ve Statik Dışa Aktarım (Static Export). Projenizin ölçeğine, veri gizliliği gereksinimlerine ve bütçenize göre doğru yöntemi seçmeniz gerekir.

• Vercel ve Cloudflare Pages (Serverless): Yapılandırma gerektirmeyen, git entegrasyonu ile otomatik build alan ve Edge Network avantajı sunan çözümlerdir. Küçük ve orta ölçekli projeler için idealdir ancak yüksek trafikli uygulamalarda maliyet artabilir.
• Docker ve Kubernetes (Self-Hosted): Sunucu altyapısını tamamen kontrol etmek isteyen kurumsal projeler için en uygun seçenektir. output: 'standalone' modu sayesinde minimize edilmiş bağımlılıklarla çalışır.
• Static Export (next export): Node.js sunucusu gerektirmeyen, sadece HTML/CSS/JS üreten yapıdır. SSR veya dinamik API rotaları desteklenmez.

Standalone Docker Yapılandırması ile Dağıtım

Kendi sunucunuzda (VPS veya Kubernetes) performanslı bir Next.js dağıtım süreci yürütmek istiyorsanız, uygulamanın derleme çıktısını küçülten standalone modunu aktif etmelisiniz. İlk olarak next.config.mjs dosyanızı güncelleyin:

/** @type {import('next').NextStyle} */
const nextConfig = {
  output: 'standalone',
  // Gerekli diğer konfigürasyonlar
};

export default nextConfig;

Bu ayar, npm install gereksinimini ortadan kaldırarak yalnızca uygulamanın çalışması için gereken node_modules bağımlılıklarını .next/standalone klasörüne kopyalar. Ardından aşağıdaki optimize edilmiş multi-stage Dockerfile yapısını kullanabilirsiniz:

FROM node:20-alpine AS base

FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000
ENV HOSTNAME "0.0.0.0"

CMD ["node", "server.js"]

Bu yöntem sayesinde image boyutunuz 1 GB seviyesinden 150 MB civarına düşecek ve otomasyon süreçleriniz hızlanacaktır. Süreçlerinize CI/CD entegrasyonu eklemek isterseniz CI/CD Süreçleri Nedir? Modern Yazılım Dağıtım Rehberi makalemize göz atabilirsiniz.

Production Ortamında Sık Karşılaşılan Next.js Dağıtım Hataları

Dağıtım sonrasında uygulamanızın beyaz ekranda kalması veya 500 hatası vermesi çoğunlukla belirli sistemik farklardan kaynaklanır.

1. Ortam Değişkeni (Environment Variables) Uyuşmazlıkları

Next.js tarayıcı tarafında erişilecek değişkenler için NEXT_PUBLIC_ ön ekini zorunlu kılar. Derleme zamanında (Build Time) çakılan değişkenler static dosyalara gömülür. Docker mimarisinde ARG ve ENV ayrımını doğru yapmazsanız istemci tarafındaki API çağrıları undefined adreslere istek atar.

Kritik İpucu: NEXT_PUBLIC_ ile başlayan değişkenler derleme anında koda işlenir. Sunucu tarafında (Server-Side) kullanılan gizli anahtarlar ise çalışma anında (Runtime) okunabilir.

2. Hydration Mismatch (İstemci-Sunucu Uyumsuzluğu)

Sunucuda üretilen HTML ile tarayıcıda React tarafından oluşturulan DOM ağacı uyuşmadığında bu hata alınır. Örneğin window.localStorage veya new Date() gibi tarayıcıya özel değerlerin sunucu render sürecinde doğrudan kullanılması ana nedendir.

// Hatalı Kullanım
export default function UserProfile() {
  const token = localStorage.getItem('token'); // SSR sırasında ç çöker veya mismatch verir
  return <div>Token: {token}</div>;
}

// Doğru Kullanım
'use client';
import { useState, useEffect } from 'react';

export default function UserProfile() {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    setToken(localStorage.getItem('token'));
  }, []);

  return <div>Token: {token}</div>;
}

HMR (Hot Module Replacement) Nedir ve Neden Bozulur?

HMR (Hot Module Replacement), geliştirme sunucusunda (Dev Server) yaptığınız kod değişikliklerinin tüm sayfayı yeniden yüklemeye (Full Refresh) gerek kalmadan, mevcut uygulama durumunu (State) koruyarak tarayıcıda anında güncellenmesini sağlayan bir teknolojidir. Next.js varsayılan olarak Turbopack veya Webpack tabanlı HMR mimarisini kullanır.

HMR mantığı, tarayıcı ile local Node.js sunucusu arasında kurulan bir WebSocket (WS/WSS) bağlantısına dayanır. Ancak aşağıdaki senaryolarda bu bağlantı kopar ve konsolda WebSocket connection to 'ws://...' failed hatası görünür:

• Reverse Proxy (Nginx/Caddy/Traefik) Engelleri: Proxy sunucusunun WebSocket başlıklarını (Upgrade ve Connection) geçirmemesi.
• Docker / Container Ağ Izolasyonu: Konteyner içindeki dosya değişikliklerinin (File System Events) ana bilgisayara (Host OS) bildirilmemesi.
• WSL2 (Windows Subsystem for Linux) Dosya Sistemi Sınırları: Projenin Windows diski (/mnt/c/) üzerinde çalıştırılması sonucu inotify olaylarının tetiklenmemesi.
• Yanlış assetPrefix veya Port Yapılandırması: Uygulamanın farklı bir portta çalışıp HMR paketlerini ana porttan istemesi.

Adım Adım Next.js HMR Hata Ayıklama Yöntemleri

Geliştirme deneyiminizi sekteye uğratan HMR kopmalarını adım adım teşhis edip çözelim.

1. Nginx Reverse Proxy İçin WebSocket Yapılandırması

Eğer yerel geliştirme veya test ortamınızda Nginx arkasında çalışıyorsanız, Nginx varsayılan olarak WebSocket isteklerini normal HTTP/1.1 olarak değerlendirir ve bağlantıyı keser. nginx.conf dosyanıza _next/webpack-hmr veya Turbopack rotası için özel yükseltme tanımları eklemelisiniz:

server {
    listen 80;
    server_name dev.local.site;

    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_cache_bypass $http_upgrade;
    }

    # Next.js HMR WebSocket Özel Rotası
    location /_next/webpack-hmr {
        proxy_pass http://localhost:3000/_next/webpack-hmr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_read_timeout 86400;
    }
}

2. Docker ve WSL2 Ortamlarında Polling (Yoklama) Aktifleştirme

Docker Bind Mount kullanırken veya WSL2 üzerinde geliştirme yaparken dosya sistemindeki değişiklikler inotify servisi tarafından fark edilmeyebilir. Bu durumda Next.js HMR paketlerini dosya yoklama (polling) yöntemine geçirmelisiniz.

next.config.mjs dosyanıza Webpack watcher ayarını ekleyin:

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { dev, isServer }) => {
    if (dev && !isServer) {
      config.watchOptions = {
        poll: 800, // Her 800ms'de bir dosyaları kontrol et
        aggregateTimeout: 300,
      };
    }
    return config;
  },
};

export default nextConfig;

Sistem Kaynağı Uyarısı: poll seçeneği işlemci (CPU) kullanımını bir miktar artırabilir. Bu nedenle yalnızca Docker veya WSL2 gibi işletim sistemi katmanlarındaki dosya izleme sorunlarında tercih edilmelidir.

3. Chrome DevTools ve Network Sekmesi İle Teşhis

HMR hatasının kaynağını doğrulamak için tarayıcınızın geliştirici araçlarını kullanmalısınız. İnceleme adımları şunlardır:

• Tarayıcıda F12 tuşuna basarak Geliştirici Araçlarını açın.
• Network (Ağ) sekmesine gelin ve filtreleme kısmından WS (WebSockets) seçeneğini işaretleyin.
• webpack-hmr veya turbopack-hmr isimli bağlantıya tıklayın.
• Messages alt sekmesini inceleyin. Eğer burada kırmız renkte bir kopma veya hiç veri akışı yoksa, proxy veya güvenlik duvarı sorununuz var demektir.

Özellikle ağ paketlerindeki HTTP durum kodlarını ve konsol loglarını inceleme konusunda daha fazla pratik yapmak için Chrome DevTools Kullanım Rehberi: Web Geliştiriciler İçin Hata Ayıklama rehberimizden faydalanabilirsiniz.

4. allowedOrigins ve Port Çakışmalarını Önleme

Farklı bir köken (origin) veya özel bir alan adı üzerinden geliştirme yapıyorsanız Next.js güvenlik gerekçesiyle HMR isteklerini reddedebilir. next.config.mjs içerisinde izin verilen kaynakları tanımlayın:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    allowedOrigins: ['my-dev-domain.test:3000', 'localhost:3000'],
  },
};

export default nextConfig;

Production Öncesi Test ve Canlı Dağıtım Kontrol Listesi

Uygulamanızı canlıya almadan önce aşağıdaki adımları sırasıyla uygulayarak olası hataları önleyebilirsiniz:

• Linter ve Tip Kontrolü: npm run lint ve tsc --noEmit komutlarının hatasız geçtiğinden emin olun.
• Yerel Standalone Testi: Local ortamda npm run build ardından node .next/standalone/server.js komutunu çalıştırarak canlı ortam simülasyonu yapın.
• Önbellek ve Header Ayarları: CDN arkasında çalışıyorsanız statik varlıkların ( assets ) Cache-Control başlıklarını kontrol edin.
• Gereksiz Logların Temizlenmesi: Production derlemesinde console.log ifadelerinin performans etkisini azaltmak için swcMinify ayarlarını yapılandırın.

Sonuç

Next.js projelerinde kararlı bir dağıtım süreci yürütmek ve kesintisiz bir geliştirme ortamı sağlamak, doğru mimari yapılandırmalardan geçer. Standalone Docker imajları ile sunucu kaynaklarınızı optimize ederken, Nginx üzerindeki WebSocket yönlendirmeleri ve doğru watchOptions tanımları ile HMR tıkanıklıklarını tamamen ortadan kaldırabilirsiniz. Next.js dağıtım ve HMR hata ayıklama adımlarını sisteminize entegre ederek hem canlı ortam güvenilirliğini hem de yazılım geliştirme hızınızı üst seviyeye taşıyabilirsiniz.

Sonraki Adım: Mevcut projenizdeki next.config.mjs dosyanıza output: 'standalone' parametresini ekleyin ve Docker derleme boyutunuzdaki düşüşü kendi ortamınızda test edin.