logoNext.js
DokumentationBlogLernen
Einführung/Anwendung erstellen/Datenabruf/Server Actions und Mutationen

Server Actions und Mutationen

Server Actions sind asynchrone Funktionen, die auf dem Server ausgeführt werden. Sie können in Server- und Client-Komponenten aufgerufen werden, um Formularübermittlungen und Datenmutationen in Next.js-Anwendungen zu verarbeiten.

🎥 Video: Mehr über Mutationen mit Server Actions erfahren → YouTube (10 Minuten).

Konvention

Eine Server Action kann mit der React "use server"-Direktive definiert werden. Sie können die Direktive entweder am Anfang einer async-Funktion platzieren, um die Funktion als Server Action zu markieren, oder am Anfang einer separaten Datei, um alle Exporte dieser Datei als Server Actions zu kennzeichnen.

Server-Komponenten

Server-Komponenten können die "use server"-Direktive auf Funktions- oder Modulebene verwenden. Um eine Server Action inline zu definieren, fügen Sie "use server" am Anfang des Funktionskörpers hinzu:

export default function Page() {
  // Server Action
  async function create() {
    'use server'
    // Daten mutieren
  }

  return '...'
}

Client-Komponenten

Um eine Server-Funktion in einer Client-Komponente aufzurufen, erstellen Sie eine neue Datei und fügen die "use server"-Direktive am Anfang hinzu. Alle exportierten Funktionen innerhalb der Datei werden als Server-Funktionen markiert, die sowohl in Client- als auch Server-Komponenten wiederverwendet werden können:

'use server'

export async function create() {}

Aktionen als Props übergeben

Sie können eine Server Action auch als Prop an eine Client-Komponente übergeben:

<ClientComponent updateItemAction={updateItem} />
'use client'

export default function ClientComponent({
  updateItemAction,
}: {
  updateItemAction: (formData: FormData) => void
}) {
  return <form action={updateItemAction}>{/* ... */}</form>
}

Normalerweise würde das Next.js TypeScript-Plugin updateItemAction in client-component.tsx markieren, da es sich um eine Funktion handelt, die im Allgemeinen nicht über Client-Server-Grenzen hinweg serialisiert werden kann. Allerdings wird bei Props mit dem Namen action oder solchen, die mit Action enden, angenommen, dass sie Server Actions erhalten. Dies ist nur eine Heuristik, da das TypeScript-Plugin nicht tatsächlich weiß, ob es eine Server Action oder eine gewöhnliche Funktion erhält. Laufzeit-Typüberprüfungen stellen dennoch sicher, dass Sie nicht versehentlich eine Funktion an eine Client-Komponente übergeben.

Verhalten

  • Server Actions können mit dem action-Attribut in einem <form>-Element aufgerufen werden.
    • Server-Komponenten unterstützen standardmäßig progressive Verbesserung, was bedeutet, dass das Formular auch dann übermittelt wird, wenn JavaScript noch nicht geladen oder deaktiviert ist.
    • In Client-Komponenten werden Formulare, die Server Actions aufrufen, in eine Warteschlange gestellt, wenn JavaScript noch nicht geladen ist, wobei die Client-Hydration priorisiert wird.
    • Nach der Hydration wird der Browser bei der Formularübermittlung nicht aktualisiert.
  • Server Actions sind nicht auf <form> beschränkt und können von Event-Handlern, useEffect, Bibliotheken von Drittanbietern und anderen Formularelementen wie <button> aufgerufen werden.
  • Server Actions sind in die Caching- und Revalidierungsarchitektur von Next.js integriert. Wenn eine Aktion aufgerufen wird, kann Next.js sowohl die aktualisierte Benutzeroberfläche als auch neue Daten in einem einzigen Server-Roundtrip zurückgeben.
  • Im Hintergrund verwenden Actions die POST-Methode, und nur diese HTTP-Methode kann sie aufrufen.
  • Die Argumente und Rückgabewerte von Server Actions müssen von React serialisierbar sein. Siehe die React-Dokumentation für eine Liste der serialisierbaren Argumente und Werte.
  • Server Actions sind Funktionen. Das bedeutet, dass sie überall in Ihrer Anwendung wiederverwendet werden können.
  • Server Actions übernehmen die Laufzeitumgebung von der Seite oder dem Layout, in dem sie verwendet werden.
  • Server Actions übernehmen die Route Segment Config von der Seite oder dem Layout, in dem sie verwendet werden, einschließlich Feldern wie maxDuration.

