Menu

rewrites

Mit Rewrites kannst du einen eingehenden Anfragepfad auf einen anderen Zielpfad umleiten.

Rewrites fungieren als URL-Proxy und maskieren den Zielpfad, sodass es für Benutzer so aussieht, als hätten sie ihren Standort auf der Website nicht gewechselt. Im Gegensatz dazu leiten Redirects zu einer neuen Seite weiter und zeigen die URL-Änderungen an.

Um Rewrites zu verwenden, kannst du den rewrites-Schlüssel in next.config.js nutzen:

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

Rewrites werden auch auf clientseitiges Routing angewendet. Im obigen Beispiel wird das Rewrite auf einen <Link href="/about"> angewendet.

rewrites ist eine asynchrone Funktion, die entweder ein Array oder ein Objekt von Arrays (siehe unten) mit Objekten zurückgibt, die source- und destination-Eigenschaften enthalten:

  • source: String - ist das Muster des eingehenden Anfragepfads.
  • destination: String - ist der Pfad, zu dem weitergeleitet werden soll.
  • basePath: false oder undefined - wenn false, wird der basePath beim Abgleich nicht einbezogen, kann nur für externe Rewrites 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.

Wenn die rewrites-Funktion ein Array zurückgibt, werden die 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 spezifischen Form zurückgibt, kann dieses Verhalten geändert und feiner gesteuert werden, ab Next.js v10.1:

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

Hinweis: Rewrites in beforeFiles überprüfen nicht sofort nach dem Abgleich einer Quelle das Dateisystem/dynamische Routen, sie werden fortgesetzt, bis alle beforeFiles überprüft wurden.

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

  1. Headers werden überprüft/angewendet
  2. Redirects werden überprüft/angewendet
  3. beforeFiles-Rewrites werden überprüft/angewendet
  4. Statische Dateien aus dem public-Verzeichnis, _next/static-Dateien und nicht-dynamische Seiten werden überprüft/bereitgestellt
  5. afterFiles-Rewrites werden überprüft/angewendet, wenn eines dieser Rewrites übereinstimmt, überprüfen wir nach jeder Übereinstimmung dynamische Routen/statische Dateien
  6. 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 du fallback: true/'blocking' in getStaticPaths verwendest, werden die in deiner 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 im destination verwendet wird.

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

Wenn ein Parameter im Ziel verwendet wird, wird keiner der 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, wird daher nicht automatisch in der Query übergeben
      },
    ]
  },
}

Du kannst die Parameter trotzdem manuell in der Query übergeben, wenn bereits einer im Ziel verwendet wird, indem du die Query im destination angibst.

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

Hinweis: Parameter aus Rewrites für statische Seiten von der Automatischen Statischen Optimierung oder dem Prerendering werden nach der Hydration clientseitig geparst und in der Query bereitgestellt.

Pfadabgleich

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

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog/:slug',
        destination: '/news/:slug', // Übereinstimmende Parameter können im Ziel verwendet werden
      },
    ]
  },
}

Wildcard-Pfadabgleich

Um einen Wildcard-Pfad abzugleichen, kannst du * nach einem Parameter verwenden, zum Beispiel wird /blog/:slug* mit /blog/a/b/c/d/hello-world übereinstimmen:

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

Regex-Pfadabgleich

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

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-blog/:post(\\d{1,})',
        destination: '/blog/:post', // Übereinstimmende Parameter können im Ziel verwendet werden
      },
    ]
  },
}

Die folgenden Zeichen (, ), {, }, [, ], |, \, ^, ., :, *, +, -, ?, $ werden für den Regex-Pfadabgleich verwendet, daher müssen sie, wenn sie in der source als nicht-spezielle Werte verwendet werden, durch Voranstellen von \\ escapt werden:

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        // Dies wird bei einer Anfrage für `/english(default)/something` übereinstimmen
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
      },
    ]
  },
}

Header-, Cookie- und Query-Abgleich

Um ein Rewrite nur dann abzugleichen, wenn Header-, Cookie- oder Query-Werte auch mit dem has-Feld übereinstimmen oder nicht mit dem missing-Feld übereinstimmen, können diese Felder verwendet werden. Sowohl die source als auch alle has-Elemente müssen übereinstimmen und alle missing-Elemente dürfen nicht übereinstimmen, damit das Rewrite 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 aus dem ausgewählten Typ, gegen den abgeglichen werden soll.
  • value: String oder undefined - der zu überprüfende Wert, wenn undefined, stimmt jeder Wert überein. 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 wird second im Ziel mit :paramName verwendbar sein.
next.config.js
module.exports = {
  async rewrites() {
    return [
      // wenn der Header `x-rewrite-me` vorhanden ist,
      // wird dieses Rewrite angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // wenn der Header `x-rewrite-me` nicht vorhanden ist,
      // wird dieses Rewrite angewendet
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // wenn source, query und cookie übereinstimmen,
      // wird dieses Rewrite angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der page-Wert wird im Ziel nicht verfügbar sein,
            // da ein Wert angegeben ist und keine benannte
            // Erfassungsgruppe 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 dieses 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 dieses Rewrite angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        destination: '/another-page',
      },
    ]
  },
}

Umleitung zu einer externen URL

Beispiele

Rewrites ermöglichen die Umleitung zu einer externen URL. Dies ist besonders nützlich für die schrittweise Einführung von Next.js. Das folgende Beispiel zeigt ein Rewrite für die Umleitung der /blog-Route deiner Hauptanwendung zu einer externen Website.

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog',
        destination: 'https://example.com/blog',
      },
      {
        source: '/blog/:slug',
        destination: 'https://example.com/blog/:slug', // Übereinstimmende Parameter können im Ziel verwendet werden
      },
    ]
  },
}

Wenn du trailingSlash: true verwendest, musst du auch einen abschließenden Schrägstrich im source-Parameter einfügen. Wenn der Zielserver ebenfalls einen abschließenden 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

Du kannst Next.js auch so konfigurieren, dass es nach der Überprüfung aller Next.js-Routen auf ein bestehendes Proxy-Website zurückfällt.

Auf diese Weise musst du die Rewrites-Konfiguration nicht ändern, wenn du weitere Seiten zu Next.js migrierst.

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

Bei der Nutzung der basePath-Unterstützung mit Rewrites wird jede source und destination automatisch mit dem basePath versehen, es sei denn, du fügst 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

Bei der Nutzung der i18n-Unterstützung mit Rewrites wird jede source und destination automatisch angepasst, um die konfigurierten locales zu berücksichtigen, es sei denn, du fügst locale: false zum Rewrite hinzu. Wenn locale: false verwendet wird, musst du die source und destination mit einer Locale versehen, damit sie korrekt übereinstimmen.

next.config.js
module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async rewrites() {
    return [
      {
        source: '/with-locale', // behandelt automatisch alle Locales
        destination: '/another', // gibt die Locale automatisch weiter
      },
      {
        // behandelt Locales nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
      },
      {
        // dies stimmt mit '/' überein, da `en` die defaultLocale ist
        source: '/en',
        destination: '/en/another',
        locale: false,
      },
      {
        // es ist möglich, alle Locales abzugleichen, auch wenn locale: false gesetzt ist
        source: '/:locale/api-alias/:path*',
        destination: '/api/:path*',
        locale: false,
      },
      {
        // dies wird zu /(en|fr|de)/(.*) konvertiert und stimmt daher nicht mit den Top-Level-
        // `/` oder `/fr` Routen überein wie /:path* es würde
        source: '/(.*)',
        destination: '/another',
      },
    ]
  },
}

Versionshistorie

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