Fehlerbehebung und Optimierung von Next.js 15+ Server Actions auf Cloudflare OpenNext/Workers

Next.js 15 und Server Actions haben massive Veränderungen im React-Ökosystem mit sich gebracht. Wenn man sie jedoch in einer Edge-Umgebung wie Cloudflare Workers statt in Vercel ausführt, stößt man auf mehrere technische Hürden. Glücklicherweise ist die Bereitstellung von Next.js-Apps in Cloudflare dank OpenNext viel einfacher geworden.

Dieser Beitrag beschreibt Fehlerbehebungspunkte und Methoden zur Leistungsoptimierung, auf die Sie stoßen könnten, wenn Sie Server Actions in einer Umgebung ab Next.js 15 auf Cloudflare OpenNext/Workers bereitstellen.

1. Die Architektur von OpenNext und Cloudflare Workers verstehen

Während Vercel eine Node.js-Umgebung (oder eine eigene Edge-Laufzeit) bereitstellt, verwenden Cloudflare Workers eine einzigartige Laufzeit, die auf V8-Isolaten basiert. Folglich kann Code, der direkt auf integrierte Node.js-Module angewiesen ist (z. B. fs, path, crypto), Fehler verursachen.

OpenNext wandelt die Next.js-Build-Ausgabe in ein Format um, das Cloudflare Workers verstehen können (über einen Adapter). Bei Server Actions kommt es jedoch während des Parsens von Formulardaten und der Rückgabe von Ausführungsergebnissen vom Server häufig zu subtilen Fehlern, die durch Laufzeitunterschiede verursacht werden.

2. Häufige Bereitstellungsfehler und Lösungen für Server Actions

2-1. FormData Parsing-Fehler (Multipart/form-data)

Bei der Verarbeitung von Datei-Uploads in Server Actions treten häufig Parsing-Fehler bei multipart/form-data auf. Sie könnten an das Speicherlimit von Cloudflare Workers (128 MB) und das Limit für die Anforderungsgröße (normalerweise 100 MB) stoßen.

Lösung: Anstatt große Datei-Uploads direkt über Server Actions zu senden, sollten Sie eine Presigned URL von Cloudflare R2 ausgeben und direkt vom Client hochladen (Direct Upload).

// app/actions.ts
'use server'

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3 = new S3Client({
  region: "auto",
  endpoint: process.env.R2_ENDPOINT,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  },
});

export async function getUploadUrl(filename: string, contentType: string) {
  const command = new PutObjectCommand({
    Bucket: process.env.R2_BUCKET_NAME,
    Key: filename,
    ContentType: contentType,
  });

  // Erstellen einer URL, die am Edge 60 Sekunden lang gültig ist
  const signedUrl = await getSignedUrl(s3, command, { expiresIn: 60 });
  return signedUrl;
}

2-2. Node.js-Abhängigkeitsfehler (Bcrypt usw.)

Die Verwendung nativer Node.js-Bindungsbibliotheken wie bcrypt zur Benutzerauthentifizierung in Server Actions führt zu einem Absturz in der Workers-Umgebung.

Lösung: Sie sollten Web-Crypto-API-unterstützte Bibliotheken wie bcryptjs (eine reine JS-Implementierung), die WASM-Version von @node-rs/argon2 oder cf-workers-hash verwenden.

2-3. Erschöpfung des Datenbank-Verbindungspools

Server Actions werden pro Anforderung ausgeführt. Wenn Sie sich direkt (TCP) mit Datenbanken wie PostgreSQL verbinden, können Ihre Verbindungen schnell erschöpft sein.

Lösung: Verwenden Sie Cloudflare Hyperdrive, um das Verbindungspooling zu verwalten, oder verwenden Sie einen HTTP-basierten Datenbankdienst (z. B. Prisma Accelerate, Neon Serverless, Supabase REST).

3. Tipps zur Leistungsoptimierung

3-1. Die Edge-Laufzeit explizit deklarieren

Wenn eine Server Action an eine bestimmte Route gebunden ist, verbessert die explizite Deklaration der Edge-Laufzeit für diese Route die Leistung. OpenNext handhabt dies effizienter.

export const runtime = 'edge';

3-2. Cache-Invalidierung mit Revalidate

Wenn Sie revalidatePath oder revalidateTag nach Abschluss einer Server Action verwenden, müssen Sie verstehen, wie das KV-basierte Caching von OpenNext funktioniert. Cloudflare KV verfügt über eine Eventual Consistency, sodass sich Aktualisierungen um bis zu 60 Sekunden verzögern können.

Wenn Sie eine sofortige Cache-Invalidierung benötigen, sollten Sie in Betracht ziehen, Cloudflare D1 oder ein externes Redis (wie Upstash) als benutzerdefinierten Cache-Handler von Next.js anstelle von Workers KV zu konfigurieren.

Zusammenfassung

💡 Kern-Checkliste für Server Actions auf Cloudflare

• Verwenden Sie für große Dateien R2 Presigned URLs für direkte Client-Uploads anstelle von Server Actions.
• Vermeiden Sie native Node.js-APIs (fs, C++ Addons) und ersetzen Sie diese durch Web-APIs oder reine JS-Pakete.
• Nutzen Sie beim Herstellen einer Verbindung zu Datenbanken Hyperdrive oder HTTP-basierte Serverless DBs.
• Beachten Sie beim Entwerfen mit revalidatePath die Eventual Consistency von Cloudflare Cache/KV.

Die Kombination aus OpenNext und Cloudflare Workers ist eine fantastische Infrastruktur, um das Next.js-Ökosystem weltweit zu den niedrigsten Kosten und mit höchster Geschwindigkeit bereitzustellen. Solange Sie mit ein paar kleinen anfänglichen Konfigurationen vorsichtig sind, können Sie die Vorteile leistungsstarker Server Actions direkt am Edge in vollem Umfang genießen.