Rewrites

Rewrites ermöglichen es Ihnen, einen eingehenden Anfragepfad einem anderen Zielpfad zuzuordnen.

Rewrites fungieren als URL-Proxy und maskieren den Zielpfad, sodass es so aussieht, als hätte der Benutzer seinen Standort auf der Website nicht geändert. Im Gegensatz dazu leiten Redirects zu einer neuen Seite weiter und zeigen die URL-Änderungen an.

Um Rewrites zu verwenden, können Sie den rewrites-Schlüssel in next.config.js nutzen:

next.config.js

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

Rewrites werden auf das Client-seitige Routing angewendet, ein <Link href="/about"> würde in obigem Beispiel den Rewrite anwenden.

rewrites ist eine asynchrone Funktion, die entweder ein Array oder ein Objekt von Arrays (siehe unten) zurückgeben soll, das Objekte mit den Eigenschaften source und destination enthält:

source: String - der eingehende Anfragepfad-Muster.
destination: String - der Pfad, zu dem geroutet werden soll.
basePath: false oder undefined - wenn false, wird der basePath beim Matching nicht berücksichtigt, kann nur für externe Rewrites verwendet werden.
locale: false oder undefined - ob das Locale beim Matching 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.

Wenn die rewrites-Funktion ein Array zurückgibt, werden Rewrites nach der Überprüfung des Dateisystems (Seiten und /public-Dateien) und vor dynamischen Routen angewendet. Wenn die rewrites-Funktion ein Objekt von Arrays mit einer bestimmten Struktur zurückgibt, kann dieses Verhalten geändert und feiner kontrolliert werden, ab v10.1 von Next.js:

next.config.js

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // Diese Rewrites werden nach Headers/Redirects
        // und vor allen Dateien inklusive _next/public-Dateien überprüft,
        // was das Überschreiben von Seiten-Dateien ermöglicht
        {
          source: '/some-page',
          destination: '/somewhere-else',
          has: [{ type: 'query', key: 'overrideMe' }],
        },
      ],
      afterFiles: [
        // Diese Rewrites werden nach Seiten/public-Dateien
        // überprüft, aber vor dynamischen Routen
        {
          source: '/non-existent',
          destination: '/somewhere-else',
        },
      ],
      fallback: [
        // Diese Rewrites werden sowohl nach Seiten/public-Dateien
        // als auch nach dynamischen Routen überprüft
        {
          source: '/:path*',
          destination: `https://my-old-site.com/:path*`,
        },
      ],
    }
  },
}

Gut zu wissen: Rewrites in beforeFiles überprüfen das Dateisystem/dynamische Routen nicht unmittelbar nach dem Matching einer Source, sie werden weiter überprüft, bis alle beforeFiles abgearbeitet sind.

Die Reihenfolge, in der Next.js Routen überprüft werden, ist:

Headers werden überprüft/angewendet
Redirects werden überprüft/angewendet
beforeFiles-Rewrites werden überprüft/angewendet
Statische Dateien aus dem public-Verzeichnis, _next/static-Dateien und nicht-dynamische Seiten werden überprüft/bereitgestellt
afterFiles-Rewrites werden überprüft/angewendet, wenn eines dieser Rewrites matched, werden dynamische Routen/statische Dateien nach jedem Match überprüft
fallback-Rewrites werden überprüft/angewendet, diese werden vor dem Rendern der 404-Seite und nach der Überprüfung dynamischer Routen/aller statischen Assets angewendet. Wenn Sie fallback: true/'blocking' in getStaticPaths verwenden, werden die in Ihrer next.config.js definierten fallback-Rewrites nicht ausgeführt.

Rewrite-Parameter

Wenn Parameter in einem Rewrite verwendet werden, werden die Parameter standardmäßig in der Query übergeben, wenn keiner der Parameter in der destination verwendet wird.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-about/:path*',
        destination: '/about', // Der :path-Parameter wird hier nicht verwendet und wird automatisch in der Query übergeben
      },
    ]
  },
}

Wenn ein Parameter in der Destination verwendet wird, werden keine Parameter automatisch in der Query übergeben.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: '/:path*', // Der :path-Parameter wird hier verwendet und wird nicht automatisch in der Query übergeben
      },
    ]
  },
}

Sie können die Parameter dennoch manuell in der Query übergeben, wenn einer bereits in der Destination verwendet wird, indem Sie die Query in der destination angeben.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/:first/:second',
        destination: '/:first?second=:second',
        // Da der :first-Parameter in der Destination verwendet wird, wird der :second-Parameter
        // nicht automatisch in der Query hinzugefügt, obwohl wir ihn manuell hinzufügen können,
        // wie oben gezeigt
      },
    ]
  },
}

Gut zu wissen: Statische Seiten aus Automatic Static Optimization oder Prerendering Parameter von Rewrites werden nach der Hydration auf dem Client geparst und in der Query bereitgestellt.

Pfad-Matching

Pfad-Matches sind erlaubt, zum Beispiel wird /blog/:slug mit /blog/hello-world matchen (keine verschachtelten Pfade):

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog/:slug',
        destination: '/news/:slug', // Gematchte Parameter können in der Destination verwendet werden
      },
    ]
  },
}

Wildcard-Pfad-Matching

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

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // Gematchte Parameter können in der Destination verwendet werden
      },
    ]
  },
}

Regex-Pfad-Matching

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

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-blog/:post(\\d{1,})',
        destination: '/blog/:post', // Gematchte Parameter können in der Destination verwendet werden
      },
    ]
  },
}