Beispiele

Event-Handler

Während es üblich ist, Server Actions innerhalb von <form>-Elementen zu verwenden, können sie auch mit Event-Handlern wie onClick aufgerufen werden. Zum Beispiel, um einen Like-Zähler zu erhöhen:

'use client'

import { incrementLike } from './actions'
import { useState } from 'react'

export default function LikeButton({ initialLikes }: { initialLikes: number }) {
  const [likes, setLikes] = useState(initialLikes)

  return (
    <>
      <p>Total Likes: {likes}</p>
      <button
        onClick={async () => {
          const updatedLikes = await incrementLike()
          setLikes(updatedLikes)
        }}
      >
        Like
      </button>
    </>
  )
}

Sie können auch Event-Handler zu Formularelementen hinzufügen, zum Beispiel, um ein Formularfeld bei onChange zu speichern:

app/ui/edit-post.tsx
'use client'

import { publishPost, saveDraft } from './actions'

export default function EditPost() {
  return (
    <form action={publishPost}>
      <textarea
        name="content"
        onChange={async (e) => {
          await saveDraft(e.target.value)
        }}
      />
      <button type="submit">Publish</button>
    </form>
  )
}

Für solche Fälle, in denen mehrere Ereignisse in schneller Folge ausgelöst werden können, empfehlen wir Debouncing, um unnötige Server-Action-Aufrufe zu vermeiden.

useEffect

Sie können den React useEffect-Hook verwenden, um eine Server Action beim Mounten der Komponente oder bei einer Änderung der Abhängigkeiten aufzurufen. Dies ist nützlich für Mutationen, die von globalen Ereignissen abhängen oder automatisch ausgelöst werden müssen. Zum Beispiel onKeyDown für App-Shortcuts, ein Intersection Observer Hook für unendliches Scrollen oder beim Mounten der Komponente, um eine Aufrufzählung zu aktualisieren:

'use client'

import { incrementViews } from './actions'
import { useState, useEffect, useTransition } from 'react'

export default function ViewCount({ initialViews }: { initialViews: number }) {
  const [views, setViews] = useState(initialViews)
  const [isPending, startTransition] = useTransition()

  useEffect(() => {
    startTransition(async () => {
      const updatedViews = await incrementViews()
      setViews(updatedViews)
    })
  }, [])

  // Sie können `isPending` verwenden, um Benutzern Feedback zu geben
  return <p>Total Views: {views}</p>
}

Denken Sie daran, die Verhaltensweisen und Einschränkungen von useEffect zu berücksichtigen.

Fehlerbehandlung

Wenn ein Fehler auftritt, wird er von der nächsten error.js oder <Suspense>-Grenze auf dem Client abgefangen. Weitere Informationen finden Sie unter Fehlerbehandlung.

Gut zu wissen:

  • Neben dem Auslösen des Fehlers können Sie auch ein Objekt zurückgeben, das von useActionState verarbeitet wird.

Datenrevalidierung

Sie können den Next.js Cache innerhalb Ihrer Server Actions mit der revalidatePath-API revalidieren:

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost() {
  try {
    // ...
  } catch (error) {
    // ...
  }

  revalidatePath('/posts')
}

Oder Sie können einen bestimmten Datenabruf mit einem Cache-Tag über revalidateTag invalidieren:

'use server'

import { revalidateTag } from 'next/cache'

export async function createPost() {
  try {
    // ...
  } catch (error) {
    // ...
  }

  revalidateTag('posts')
}

Umleitung

Wenn Sie den Benutzer nach Abschluss einer Server Action zu einer anderen Route weiterleiten möchten, können Sie die redirect-API verwenden. redirect muss außerhalb des try/catch-Blocks aufgerufen werden:

'use server'

import { redirect } from 'next/navigation'
import { revalidateTag } from 'next/cache'

export async function createPost(id: string) {
  try {
    // ...
  } catch (error) {
    // ...
  }

  revalidateTag('posts') // Zwischengespeicherte Beiträge aktualisieren
  redirect(`/post/${id}`) // Zur neuen Beitragsseite navigieren
}

Cookies

Sie können Cookies innerhalb einer Server Action mit der cookies-API get, set und delete:

'use server'

import { cookies } from 'next/headers'

export async function exampleAction() {
  const cookieStore = await cookies()

  // Cookie abrufen
  cookieStore.get('name')?.value

  // Cookie setzen
  cookieStore.set('name', 'Delba')

  // Cookie löschen
  cookieStore.delete('name')
}

Weitere Beispiele finden Sie unter Cookies löschen.

Sicherheit

Standardmäßig erstellt eine Server Action, wenn sie erstellt und exportiert wird, einen öffentlichen HTTP-Endpunkt und sollte mit den gleichen Sicherheitsannahmen und Autorisierungsprüfungen behandelt werden. Das bedeutet, selbst wenn eine Server Action oder Hilfsfunktion nicht anderswo in Ihrem Code importiert wird, ist sie dennoch öffentlich zugänglich.

Um die Sicherheit zu verbessern, bietet Next.js die folgenden integrierten Funktionen:

  • Sichere Action-IDs: Next.js erstellt verschlüsselte, nicht-deterministische IDs, die es dem Client ermöglichen, auf die Server Action zu verweisen und sie aufzurufen. Diese IDs werden zwischen Builds periodisch neu berechnet, um die Sicherheit zu erhöhen.
  • Dead-Code-Eliminierung: Nicht verwendete Server Actions (referenziert durch ihre IDs) werden aus dem Client-Bundle entfernt, um den öffentlichen Zugriff durch Dritte zu vermeiden.

Gut zu wissen:

Die IDs werden während der Kompilierung erstellt und für maximal 14 Tage zwischengespeichert. Sie werden neu generiert, wenn ein neuer Build initiiert wird oder der Build-Cache ungültig wird. Diese Sicherheitsverbesserung reduziert das Risiko in Fällen, in denen eine Authentifizierungsschicht fehlt. Dennoch sollten Sie Server Actions wie öffentliche HTTP-Endpunkte behandeln.

// app/actions.js
'use server'

// Diese Aktion **wird** in unserer Anwendung verwendet, daher erstellt Next.js
// eine sichere ID, damit der Client auf die Server Action verweisen
// und sie aufrufen kann.
export async function updateUserAction(formData) {}

// Diese Aktion **wird nicht** in unserer Anwendung verwendet, daher entfernt Next.js
// diesen Code automatisch während `next build`
// und erstellt keinen öffentlichen Endpunkt.
export async function deleteUserAction(formData) {}

Authentifizierung und Autorisierung

Sie sollten sicherstellen, dass der Benutzer berechtigt ist, die Aktion auszuführen. Zum Beispiel:

app/actions.ts
'use server'

import { auth } from './lib'

export function addItem() {
  const { user } = auth()
  if (!user) {
    throw new Error('Sie müssen angemeldet sein, um diese Aktion auszuführen')
  }

  // ...
}

Closures und Verschlüsselung

Das Definieren einer Server Action innerhalb einer Komponente erstellt einen Closure, in dem die Aktion Zugriff auf den Scope der äußeren Funktion hat. Zum Beispiel hat die publish-Aktion Zugriff auf die publishVersion-Variable:

export default async function Page() {
  const publishVersion = await getLatestVersion();

  async function publish() {
    "use server";
    if (publishVersion !== await getLatestVersion()) {
      throw new Error('Die Version hat sich seit dem Drücken von "Publish" geändert');
    }
    ...
  }

  return (
    <form>
      <button formAction={publish}>Publish</button>
    </form>
  );
}

