Weiterleitungen

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:

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: Das Muster des eingehenden Anfragepfads.
• destination: Der Pfad, zu dem umgeleitet 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 beispielsweise ein Browser eine Anfrage an POST /v1/users sendete, die den Statuscode 302 mit dem Standort /v2/users zurückgab, könnte die nachfolgende Anfrage GET /v2/users sein, anstatt des erwarteten POST /v2/users. Next.js verwendet die Statuscodes 307 (temporär) und 308 (permanent), 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 - gibt an, ob die Locale beim Abgleich nicht einbezogen werden soll.
• has: Ein Array von Has-Objekten mit den Eigenschaften type, key und value.
• missing: 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.

Bei Verwendung des Pages-Routers werden Weiterleitungen nicht auf 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
}

Gut zu wissen: Denken Sie daran, den Schrägstrich / vor dem Doppelpunkt : in den Pfadparametern der source- und destination-Pfade einzufügen, da der Pfad sonst als wörtliche Zeichenkette behandelt wird und Sie riskieren, Endlosschleifen zu verursachen.

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

Pfadabgleich

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

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, z.B. wird /blog/:slug* mit /blog/a/b/c/d/hello-world übereinstimmen:

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, z.B. wird /post/:slug(\\d{1,}) mit /post/123 übereinstimmen, aber nicht mit /post/abc:

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 den Regex-Pfadabgleich verwendet. Wenn sie in der source als nicht-spezielle Werte verwendet werden, müssen sie durch Voranstellen von \\ maskiert werden:

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

Header-, Cookie- und Query-Abgleich

Um eine Weiterleitung nur dann abzugleichen, wenn Header-, Cookie- oder Query-Werte ebenfalls übereinstimmen, kann das Feld has verwendet werden, oder das Feld missing, wenn sie nicht übereinstimmen sollen. 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 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, kann second im Ziel mit :paramName verwendet werden.

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 der Wert bereitgestellt wird und keine benannte
            // Erfassungsgruppe verwendet, 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-Pfad automatisch mit dem basePath präfixiert, es sei denn, Sie fügen basePath: false zur Weiterleitung hinzu:

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-Pfad automatisch präfixiert, um die konfigurierten locales zu handhaben, 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 präfixieren, damit sie korrekt abgeglichen werden können.

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

  async redirects() {
    return [
      {
        source: '/with-locale', // handhabt automatisch alle Locales
        destination: '/another', // gibt die Locale automatisch weiter
        permanent: false,
      },
      {
        // handhabt Locales nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // 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,
      },
      {
        // wird zu /(en|fr|de)/(.*) konvertiert, stimmt also nicht mit den
        // Top-Level-Pfaden `/` oder `/fr` überein, wie es /:path* tun würde
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

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

Andere Weiterleitungen

• Innerhalb von API-Routen und Route Handlern können Sie basierend auf der eingehenden Anfrage weiterleiten.
• Innerhalb von getStaticProps und getServerSideProps können Sie bestimmte Seiten zur Laufzeit weiterleiten.

Versionsverlauf