Weiterleitungen

Weiterleitungen ermöglichen es Ihnen, eine eingehende Anfragepfadanfrage zu einem anderen Zielpfad umzuleiten.

Um Weiterleitungen zu verwenden, können Sie den Schlüssel redirects in next.config.js nutzen:

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/about',
        destination: '/',
        permanent: true,
      },
    ]
  },
}

redirects ist eine asynchrone Funktion, die ein Array erwartet, das Objekte mit den Eigenschaften source, destination und permanent enthält:

source ist das Muster des eingehenden Anfragepfads.
destination ist der Pfad, zu dem weitergeleitet werden soll.
permanent true oder false - bei true wird der 308-Statuscode verwendet, der Clients/Suchmaschinen anweist, die Weiterleitung dauerhaft zu cachen, bei false wird der 307-Statuscode verwendet, der temporär ist und nicht gecacht wird.

Warum verwendet Next.js 307 und 308? Traditionell wurde 302 für eine temporäre Weiterleitung und 301 für eine permanente Weiterleitung verwendet, aber viele Browser änderten die Anfragemethode der Weiterleitung zu GET, unabhängig von der ursprünglichen Methode. Wenn beispielsweise der Browser eine Anfrage an POST /v1/users stellte, die den Statuscode 302 mit dem Standort /v2/users zurückgab, könnte die anschließende Anfrage GET /v2/users anstelle der erwarteten POST /v2/users sein. Next.js verwendet die Statuscode 307 für temporäre Weiterleitungen und 308 für permanente Weiterleitungen, um die verwendete Anfragemethode explizit beizubehalten.

basePath: false oder undefined - wenn false, wird der basePath nicht beim Abgleich berücksichtigt, kann nur für externe Weiterleitungen verwendet werden.
locale: false oder undefined - ob der Gebietsschema-Präfix beim Abgleich nicht berücksichtigt werden soll.
has ist ein Array von has-Objekten mit den Eigenschaften type, key und value.
missing ist ein Array von missing-Objekten mit den Eigenschaften type, key und value.

Weiterleitungen werden vor dem Dateisystem geprüft, einschließlich Seiten und /public-Dateien.

Bei Verwendung des Pages Routers werden Weiterleitungen nicht auf Client-Side-Routing (Link, router.push) angewendet, es sei denn, Middleware ist vorhanden und stimmt mit dem Pfad überein.

Wenn eine Weiterleitung angewendet wird, werden alle in der Anfrage bereitgestellten Abfragewerte an das Weiterleitungsziel weitergegeben. Betrachten Sie beispielsweise folgende Weiterleitungskonfiguration:

{
  source: '/old-blog/:path*',
  destination: '/blog/:path*',
  permanent: false
}

Wenn /old-blog/post-1?hello=world angefordert wird, wird der Client zu /blog/post-1?hello=world weitergeleitet.

Pfadabgleich

Pfadabgleiche sind erlaubt, zum Beispiel wird /old-blog/:slug mit /old-blog/hello-world übereinstimmen (keine verschachtelten Pfade):

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/news/:slug', // Übereinstimmende Parameter können im Ziel verwendet werden
        permanent: true,
      },
    ]
  },
}

Platzhalter-Pfadabgleich

Um einen Platzhalter-Pfad abzugleichen, können Sie * nach einem Parameter verwenden, zum Beispiel wird /blog/:slug* mit /blog/a/b/c/d/hello-world übereinstimmen:

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // Übereinstimmende Parameter können im Ziel verwendet werden
        permanent: true,
      },
    ]
  },
}

Regex-Pfadabgleich

Um einen Regex-Pfad abzugleichen, können Sie den Regex in Klammern nach einem Parameter einschließen, zum Beispiel wird /post/:slug(\\d{1,}) mit /post/123 übereinstimmen, aber nicht mit /post/abc:

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/post/:slug(\\d{1,})',
        destination: '/news/:slug', // Übereinstimmende Parameter können im Ziel verwendet werden
        permanent: false,
      },
    ]
  },
}

Die folgenden Zeichen (, ), {, }, :, *, +, ? werden für Regex-Pfadabgleiche verwendet, daher müssen sie beim Einsatz als Nicht-Sonderzeichen in der source mit einem \\ davor maskiert werden:

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        // dies wird einer Anfrage nach `/english(default)/something` entsprechen
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
        permanent: false,
      },
    ]
  },
}

Um eine Weiterleitung nur bei Übereinstimmung von Header-, Cookie- oder Abfragewerten weiterzuleiten, können die Felder has und missing verwendet werden. Sowohl die source als auch alle has-Elemente müssen übereinstimmen und alle missing-Elemente dürfen nicht übereinstimmen, damit die Weiterleitung angewendet wird.

