Weiterleitungen (Redirects)

Weiterleitungen ermöglichen es Ihnen, einen eingehenden Anfragepfad auf einen 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 mit Objekten erwartet, die die Eigenschaften source, destination und permanent enthalten:

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

Warum verwendet Next.js 307 und 308? Traditionell wurde 302 für temporäre Weiterleitungen und 301 für permanente Weiterleitungen verwendet, aber viele Browser haben die Anfragemethode der Weiterleitung unabhängig von der ursprünglichen Methode auf GET geändert. Wenn ein Browser beispielsweise eine Anfrage an POST /v1/users sendete, die den Statuscode 302 mit dem Ort /v2/users zurückgab, könnte die folgende Anfrage GET /v2/users sein statt des erwarteten POST /v2/users. Next.js verwendet die Statuscodes 307 für temporäre und 308 für permanente Weiterleitungen, um die verwendete Anfragemethode explizit beizubehalten.

basePath: false oder undefined - wenn false, wird der basePath nicht beim Abgleich einbezogen, kann nur für externe Weiterleitungen verwendet werden.
locale: false oder undefined - ob die Locale beim Abgleich nicht einbezogen 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 überprüft, das Seiten und /public-Dateien enthält.

Weiterleitungen werden nicht für clientseitiges Routing (Link, router.push) angewendet, es sei denn, Middleware ist vorhanden und passt zum Pfad.

Wenn eine Weiterleitung angewendet wird, werden alle in der Anfrage bereitgestellten Query-Werte an das Weiterleitungsziel übergeben. Beispielsweise siehe die folgende Weiterleitungskonfiguration:

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

Wenn /old-blog/post-1?hello=world angefragt 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,
      },
    ]
  },
}

Wildcard-Pfadabgleich

Um einen Wildcard-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,
      },
    ]
  },
}

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. Wenn sie in der source als nicht-spezielle Werte verwendet werden, müssen sie durch Hinzufügen von \\ davor escaped werden:

next.config.js

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

Um eine Weiterleitung nur dann anzuwenden, wenn Header-, Cookie- oder Query-Werte ebenfalls übereinstimmen, kann das Feld has verwendet werden, oder das Feld missing, um sicherzustellen, dass bestimmte Werte nicht übereinstimmen. 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 die folgenden Felder haben:

type: String - muss entweder header, cookie, host oder query sein.
key: String - der Schlüssel des ausgewählten Typs, gegen den abgeglichen werden soll.
value: String oder undefined - der zu überprüfende Wert. Wenn undefined, wird jeder Wert übereinstimmen. 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, dann 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, Query und Cookie übereinstimmen,
      // wird diese Weiterleitung angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der Seitenwert wird im Ziel nicht verfügbar sein,
            // da value bereitgestellt wird 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

Wenn Sie basePath-Unterstützung mit Weiterleitungen nutzen, werden jeder source und destination automatisch mit dem basePath prefix 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 /docs nicht hinzu, da basePath: false gesetzt ist
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
        permanent: false,
      },
    ]
  },
}

Weiterleitungen mit i18n-Unterstützung

Wenn Sie i18n-Unterstützung mit Weiterleitungen nutzen, werden jeder source und destination automatisch mit den konfigurierten locales prefix versehen, es sei denn, Sie fügen locale: false zur Weiterleitung hinzu. Wenn locale: false verwendet wird, müssen Sie source und destination mit einer Locale prefixen, damit sie korrekt abgeglichen werden können.

next.config.js

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },

  async redirects() {
    return [
      {
        source: '/with-locale', // behandelt alle Locales automatisch
        destination: '/another', // gibt die Locale automatisch weiter
        permanent: false,
      },
      {
        // behandelt Locales nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // dies stimmt mit '/' überein, da `en` die defaultLocale ist
        source: '/en',
        destination: '/en/another',
        locale: false,
        permanent: false,
      },
      // es ist möglich, alle Locales abzugleichen, auch wenn locale: false gesetzt ist
      {
        source: '/:locale/page',
        destination: '/en/newpage',
        permanent: false,
        locale: false,
      },
      {
        // dies wird in /(en|fr|de)/(.*) umgewandelt, sodass es nicht mit den Top-Level
        // `/` oder `/fr` Routen übereinstimmt, wie /:path* es tun würde
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

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

Andere Weiterleitungen

In API-Routen können Sie res.redirect() verwenden.
In getStaticProps und getServerSideProps können Sie bestimmte Seiten zur Laufzeit weiterleiten.

Versionsverlauf

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

Weiterleitungen (Redirects)

On this page