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 direktes Antworten modifizieren.

Middleware wird ausgeführt, bevor Routen gerendert werden. Sie ist besonders nützlich für die Implementierung von 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*',
}

import { NextResponse } from 'next/server'

// Diese Funktion kann als `async` markiert werden, wenn `await` im Inneren verwendet wird
export function middleware(request) {
  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 benannt als 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, spezifische Pfade anzugeben, auf denen die Middleware ausgeführt werden soll. Sie können diese Pfade auf verschiedene Arten angeben:

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

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 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 zur Übereinstimmung mit den Anfragepfaden verwendet wird. Es kann ein String für direkte Pfadübereinstimmung oder ein Muster für komplexere Übereinstimmung sein.
• regexp (optional): Ein regulärer Ausdruck als String, der die Übereinstimmung 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 lokalisierungsbasierte Routing-Übereinstimmung ignoriert.
• has (optional): Gibt Bedingungen basierend auf dem Vorhandensein spezifischer Anfrageelemente wie Header, Abfrageparameter oder Cookies an.
• missing (optional): Konzentriert sich auf Bedingungen, bei denen bestimmte Anfrageelemente 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 darstellt.

import type { NextRequest } from 'next/server'

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

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

Gut zu wissen:

• NextRequest ist ein Typ, der eingehende HTTP-Anfragen in Next.js-Middleware repräsentiert, 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.

Laufzeitumgebung

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

Versionsverlauf