middleware.js

Die Datei middleware.js|ts wird verwendet, um Middleware zu schreiben und Code auf dem Server auszuführen, bevor eine Anfrage abgeschlossen wird. Basierend auf der eingehenden Anfrage können Sie die Antwort durch Umschreiben, Weiterleiten, Ändern der Anfrage- oder Antwort-Header oder direkte Antworten modifizieren.

Middleware wird ausgeführt, bevor Routen gerendert werden. Sie ist besonders nützlich für die Implementierung von benutzerdefinierter serverseitiger Logik wie Authentifizierung, Protokollierung oder der Handhabung von Weiterleitungen.

Verwenden Sie die Datei middleware.ts (oder .js) im Stammverzeichnis Ihres Projekts, um Middleware zu definieren. Zum Beispiel auf derselben Ebene wie app oder pages oder innerhalb von src, falls zutreffend.

import { NextResponse, NextRequest } from 'next/server'

// Diese Funktion kann als `async` markiert werden, wenn `await` im Inneren verwendet wird
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

Exports

Middleware-Funktion

Die Datei muss eine einzelne Funktion exportieren, entweder als Standardexport oder mit dem Namen middleware. Beachten Sie, dass mehrere Middleware-Funktionen aus derselben Datei nicht unterstützt werden.

// Beispiel für einen Standardexport
export default function middleware(request) {
  // Middleware-Logik
}

Config-Objekt (optional)

Optional kann ein Config-Objekt neben der Middleware-Funktion exportiert werden. Dieses Objekt enthält den Matcher, um die Pfade anzugeben, auf die die Middleware angewendet wird.

Matcher

Die matcher-Option ermöglicht es Ihnen, bestimmte Pfade anzugeben, auf denen die Middleware ausgeführt werden soll. Sie können diese Pfade auf verschiedene Weise angeben:

• Für einen einzelnen Pfad: Verwenden Sie direkt einen String, um den Pfad zu definieren, z.B. '/about'.
• Für mehrere Pfade: Verwenden Sie ein Array, um mehrere Pfade aufzulisten, z.B. matcher: ['/about', '/contact'], wodurch die Middleware auf /about und /contact angewendet wird.

Zusätzlich unterstützt matcher komplexe Pfadspezifikationen durch reguläre Ausdrücke, wie z.B. matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'], was eine präzise Kontrolle darüber ermöglicht, welche Pfade ein- oder ausgeschlossen werden sollen.

Die matcher-Option akzeptiert auch ein Array von Objekten mit den folgenden Schlüsseln:

• source: Der Pfad oder das Muster, das zum Abgleichen der Anfragepfade verwendet wird. Es kann ein String für direkte Pfadabgleiche oder ein Muster für komplexere Abgleiche sein.
• regexp (optional): Ein String mit regulärem Ausdruck, der den Abgleich basierend auf der Quelle verfeinert. Er bietet zusätzliche Kontrolle darüber, welche Pfade ein- oder ausgeschlossen werden.
• locale (optional): Ein Boolean, der, wenn auf false gesetzt, die sprachbasierte Routing in Pfadabgleichen ignoriert.
• has (optional): Gibt Bedingungen basierend auf dem Vorhandensein bestimmter Anfrageelemente wie Header, Query-Parameter oder Cookies an.
• missing (optional): Konzentriert sich auf Bedingungen, bei denen bestimmte Anfrageelemente fehlen, wie z.B. fehlende Header oder Cookies.

export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

Parameter

request

Bei der Definition von Middleware akzeptiert die Standardexportfunktion einen einzelnen Parameter, request. Dieser Parameter ist eine Instanz von NextRequest, die die eingehende HTTP-Anfrage darstellt.

import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // Middleware-Logik kommt hierhin
}

Gut zu wissen:

• NextRequest ist ein Typ, der eingehende HTTP-Anfragen in Next.js-Middleware darstellt, während NextResponse eine Klasse ist, die zur Manipulation und zum Zurücksenden von HTTP-Antworten verwendet wird.

NextResponse

Middleware kann das NextResponse-Objekt verwenden, das die Web Response API erweitert. Durch die Rückgabe eines NextResponse-Objekts können Sie direkt Cookies manipulieren, Header setzen, Weiterleitungen implementieren und Pfade umschreiben.

Gut zu wissen: Für Weiterleitungen können Sie auch Response.redirect anstelle von NextResponse.redirect verwenden.

Runtime

Middleware verwendet standardmäßig die Edge Runtime. Falls Sie dies nicht möchten, können Sie die vollständige Node.js Runtime verwenden, um Middleware auszuführen.

Versionsverlauf