Menu

Header

Header ermöglichen es Ihnen, benutzerdefinierte HTTP-Header für die Antwort auf eine eingehende Anfrage für einen bestimmten Pfad festzulegen.

Um benutzerdefinierte HTTP-Header festzulegen, können Sie den Schlüssel headers in next.config.js verwenden:

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/about',
        headers: [
          {
            key: 'x-custom-header',
            value: 'mein benutzerdefinierter Header-Wert',
          },
          {
            key: 'x-another-custom-header',
            value: 'mein anderer benutzerdefinierter Header-Wert',
          },
        ],
      },
    ]
  },
}

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

  • source ist das Pfadmuster der eingehenden Anfrage.
  • headers ist ein Array von Response-Header-Objekten mit den Eigenschaften key und value.
  • 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 das Gebietsschema 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.

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

Verhalten beim Header-Überschreiben

Wenn zwei Header denselben Pfad haben und denselben Header-Schlüssel setzen, überschreibt der letzte Header-Schlüssel den ersten. Bei den folgenden Headern wird der Pfad /hello dazu führen, dass der Header x-hello den Wert world hat, da der zuletzt gesetzte Header-Wert world ist.

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'x-hello',
            value: 'there',
          },
        ],
      },
      {
        source: '/hello',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

Pfad-Matching

Pfad-Übereinstimmungen sind erlaubt, beispielsweise wird /blog/:slug mit /blog/hello-world übereinstimmen (keine verschachtelten Pfade):

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:slug',
        headers: [
          {
            key: 'x-slug',
            value: ':slug', // Übereinstimmende Parameter können im Wert verwendet werden
          },
          {
            key: 'x-slug-:slug', // Übereinstimmende Parameter können im Schlüssel verwendet werden
            value: 'mein anderer benutzerdefinierter Header-Wert',
          },
        ],
      },
    ]
  },
}

Wildcard-Pfad-Matching

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

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:slug*',
        headers: [
          {
            key: 'x-slug',
            value: ':slug*', // Übereinstimmende Parameter können im Wert verwendet werden
          },
          {
            key: 'x-slug-:slug*', // Übereinstimmende Parameter können im Schlüssel verwendet werden
            value: 'mein anderer benutzerdefinierter Header-Wert',
          },
        ],
      },
    ]
  },
}

Regex-Pfad-Matching

Um einen Regex-Pfad zu matchen, können Sie den Regex in Klammern nach einem Parameter setzen, beispielsweise wird /blog/:slug(\\d{1,}) mit /blog/123 übereinstimmen, aber nicht mit /blog/abc:

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:post(\\d{1,})',
        headers: [
          {
            key: 'x-post',
            value: ':post',
          },
        ],
      },
    ]
  },
}

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

next.config.js
module.exports = {
  async headers() {
    return [
      {
        // dies wird einer Anfrage für `/english(default)/something` entsprechen
        source: '/english\\(default\\)/:slug',
        headers: [
          {
            key: 'x-header',
            value: 'value',
          },
        ],
      },
    ]
  },
}

Um einen Header nur anzuwenden, wenn Header-, Cookie- oder Query-Werte ebenfalls mit dem has-Feld übereinstimmen oder nicht mit dem missing-Feld übereinstimmen, können 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 der Header 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 gemacht wird.
  • value: String oder undefined - der zu prüfende Wert, wenn nicht definiert, passt jeder Wert. Ein regex-ähnlicher String kann verwendet werden, um einen bestimmten Teil des Wertes 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 headers() {
    return [
      // wenn der Header `x-add-header` vorhanden ist,
      // wird der Header `x-another-header` angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-add-header',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: 'hallo',
          },
        ],
      },
      // wenn der Header `x-no-header` nicht vorhanden ist,
      // wird der Header `x-another-header` angewendet
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-no-header',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: 'hallo',
          },
        ],
      },
      // wenn Quelle, Query und Cookie übereinstimmen,
      // wird der Header `x-authorized` angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der Seitenwert wird in den Header-Schlüsseln/Werten 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',
          },
        ],
        headers: [
          {
            key: 'x-authorized',
            value: ':authorized',
          },
        ],
      },
      // wenn der Header `x-authorized` vorhanden ist und
      // einen übereinstimmenden Wert enthält, wird `x-another-header` angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: ':authorized',
          },
        ],
      },
      // wenn der Host `example.com` ist,
      // wird dieser Header angewendet
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: ':authorized',
          },
        ],
      },
    ]
  },
}

Header mit basePath-Unterstützung

Bei Verwendung von basePath-Unterstützung mit Headern wird jede source automatisch mit dem basePath präfigiert, es sei denn, Sie fügen basePath: false zum Header hinzu:

next.config.js
module.exports = {
  basePath: '/docs',
 
  async headers() {
    return [
      {
        source: '/with-basePath', // wird zu /docs/with-basePath
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        source: '/without-basePath', // wird nicht modifiziert, da basePath: false gesetzt ist
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
        basePath: false,
      },
    ]
  },
}

Header mit i18n-Unterstützung

Bei Verwendung der i18n-Unterstützung werden bei Headern automatisch alle source-Einträge mit den konfigurierten locales versehen, es sei denn, Sie fügen locale: false zum Header hinzu. Wenn locale: false verwendet wird, müssen Sie die source mit einem Gebietsschema versehen, damit sie korrekt zugeordnet wird.

