middleware.js

Die middleware.js|ts-Datei 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 dann die Antwort durch Umschreiben, Umleiten, Ändern der Anfrage- oder Antwortheader oder direktes Antworten modifizieren.

Middleware wird vor dem Rendering von Routen ausgeführt. Sie ist besonders nützlich für die Implementierung von benutzerdefinierter serverseitiger Logik wie Authentifizierung, Logging oder Behandlung von Umleitungen.

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

import { NextResponse, NextRequest } from 'next/server'
 
// Diese Funktion kann mit `async` markiert werden, wenn `await` innerhalb verwendet wird
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}

import { NextResponse } from 'next/server'
 
// Diese Funktion kann mit `async` markiert werden, wenn `await` innerhalb verwendet wird
export function middleware(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}

Exporte

Middleware-Funktion

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

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

Konfigurationsobjekt (optional)

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

Matcher

Die Option matcher ermöglicht es Ihnen, bestimmte Pfade auszuwählen, auf denen die Middleware ausgeführt wird. Sie können diese Pfade auf mehrere Arten angeben:

• Für einen einzelnen Pfad: Verwenden Sie direkt einen Zeichenkettenstring, um den Pfad zu definieren, wie '/about'.
• Für mehrere Pfade: Verwenden Sie ein Array, um mehrere Pfade aufzulisten, wie matcher: ['/about', '/contact'], was die Middleware auf beide Pfade /about und /contact anwendet.

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

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

• source: Der Pfad oder das Muster zum Abgleichen der Anfragepfade. Es kann ein Zeichenkettenstring für direktes Pfadabgleichen oder ein Muster für komplexeren Abgleich sein.
• regexp (optional): Ein regulärer Ausdruck als Zeichenkettenstring, der den Abgleich basierend auf der Quelle verfeinert. Er bietet zusätzliche Kontrolle darüber, welche Pfade einbezogen oder ausgeschlossen werden.
• locale (optional): Ein boolescher Wert, der bei Festlegung auf false das lokalisierungsbasierte Routing beim Pfadabgleich ignoriert.
• has (optional): Gibt Bedingungen basierend auf dem Vorhandensein bestimmter Anforderungselemente wie Header, Abfrageparameter oder Cookies an.
• missing (optional): Konzentriert sich auf Bedingungen, bei denen bestimmte Anforderungselemente fehlen, wie 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 repräsentiert.

import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // Middleware-Logik wird hier eingefügt
}

export function middleware(request) {
  // Middleware-Logik wird hier eingefügt
}

Hinweis:

• NextRequest ist ein Typ, der eingehende HTTP-Anfragen in Next.js Middleware repräsentiert, während NextResponse eine Klasse ist, die verwendet wird, um HTTP-Antworten zu manipulieren und zurückzusenden.

NextResponse

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

Hinweis: Für Umleitungen können Sie auch Response.redirect anstelle von NextResponse.redirect verwenden.

Laufzeit

Middleware unterstützt nur die Edge-Laufzeit. Die Node.js-Laufzeit kann nicht verwendet werden.

Versionshistorie