has und missing-Elemente können folgende Felder haben:

type: String - muss entweder header, cookie, host oder query sein.
key: String - der Schlüssel des ausgewählten Typs, gegen den verglichen wird.
value: String oder undefined - der zu prüfende Wert, wenn undefined, passt jeder Wert. Ein regex-ähnlicher String kann verwendet werden, um einen bestimmten Teil des Werts zu erfassen, z.B. wenn der Wert first-(?<paramName>.*) für first-second verwendet wird, kann second im Ziel mit :paramName verwendet werden.

next.config.js

module.exports = {
  async redirects() {
    return [
      // wenn der Header `x-redirect-me` vorhanden ist,
      // wird diese Weiterleitung angewendet
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'header',
            key: 'x-redirect-me',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // wenn der Header `x-dont-redirect` vorhanden ist,
      // wird diese Weiterleitung NICHT angewendet
      {
        source: '/:path((?!another-page$).*)',
        missing: [
          {
            type: 'header',
            key: 'x-do-not-redirect',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // wenn Source, Abfrage und Cookie übereinstimmen,
      // wird diese Weiterleitung angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der Seitenwert ist nicht im Ziel verfügbar,
            // da der Wert angegeben ist und keine benannte
            // Erfassungsgruppe verwendet wird, z.B. (?<page>home)
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        permanent: false,
        destination: '/another/:path*',
      },
      // wenn der Header `x-authorized` vorhanden ist und
      // einen übereinstimmenden Wert enthält, wird diese Weiterleitung angewendet
      {
        source: '/',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        permanent: false,
        destination: '/home?authorized=:authorized',
      },
      // wenn der Host `example.com` ist,
      // wird diese Weiterleitung angewendet
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
    ]
  },
}

Weiterleitungen mit basePath-Unterstützung

Bei Nutzung der basePath-Unterstützung mit Weiterleitungen wird jede source und destination automatisch mit dem basePath versehen, es sei denn, Sie fügen basePath: false zur Weiterleitung hinzu:

next.config.js

module.exports = {
  basePath: '/docs',
 
  async redirects() {
    return [
      {
        source: '/with-basePath', // wird automatisch zu /docs/with-basePath
        destination: '/another', // wird automatisch zu /docs/another
        permanent: false,
      },
      {
        // fügt kein /docs hinzu, da basePath: false gesetzt ist
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
        permanent: false,
      },
    ]
  },
}

Weiterleitungen mit i18n-Unterstützung

Bei der Nutzung der i18n-Unterstützung mit Weiterleitungen werden jede source und destination automatisch mit einem Präfix versehen, um die konfigurierten locales zu behandeln, es sei denn, Sie fügen locale: false zur Weiterleitung hinzu. Wenn locale: false verwendet wird, müssen Sie die source und destination mit einer Lokalisierung versehen, damit sie korrekt zugeordnet werden können.

next.config.js

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async redirects() {
    return [
      {
        source: '/with-locale', // behandelt automatisch alle Lokalisierungen
        destination: '/another', // übergibt die Lokalisierung automatisch
        permanent: false,
      },
      {
        // behandelt Lokalisierungen nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // entspricht '/', da `en` die Standardlokalisierung ist
        source: '/en',
        destination: '/en/another',
        locale: false,
        permanent: false,
      },
      // Es ist möglich, alle Lokalisierungen zu matching, auch wenn locale: false gesetzt ist
      {
        source: '/:locale/page',
        destination: '/en/newpage',
        permanent: false,
        locale: false,
      },
      {
        // wird in /(en|fr|de)/(.*) konvertiert, sodass die Top-Level-Routen
        // '/' oder '/fr' nicht gemacht werden wie /:path*
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

In seltenen Fällen müssen Sie möglicherweise einen benutzerdefinierten Statuscode für ältere HTTP-Clients zuweisen, um die Weiterleitung ordnungsgemäß durchzuführen. In diesen Fällen können Sie die Eigenschaft statusCode anstelle der Eigenschaft permanent verwenden, aber nicht beide. Um die IE11-Kompatibilität zu gewährleisten, wird für den Statuscode 308 automatisch ein Refresh-Header hinzugefügt.

Andere Weiterleitungen

In API-Routen und Route-Handlern können Sie basierend auf der eingehenden Anfrage weiterleiten.
In getStaticProps und getServerSideProps können Sie bestimmte Seiten zum Zeitpunkt der Anfrage weiterleiten.

Versionshistorie

Version	Änderungen
`v13.3.0`	`missing` hinzugefügt.
`v10.2.0`	`has` hinzugefügt.
`v9.5.0`	`redirects` hinzugefügt.