Closures sind nützlich, wenn Sie eine Momentaufnahme von Daten (z.B. publishVersion) zum Zeitpunkt des Renderings erfassen müssen, damit sie später verwendet werden können, wenn die Aktion aufgerufen wird.

Damit dies funktioniert, werden die erfassten Variablen jedoch an den Client und zurück zum Server gesendet, wenn die Aktion aufgerufen wird. Um zu verhindern, dass sensible Daten dem Client zugänglich gemacht werden, verschlüsselt Next.js die eingeschlossenen Variablen automatisch. Für jede Aktion wird bei jedem Build einer Next.js-Anwendung ein neuer privater Schlüssel generiert. Das bedeutet, dass Aktionen nur für einen bestimmten Build aufgerufen werden können.

Gut zu wissen: Wir empfehlen nicht, sich allein auf die Verschlüsselung zu verlassen, um zu verhindern, dass sensible Werte dem Client zugänglich gemacht werden. Stattdessen sollten Sie die React taint APIs verwenden, um proaktiv zu verhindern, dass bestimmte Daten an den Client gesendet werden.

Überschreiben von Verschlüsselungsschlüsseln (Fortgeschrittene)

Wenn Sie Ihre Next.js-Anwendung selbst auf mehreren Servern hosten, kann jede Serverinstanz einen unterschiedlichen Verschlüsselungsschlüssel erhalten, was zu potenziellen Inkonsistenzen führen kann.

Um dies zu vermeiden, können Sie den Verschlüsselungsschlüssel mit der Umgebungsvariable process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY überschreiben. Durch die Angabe dieser Variable wird sichergestellt, dass Ihre Verschlüsselungsschlüssel über Builds hinweg konsistent bleiben und alle Serverinstanzen denselben Schlüssel verwenden. Diese Variable muss mit AES-GCM verschlüsselt sein.

Dies ist ein fortgeschrittener Anwendungsfall, bei dem ein einheitliches Verschlüsselungsverhalten über mehrere Bereitstellungen hinweg für Ihre Anwendung entscheidend ist. Sie sollten Standard-Sicherheitspraktiken wie Schlüsselrotation und Signierung berücksichtigen.

Gut zu wissen: Next.js-Anwendungen, die auf Vercel bereitgestellt werden, handhaben dies automatisch.

Erlaubte Ursprünge (Fortgeschrittene)

Da Server-Aktionen (Server Actions) in einem <form>-Element aufgerufen werden können, sind sie anfällig für CSRF-Angriffe.

Im Hintergrund verwenden Server-Aktionen die POST-Methode, und nur diese HTTP-Methode ist für ihren Aufruf erlaubt. Dies verhindert die meisten CSRF-Schwachstellen in modernen Browsern, insbesondere da SameSite-Cookies standardmäßig aktiviert sind.

Als zusätzlichen Schutz vergleichen Server-Aktionen in Next.js auch den Origin-Header mit dem Host-Header (oder X-Forwarded-Host). Wenn diese nicht übereinstimmen, wird die Anfrage abgebrochen. Mit anderen Worten: Server-Aktionen können nur auf demselben Host aufgerufen werden, auf dem die sie enthaltende Seite gehostet wird.

Für große Anwendungen, die Reverse-Proxies oder mehrschichtige Backend-Architekturen verwenden (bei denen sich die Server-API von der Produktionsdomäne unterscheidet), wird empfohlen, die Konfigurationsoption serverActions.allowedOrigins zu verwenden, um eine Liste sicherer Ursprünge anzugeben. Die Option akzeptiert ein Array von Strings.

next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
    },
  },
}

Erfahren Sie mehr über Sicherheit und Server-Aktionen.

Zusätzliche Ressourcen

Weitere Informationen finden Sie in den folgenden React-Dokumenten:

serverActions

Konfigurieren Sie das Verhalten von Server-Aktionen (Server Actions) in Ihrer Next.js-Anwendung.

Datenabruf

Erfahren Sie, wie Sie mit Next.js Daten abrufen, zwischenspeichern, erneut validieren und verändern können.

Deep Dive

Erfahren Sie, wie Next.js unter der Haube funktioniert.

On this page