HTTP-Header

Headers ermöglichen es Ihnen, benutzerdefinierte HTTP-Header in der Antwort auf eine eingehende Anfrage für einen bestimmten Pfad zu setzen.

Um benutzerdefinierte HTTP-Header zu setzen, können Sie den headers-Schlüssel 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 zurückgibt:

source ist das Muster des eingehenden Anfragepfads.
headers ist ein Array von Response-Header-Objekten mit den Eigenschaften key und value.
basePath: false oder undefined - wenn false, wird das basePath bei der Übereinstimmung nicht berücksichtigt, kann nur für externe Rewrites verwendet werden.
locale: false oder undefined - gibt an, ob das Locale bei der Übereinstimmung 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.

Headers werden vor dem Dateisystem überprüft, das Seiten und Dateien in /public umfasst.

Wenn zwei Header denselben Pfad abgleichen und denselben Header-Schlüssel setzen, überschreibt der letzte Header-Schlüssel den ersten. Mit den folgenden Headern führt der Pfad /hello dazu, dass der Header x-hello den Wert world hat, da der letzte 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',
          },
        ],
      },
    ]
  },
}

Pfadabgleich

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

next.config.js

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

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 abgeglichen:

next.config.js

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

Regex-Pfadabgleich

Um einen Regex-Pfad abzugleichen, können Sie den Regex in Klammern nach einem Parameter einschließen, z.B. wird /blog/:slug(\\d{1,}) mit /blog/123 abgeglichen, 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 den Regex-Pfadabgleich verwendet. Wenn sie in der source als nicht-spezielle Werte verwendet werden, müssen sie durch Voranstellen von \\ escaped werden:

next.config.js

module.exports = {
  async headers() {
    return [
      {
        // dies gleicht `/english(default)/something` ab
        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 diese Felder 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 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 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: 'hello',
          },
        ],
      },
      // 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: 'hello',
          },
        ],
      },
      // wenn die Quelle, der Query und der Cookie übereinstimmen,
      // wird der Header `x-authorized` angewendet
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // der Seitenwert wird nicht in den Header-Schlüssel/Werten verfügbar sein,
            // da der Wert bereitgestellt wird und keine benannte Erfassungsgruppe verwendet wird, 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

Wenn Sie basePath-Unterstützung mit Headern verwenden, wird jede source automatisch mit dem basePath präfixiert, 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

Wenn Sie i18n-Unterstützung mit Headern verwenden, wird jede source automatisch präfixiert, um die konfigurierten locales zu handhaben, es sei denn, Sie fügen locale: false zum Header hinzu. Wenn locale: false verwendet wird, müssen Sie der source ein Locale voranstellen, damit sie korrekt abgeglichen werden kann.

next.config.js

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

  async headers() {
    return [
      {
        source: '/with-locale', // handhabt automatisch alle Locales
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // handhabt Locales nicht automatisch, da locale: false gesetzt ist
        source: '/nl/with-locale-manual',
        locale: false,
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // dies gleicht '/' ab, da `en` das defaultLocale ist
        source: '/en',
        locale: false,
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // dies wird zu /(en|fr|de)/(.*) konvertiert, daher wird es nicht die obersten
        // `/` oder `/fr`-Routen wie /:path* abgleichen
        source: '/(.*)',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

Cache-Control

Sie können Cache-Control-Header nicht in next.config.js für Seiten oder Assets setzen, da diese Header in der Produktion überschrieben werden, um sicherzustellen, dass Antworten und statische Assets effektiv zwischengespeichert werden.

Wenn Sie den Cache einer Seite, die statisch generiert wurde, erneut validieren müssen, können Sie dies tun, indem Sie die revalidate-Eigenschaft in der getStaticProps-Funktion der Seite setzen.

Sie können den Cache-Control-Header in Ihren API-Routen setzen, indem Sie die Methode res.setHeader verwenden:

import type { NextApiRequest, NextApiResponse } from 'next'

type ResponseData = {
  message: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<ResponseData>
) {
  res.setHeader('Cache-Control', 's-maxage=86400')
  res.status(200).json({ message: 'Hello from Next.js!' })
}

export default function handler(req, res) {
  res.setHeader('Cache-Control', 's-maxage=86400')
  res.status(200).json({ message: 'Hello from Next.js!' })
}

Optionen

CORS

Cross-Origin Resource Sharing (CORS) ist eine Sicherheitsfunktion, die es Ihnen ermöglicht, zu steuern, welche Websites auf Ihre Ressourcen zugreifen können. Sie können den Access-Control-Allow-Origin-Header setzen, um einer bestimmten Origin den Zugriff auf Ihre API-Endpunkte zu erlauben.

async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          {
            key: "Access-Control-Allow-Origin",
            value: "*", // Setzen Sie Ihre Origin
          },
          {
            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, das es Browsern ermöglicht, proaktiv Domain-Namen-Auflösungen für externe Links, Bilder, CSS, JavaScript und mehr durchzuführen. Dieses Prefetching erfolgt im Hintergrund, sodass die DNS-Auflösung wahrscheinlich abgeschlossen ist, wenn die referenzierten Elemente benötigt werden. Dies reduziert die Latenz, wenn der Benutzer auf einen Link klickt.

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

Strict-Transport-Security

Dieser Header informiert Browser, dass sie nur über HTTPS darauf zugreifen sollten, anstatt über HTTP. Mit der folgenden Konfiguration verwenden alle aktuellen und zukünftigen Subdomains HTTPS für einen max-age von 2 Jahren. 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 notwendig, 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 Site innerhalb eines iframe angezeigt werden darf. Dies kann gegen Clickjacking-Angriffe schützen.

Dieser Header wurde durch die CSP-Option frame-ancestors ersetzt, die in modernen Browsern besser unterstützt wird (siehe Content Security Policy für Konfigurationsdetails).

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

Permissions-Policy

Dieser Header ermöglicht es Ihnen, zu steuern, welche Funktionen und APIs im Browser verwendet werden können. Er wurde früher als Feature-Policy bezeichnet.

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

X-Content-Type-Options

Dieser Header verhindert, dass der Browser versucht, den Typ des Inhalts 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.

Zum Beispiel könnte ein Benutzer versuchen, ein Bild herunterzuladen, aber es wird als ein anderer Content-Type wie eine ausführbare Datei behandelt, die bösartig 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 einbezieht, wenn er von der aktuellen Website (Origin) zu einer anderen navigiert.

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

Content-Security-Policy

Erfahren Sie mehr über das Hinzufügen einer Content Security Policy zu Ihrer Anwendung.

Versionsverlauf

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

Header-Überschreibungsverhalten

Pfadabgleich

Wildcard-Pfadabgleich

Regex-Pfadabgleich

Header mit basePath-Unterstützung

Header mit i18n-Unterstützung

Cache-Control

Optionen

CORS

X-DNS-Prefetch-Control

Strict-Transport-Security

X-Frame-Options

Permissions-Policy

X-Content-Type-Options

Referrer-Policy

Content-Security-Policy

Versionsverlauf

On this page