next.config.js
module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async headers() {
    return [
      {
        source: '/with-locale', // behandelt automatisch alle Gebietsschemas
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // behandelt Gebietsschemas nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        locale: false,
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // passt zu '/', da 'en' das Standardgebietsschema ist
        source: '/en',
        locale: false,
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // wird zu /(en|fr|de)/(.*) konvertiert, sodass es nicht die obersten Routen
        // '/' oder '/fr' wie /:path* matcht
        source: '/(.*)',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

Cache-Control

Next.js setzt den Cache-Control-Header auf public, max-age=31536000, immutable für wirklich unveränderliche Assets. Er kann nicht überschrieben werden. Diese unveränderlichen Dateien enthalten einen SHA-Hash im Dateinamen, sodass sie sicher unbegrenzt zwischengespeichert werden können. Beispielsweise Statische Bildimporte. Sie können für diese Assets keine Cache-Control-Header in next.config.js festlegen.

Sie können jedoch Cache-Control-Header für andere Antworten oder Daten festlegen.

Weitere Informationen zum Caching mit dem App Router.

Optionen

CORS

Cross-Origin Resource Sharing (CORS) ist eine Sicherheitsfunktion, die es Ihnen ermöglicht zu steuern, welche Seiten auf Ihre Ressourcen zugreifen können. Sie können den Access-Control-Allow-Origin-Header festlegen, um einem bestimmten Ursprung den Zugriff auf Ihre Route-Handler zu erlauben.

async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          {
            key: "Access-Control-Allow-Origin",
            value: "*", // Setzen Sie Ihren Ursprung
          },
          {
            key: "Access-Control-Allow-Methods",
            value: "GET, POST, PUT, DELETE, OPTIONS",
          },
          {
            key: "Access-Control-Allow-Headers",
            value: "Content-Type, Authorization",
          },
        ],
      },
    ];
  },

X-DNS-Prefetch-Control

Dieser Header steuert das DNS-Prefetching und ermöglicht Browsern, proaktiv Domainnamenauflösungen für externe Links, Bilder, CSS, JavaScript und mehr durchzuführen. Dieses Prefetching wird im Hintergrund ausgeführt, sodass die DNS wahrscheinlich aufgelöst ist, wenn die referenzierten Elemente benötigt werden. Dies reduziert die Latenz, wenn der Benutzer einen Link anklickt.

{
  key: 'X-DNS-Prefetch-Control',
  value: 'on'
}

Strict-Transport-Security

Dieser Header informiert Browser, dass nur über HTTPS zugegriffen werden sollte, anstatt über HTTP. Mit der unten stehenden Konfiguration werden alle aktuellen und zukünftigen Subdomains für eine max-age von 2 Jahren über HTTPS verwendet. Dies blockiert den Zugriff auf Seiten oder Subdomains, die nur über HTTP bereitgestellt werden können.

Wenn Sie auf Vercel bereitstellen, ist dieser Header nicht erforderlich, da er automatisch zu allen Bereitstellungen hinzugefügt wird, es sei denn, Sie deklarieren headers in Ihrer next.config.js.

{
  key: 'Strict-Transport-Security',
  value: 'max-age=63072000; includeSubDomains; preload'
}

X-Frame-Options

Dieser Header gibt an, ob die Website in einem iframe angezeigt werden darf. Dies kann Clickjacking-Angriffe verhindern.

Dieser Header wurde durch die CSP-Option frame-ancestors ersetzt, die in modernen Browsern besser unterstützt wird (weitere Konfigurationsdetails finden Sie unter Content Security Policy).

{
  key: 'X-Frame-Options',
  value: 'SAMEORIGIN'
}

Permissions-Policy

Dieser Header ermöglicht es Ihnen, zu steuern, welche Features und APIs im Browser verwendet werden können. Er wurde zuvor Feature-Policy genannt.

{
  key: 'Permissions-Policy',
  value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()'
}

X-Content-Type-Options

Dieser Header verhindert, dass der Browser versucht, den Inhaltstyp zu erraten, wenn der Content-Type-Header nicht explizit gesetzt ist. Dies kann XSS-Exploits für Websites verhindern, die es Benutzern ermöglichen, Dateien hochzuladen und zu teilen.

Beispielsweise ein Benutzer, der versucht, ein Bild herunterzuladen, aber es als ein anderer Content-Type wie eine ausführbare Datei behandelt wird, was potenziell schädlich sein könnte. Dieser Header gilt auch für das Herunterladen von Browser-Erweiterungen. Der einzige gültige Wert für diesen Header ist nosniff.

{
  key: 'X-Content-Type-Options',
  value: 'nosniff'
}

Referrer-Policy

Dieser Header steuert, wie viele Informationen der Browser beim Navigieren von der aktuellen Website (Herkunft) zu einer anderen einschließt.

{
  key: 'Referrer-Policy',
  value: 'origin-when-cross-origin'
}

Content-Security-Policy

Erfahren Sie mehr über das Hinzufügen einer Content-Sicherheitsrichtlinie zu Ihrer Anwendung.

Versionsverlauf

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