Die folgenden Zeichen (, ), {, }, [, ], |, \, ^, ., :, *, +, -, ?, $ werden für Regex-Pfad-Matching verwendet, daher müssen sie, wenn sie in der source als nicht-spezielle Werte verwendet werden, durch Hinzufügen von \\ vor ihnen escaped werden:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        // dies wird `/english(default)/something` matchen, wenn es angefragt wird
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
      },
    ]
  },
}

Um einen Rewrite nur dann anzuwenden, 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 der Rewrite 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 gematcht werden soll.
value: String oder undefined - der zu überprüfende Wert, wenn undefined, wird jeder Wert gematcht. 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 in der Destination mit :paramName verwendet werden.

next.config.js

module.exports = {
  async rewrites() {
    return [
      // wenn der Header `x-rewrite-me` vorhanden ist,
      // wird dieser Rewrite angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // wenn der Header `x-rewrite-me` nicht vorhanden ist,
      // wird dieser Rewrite angewendet
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // wenn die Source, Query und Cookie übereinstimmen,
      // wird dieser Rewrite angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der page-Wert wird in der Destination nicht verfügbar sein,
            // da value angegeben ist und keine benannte Capture-Gruppe verwendet wird, z.B. (?<page>home)
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        destination: '/:path*/home',
      },
      // wenn der Header `x-authorized` vorhanden ist und
      // einen übereinstimmenden Wert enthält, wird dieser Rewrite angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        destination: '/home?authorized=:authorized',
      },
      // wenn der Host `example.com` ist,
      // wird dieser Rewrite angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        destination: '/another-page',
      },
    ]
  },
}

Rewriting zu einer externen URL

Beispiele

Verwendung mehrerer Zonen

Rewrites ermöglichen es Ihnen, zu einer externen URL umzuleiten. Dies ist besonders nützlich für die schrittweise Einführung von Next.js. Das folgende Beispiel zeigt einen Rewrite, der die /blog-Route Ihrer Haupt-App zu einer externen Site umleitet.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog',
        destination: 'https://example.com/blog',
      },
      {
        source: '/blog/:slug',
        destination: 'https://example.com/blog/:slug', // Gematchte Parameter können in der Destination verwendet werden
      },
    ]
  },
}

Wenn Sie trailingSlash: true verwenden, müssen Sie auch einen nachgestellten Schrägstrich in den source-Parameter einfügen. Wenn der Zielserver ebenfalls einen nachgestellten Schrägstrich erwartet, sollte dieser auch im destination-Parameter enthalten sein.

next.config.js

module.exports = {
  trailingSlash: true,
  async rewrites() {
    return [
      {
        source: '/blog/',
        destination: 'https://example.com/blog/',
      },
      {
        source: '/blog/:path*/',
        destination: 'https://example.com/blog/:path*/',
      },
    ]
  },
}

Schrittweise Einführung von Next.js

Sie können Next.js auch so konfigurieren, dass es nach der Überprüfung aller Next.js-Routen auf einen Proxy für eine bestehende Website zurückfällt.

Auf diese Weise müssen Sie die Rewrite-Konfiguration nicht ändern, wenn Sie weitere Seiten zu Next.js migrieren.

next.config.js

module.exports = {
  async rewrites() {
    return {
      fallback: [
        {
          source: '/:path*',
          destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
        },
      ],
    }
  },
}

Rewrites mit basePath-Unterstützung

Wenn Sie basePath-Unterstützung mit Rewrites verwenden, wird jeder source- und destination-Pfad automatisch mit dem basePath präfixiert, es sei denn, Sie fügen basePath: false zum Rewrite hinzu:

next.config.js

module.exports = {
  basePath: '/docs',

  async rewrites() {
    return [
      {
        source: '/with-basePath', // wird automatisch zu /docs/with-basePath
        destination: '/another', // wird automatisch zu /docs/another
      },
      {
        // fügt /docs nicht zu /without-basePath hinzu, da basePath: false gesetzt ist
        // Hinweis: dies kann nicht für interne Rewrites verwendet werden, z.B. `destination: '/another'`
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
      },
    ]
  },
}

Rewrites mit i18n-Unterstützung

Wenn Sie i18n-Unterstützung mit Rewrites verwenden, wird jeder source- und destination-Pfad automatisch präfixiert, um die konfigurierten locales zu handhaben, es sei denn, Sie fügen locale: false zum Rewrite hinzu. Wenn locale: false verwendet wird, müssen Sie source und destination mit einem Locale präfixieren, damit sie korrekt gematcht werden können.

next.config.js

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

  async rewrites() {
    return [
      {
        source: '/with-locale', // handhabt automatisch alle Locales
        destination: '/another', // übergibt automatisch das Locale
      },
      {
        // handhabt Locales nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
      },
      {
        // matched '/', da `en` das defaultLocale ist
        source: '/en',
        destination: '/en/another',
        locale: false,
      },
      {
        // es ist möglich, alle Locales zu matchen, auch wenn locale: false gesetzt ist
        source: '/:locale/api-alias/:path*',
        destination: '/api/:path*',
        locale: false,
      },
      {
        // wird zu /(en|fr|de)/(.*) konvertiert, sodass es nicht die Top-Level
        // `/` oder `/fr` Routen wie /:path* matchen würde
        source: '/(.*)',
        destination: '/another',
      },
    ]
  },
}

Versionsverlauf

Version	Änderungen
`v13.3.0`	`missing` hinzugefügt.
`v10.2.0`	`has` hinzugefügt.
`v9.5.0`	Header-Unterstützung hinzugefügt.

On this page