Next.js mit Nginx deployen

Diese Anleitung beschreibt das Deployment einer Next.js Anwendung auf einem Server mit Nginx. Zwei Modi werden behandelt: ein Standard-Node.js-Deployment mit vollem SSR-Support und ein statisches Export-Deployment, bei dem Nginx direkt statische HTML-Dateien ausliefert.

Standard-Deployment mit Node.js

1. Next.js-App bauen

Baue lokal, bevor du die Dateien auf den Server überträgst:

# Zum Projektverzeichnis navigieren
cd your-next-app

# Abhängigkeiten installieren, falls noch nicht geschehen
npm install

# App bauen
npm run build

# Erstellt ein .next-Verzeichnis mit der gebauten App

2. Dateien auf den Server übertragen

# Beispiel mit SCP (vom lokalen Rechner ausführen)
scp -r .next package.json package-lock.json public next.config.js benutzername@server-ip:/pfad/zur/app

3. Abhängigkeiten auf dem Server installieren

Per SSH auf den Server einloggen und Produktionsabhängigkeiten installieren:

cd /pfad/zur/app
npm install --production

4. Nginx als Reverse Proxy einrichten

Nginx installieren, falls noch nicht vorhanden:

sudo apt update
sudo apt install nginx

Eine neue Nginx-Konfigurationsdatei für deine Site erstellen:

sudo nano /etc/nginx/sites-available/nextjs

Diese Konfiguration hinzufügen (Domainnamen und Pfade anpassen):

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

    # Gzip-Komprimierung aktivieren
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_proxied any;
    gzip_vary on;
    gzip_types
        application/javascript
        application/json
        application/x-javascript
        application/xml
        image/svg+xml
        text/css
        text/javascript
        text/plain
        text/xml;

    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;
    }

    # Langzeit-Caching für statische Assets
    location /_next/static/ {
        proxy_pass http://localhost:3000/_next/static/;
        expires 365d;
        access_log off;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }

    location /public/ {
        proxy_pass http://localhost:3000/public/;
        expires 365d;
        access_log off;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}

Site aktivieren, Konfiguration testen und Nginx neu starten:

sudo ln -s /etc/nginx/sites-available/nextjs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

5. Next.js-Server mit PM2 ausführen

PM2 verwaltet den Node.js-Prozess und startet ihn bei Server-Neustart automatisch neu:

# PM2 global installieren
sudo npm install -g pm2

# Next.js-App starten
cd /pfad/zur/app
pm2 start npm --name "next-app" -- start

# Beim Neustart persistent halten
pm2 startup
pm2 save

6. SSL mit Certbot einrichten

Certbot installieren und Let’s Encrypt-Zertifikat erhalten:

# Certbot installieren
sudo apt install certbot python3-certbot-nginx

# Zertifikate erhalten und installieren
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

# Automatische Erneuerung prüfen
sudo systemctl status certbot.timer

Certbot passt deine Nginx-Konfiguration automatisch für SSL an.

---

Statisches Export-Deployment

Verwende diese Methode, wenn du kein SSR, keine API-Routen oder Middleware benötigst.

1. App für statischen Export konfigurieren

output-Einstellung in next.config.js hinzufügen:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
}

module.exports = nextConfig

2. App bauen

npm run build

Erstellt ein out-Verzeichnis mit fertig auslieferbaren statischen Dateien.

3. Nginx installieren

sudo apt update
sudo apt install nginx

4. Gebaute Dateien auf den Server übertragen

# Vom lokalen Rechner
scp -r ./out/* benutzername@server-ip:/var/www/yourdomain.com/html/

Verzeichnis anlegen und Berechtigungen auf dem Server setzen:

sudo mkdir -p /var/www/yourdomain.com/html
sudo chown -R $USER:$USER /var/www/yourdomain.com/html
sudo chmod -R 755 /var/www/yourdomain.com

5. Nginx-Server-Block konfigurieren

sudo nano /etc/nginx/sites-available/yourdomain.com

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/yourdomain.com/html;
    index index.html;

    # Gzip-Komprimierung aktivieren
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_proxied any;
    gzip_vary on;
    gzip_types
        application/javascript
        application/json
        application/x-javascript
        application/xml
        image/svg+xml
        text/css
        text/javascript
        text/plain
        text/xml;

    # Langzeit-Caching für statische Assets
    location /_next/static/ {
        expires 365d;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }

    location / {
        try_files $uri $uri.html $uri/ =404;
    }

    # Eigene 404-Seite
    error_page 404 /404.html;
}

6. Site aktivieren und Nginx neu starten

sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

7. SSL einrichten

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

---

Wichtige Hinweise

• Auf dem Server muss Node.js installiert sein. Die Mindestversion hängt von der genutzten Next.js-Version ab – aktuelle Anforderungen in den offiziellen Next.js-Dokumenten prüfen (nur für Standard-Deployment).
• Statischer Export unterstützt kein SSR, keine API-Routen, Server Actions oder Middleware.
• Korrekte Dateiberechtigungen setzen, damit Nginx die statischen Dateien lesen kann.
• In der Produktion immer HTTPS verwenden und Logging sowie Monitoring einrichten.

Häufig gestellte Fragen

Ist Nginx besser als Apache für Next.js?

Nginx wird für Next.js-Deployments oft bevorzugt, da es statische Assets effizient ausliefert, weniger Arbeitsspeicher verbraucht und unter hoher Last besser performt. Es eignet sich besonders gut als Reverse Proxy und für die Auslieferung statischer Inhalte.

Wie funktioniert clientseitiges Routing beim statischen Export?

Füge einen location-Block in die Nginx-Konfiguration ein, der Anfragen auf die passende HTML-Datei umleitet. Da das clientseitige Routing von Next.js erwartet, dass der Server für alle Routen die index.html ausliefert, ist dies erforderlich.

Wie verwalte ich Umgebungsvariablen?

Bei SSR-Deployments werden Umgebungsvariablen direkt auf dem Server gesetzt. Beim statischen Export müssen clientseitig genutzte Variablen mit NEXT_PUBLIC_ prefixed und zur Build-Zeit verfügbar sein – sie werden in die JavaScript-Bundles eingebettet.

Wie aktualisiere ich das Deployment nach Code-Änderungen?

Beim Standard-Deployment: aktuellen Code pullen, neu bauen und den PM2-Prozess neu starten. Beim statischen Export: lokal neu bauen, das neue out-Verzeichnis auf den Server kopieren – kein Nginx-Neustart erforderlich.