Next.js auf Vercel deployen: Umgebungsvariablen, Domains und Performance-Monitoring

Die 500-Fehlerseite von Vercel im Browser. Die Umgebungsvariablen stehen im Vercel-Dashboard – und trotzdem liefert die API undefined? .env.local dreimal geprüft, zweimal neu deployt, Browser-Cache geleert – nichts hilft.

Eine halbe Stunde später lag das Problem am Präfix NEXT_PUBLIC_.

Kennen Sie das? Lokal läuft das Next.js-Projekt perfekt, auf Vercel wird alles merkwürdig: Env-Vars greifen nicht, die eigene Domain liefert stundenlang 404, SSL-Probleme mit Endlosschleifen.

Der Vercel-Workflow ist einfach – aber „einfach“ heißt nicht „ohne Fallen“. Dieser Artikel führt Sie durch das komplette Next.js-Deployment auf Vercel: One-Click-Deploy, korrekte Umgebungsvariablen, Domain-Bindung und Performance-Monitoring – inklusive der Stolpersteine, die die Doku selten nennt.

Basis-Deployment (in 5 Minuten live)

One-Click-Deploy richtig machen

Vercel ist schlank: Code auf GitHub, Projekt verbinden, ein paar Klicks – fertig. Hinter der Einfachheit stecken aber Details.

Ihr Next.js-Projekt muss in einem Git-Repo liegen (GitHub, GitLab oder Bitbucket). Öffnen Sie vercel.com, melden Sie sich mit GitHub an und klicken Sie auf „Import Project“.

Vercel scannt das Repository, erkennt Next.js und setzt Build-Befehl sowie Output-Verzeichnis automatisch:

Build Command: next build
Output Directory: .next
Install Command: npm install

Auf „Deploy“ klicken, ein bis zwei Minuten warten – Sie erhalten eine URL your-project.vercel.app. Statische Assets (JS, CSS, Bilder) landen im Edge Network – globales CDN, ohne Extra-Konfiguration.

Ein Detail, das Anfänger übersehen: Prüfen Sie package.json.

Steht im build-Skript nicht next build, oder fehlen next, react, react-dom, scheitert das Deployment. Manche setzen webpack als Build – Vercel findet dann kein Next.js.

Außerdem der DPS-Workflow – Develop, Preview, Ship:

• Develop: lokal mit npm run dev
• Preview: Pull Request oder Push auf Nicht-Main-Branch → Vercel erzeugt eine Preview-URL
• Ship: Merge auf main → automatisches Production-Deploy

Praktisch: Feature-Branch, PR, Link your-project-git-feature-branch.vercel.app an QA oder Produkt – ohne die Live-Umgebung zu berühren.

Nach dem Deploy: Build-Logs prüfen

Vor dem Feiern: Vercel Dashboard → Projekt → „Deployments“ → neuestes Deployment öffnen.

Die Build-Logs zeigen:

1. Dauer der Dependency-Installation – über eine Minute deutet auf großes node_modules oder langsames Netz
2. Warnungen beim Build – TypeScript, ESLint
3. Anzahl statischer Seiten – welche Seiten SSG, welche SSR

Beim ersten Deploy schwebten TypeScript-Fehler in den Logs – das Deployment ging trotzdem durch. Vercel blockiert standardmäßig nicht wegen TypeScript – außer Sie setzen in next.config.js typescript.ignoreBuildErrors: false.

Build erfolgreich ≠ Seite erreichbar.

Deployment grün, Seite 500 – klassisch: API-Route nutzt Node-fs für lokale Dateien. Edge Functions haben kein Dateisystem. Serverless Functions auf Vercel sind pro Request isoliert; persistente Dateien gibt es nicht.

Umgebungsvariablen (die häufigste Stolperfalle)

Drei Umgebungsebenen

Env-Vars auf Vercel sind verwirrend – hier die Struktur.

Vercel unterscheidet Production, Preview und Development:

• Production: Live für Nutzer, typisch main
• Preview: PR oder andere Branches → Test-URL
• Development: lokal mit npm run dev

Pro Ebene andere Werte möglich – z. B. echte DB in Production, Test-DB in Preview, lokale DB in Development.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Lokal:

Im Projektroot .env.local oder .env.development:

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here

.env.local gehört in .gitignore, damit Keys nicht ins Repo gelangen.

Auf Vercel:

Dashboard → Projekt → Settings → Environment Variables.

Drei Checkboxen: Production, Preview, Development – nur angehakte Umgebungen erhalten die Variable.

Beispiel nur für Production:

Name: DATABASE_URL
Value: postgresql://prod-server:5432/prod-db
Environment: ✅ Production

Speichern, neu deployen – erst dann sind die Werte aktiv.

Stolperfalle: Nach Änderung an Env-Vars ohne Redeploy bleiben alte Werte aktiv. Push oder manuelles Redeploy nötig.

Client vs. Server

Der kniffligste Teil – ein Klassiker um drei Uhr morgens.

Zwei Arten in Next.js:

1. Server: nur in API-Routen, getServerSideProps, getStaticProps
2. Client: Präfix NEXT_PUBLIC_ – wird in den Browser-JS-Bundle eingebettet

# Server (sicher)
DATABASE_URL=postgresql://...
API_SECRET_KEY=abc123

# Client (sichtbar im Browser)
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Site

DATABASE_URL und API_SECRET_KEY erreichen den Browser nicht. NEXT_PUBLIC_* steht im kompilierten JS – in den DevTools für jeden sichtbar.

Typischer Fehler: API-Key soll im Client eine Third-Party-API aufrufen. Ohne NEXT_PUBLIC_ → undefined im Browser. Mit Präfix funktioniert es – und der Key liegt offen in DevTools unter NEXT_PUBLIC_.

Richtig: Keine Secrets im Client. Request über eigene API-Route:

// app/api/data/route.ts (Server)
export async function GET() {
  const res = await fetch('https://api.example.com', {
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET_KEY}` // sicher
    }
  })
  return res.json()
}

// app/page.tsx (Client)
const data = await fetch('/api/data') // eigene API, kein Key im Browser

Der Key bleibt serverseitig.

Wichtig: NEXT_PUBLIC_-Variablen werden beim Build eingebettet, nicht zur Laufzeit. Änderung erfordert neuen Build.

Env-Vars im Team synchronisieren

.env.local darf nicht ins Git – neue Kolleg:innen wissen nicht, welche Variablen nötig sind.

Vercel CLI:

vercel env pull .env.local

Lädt Development-Variablen von Vercel in .env.local.

Voraussetzung:

npm i -g vercel
vercel link  # Projekt verknüpfen
vercel env pull

Nur Development wird gezogen – Production/Preview aus Sicherheitsgründen nicht.

.env.example als Vorlage:

# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_API_BASE_URL=

Ins Repo committen; lokal kopieren nach .env.local und Werte eintragen.

Gesamtlimit Env-Vars auf Vercel: 64 KB; einzelne Edge-Variable max. 5 KB. JWT-Keys oder base64-Bilder können das Limit treffen.

Eigene Domain

Domain in drei Schritten

your-project.vercel.app wirkt unprofessionell; *.vercel.app ist in manchen Regionen problematisch. Eigene Domain ist für viele Nutzer Pflicht.

Schritt 1: Domain in Vercel

Dashboard → Projekt → Settings → Domains → „Add“ → z. B. example.com oder blog.example.com.

Vercel zeigt die benötigten DNS-Einträge.

Schritt 2: DNS

Root-Domain (example.com):

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Type: A
Name: @
Value: 76.76.21.21

Subdomain (blog.example.com):

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

Nutzer in China:

cname-china.vercel-dns.com statt cname.vercel-dns.com:

Type: CNAME
Name: blog
Value: cname-china.vercel-dns.com

Oder A-Record:

Type: A
Name: @
Value: 76.223.126.88 oder 76.76.21.98

Nach DNS-Änderung Minuten bis Stunden warten – Vercel erkennt die Aktivierung.

Schritt 3: Verifizieren

Dashboard aktualisieren – grünes „Valid Configuration“ bedeutet Erfolg. Domain im Browser öffnen.

Stolpersteine: CNAME-Name als vollständiger Host (blog.example.com statt blog). Falscher A-Record-IP oder DNS-Cache → lange 404.

SSL automatisch

Vercel beantragt Let’s-Encrypt-Zertifikate automatisch – HTTPS ohne Extra-Schritte.

Nach DNS: Status „Certificate Status: Provisioning“, dann „Active“. https://example.com zeigt das Schloss.

Fallgrube: Zertifikat passt nicht → Redirect-Schleife.

Root und www gleichzeitig, aber DNS oder SSL nur für eine Variante – Browser springt zwischen http://example.com und https://www.example.com.

Lösung: Beide Domains in Vercel, DNS für beide korrekt. Bei manchen DNS-Anbietern SSL/TLS auf „Full (strict)“ statt „Flexible“.

SSL prüfen:

Browser → Schloss → Zertifikat („Issued by: Let’s Encrypt“).

curl -I https://example.com

Status 200? Header Strict-Transport-Security (HSTS)?

Subdomains und mehrere Domains

www und Root: Beide in Domains hinzufügen; in Settings „Primary Domain“ wählen – die andere leitet um.

i18n: Subdomains pro Sprache:

• en.example.com → Englisch
• zh.example.com → Chinesisch
• ja.example.com → Japanisch

In next.config.js:

module.exports = {
  i18n: {
    locales: ['en', 'zh', 'ja'],
    defaultLocale: 'en',
    domains: [
      { domain: 'en.example.com', defaultLocale: 'en' },
      { domain: 'zh.example.com', defaultLocale: 'zh' },
      { domain: 'ja.example.com', defaultLocale: 'ja' },
    ],
  },
}

Preview mit eigener Domain: z. B. staging.example.com mit Git Branch staging – jeder Push auf staging deployt dorthin, Production bleibt unberührt.

Performance-Monitoring und Optimierung

Vercel Analytics und Speed Insights

Nach dem Go-Live: Wie schnell lädt die Seite? Wo hakt es?

Zwei kostenlose Tools: Analytics (Verhalten) und Speed Insights (Performance).

Speed Insights einbinden (App Router, Next.js 13+):

npm install @vercel/speed-insights

Im Root-Layout:

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  )
}

Nach Deploy sammelt der Tab „Speed Insights“ Real-User-Daten.

Core Web Vitals

Automatisch erfasst:

1. FCP (First Contentful Paint) – ideal < 1,8 s
2. LCP (Largest Contentful Paint) – ideal < 2,5 s
3. CLS (Cumulative Layout Shift) – ideal < 0,1

Daten aus echten Browsern (RUM), nicht nur Lab – nach Region, Gerät und Browser.

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Optimierung anhand der Daten

Beispiel: LCP dauerhaft ~4 s. Ursache: 2-MB-PNG im Hero, ohne next/image.

WebP + next/image → LCP ~1,8 s, Score von 60 auf 95.

Lab-Scores täuschen; RUM zeigt, was Nutzer spüren.

Analytics

Seitenaufrufe, Referrer, Regionen, Absprungrate. Für Personal-Projects kostenlos bis 100.000 Views/Monat; kommerziell kostenpflichtig.

Erweiterte Einstellungen

Eigener Build-Befehl

Settings → Build & Development Settings – z. B. mit pnpm:

Build Command: pnpm build
Install Command: pnpm install

Oder Pre-Build:

Build Command: npm run prebuild && npm run build

Edge Functions und Edge Middleware

Code läuft an Edge-Knoten – oft schneller als klassische Serverless Functions. Next.js-Middleware wird als Edge Middleware deployed – Auth, Redirects, A/B-Tests am Edge.

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request) {
  if (!request.cookies.get('token')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

Serverless-Timeout

Standard 10 s (Free). Lange API-Jobs → Upgrade (bis 60 s) oder Queue (Inngest, Trigger.dev).

Deployment Protection

Settings → Deployment Protection → Passwort für Previews – sinnvoll für unveröffentlichte Features oder sensible Daten.

Zusammenfassung

Sie kennen jetzt den Ablauf: One-Click-Deploy, drei Env-Ebenen, Domain und SSL, Monitoring und Extras.

Env-Vars: Server ohne Präfix, Client mit NEXT_PUBLIC_, API-Keys nie im Client – diese Lektion haben wir schon gelernt.

Domains: DNS-Details zählen; für China cname-china.vercel-dns.com oder 76.76.21.21.

Monitoring: Speed Insights mit RUM; LCP > 2,5 s → Bilder, Fonts, First Paint prüfen – oft +30 Punkte mit einer Änderung.

Pushen Sie Ihr erstes Projekt auf GitHub, verbinden Sie Vercel – der Moment, wenn das Deployment durchläuft, rechtfertigt die Lesezeit.

Fragen gerne in den Kommentaren. Gutes Deployment!