Headers.set() — Methode · JavaScript-Referenz

Signatur

Headers.prototype.set(name, value)

Beschreibung

Die Methode set() der Headers-Schnittstelle legt für einen Header-Namen genau einen Wert fest. Gibt es den Header schon, werden alle bisherigen Werte ersetzt. Gibt es ihn noch nicht, wird er angelegt. Genau darin liegt der Unterschied zu Headers.prototype.append(): append() hängt einen weiteren Wert an einen vorhandenen Header an, und die Werte werden dann durch , verbunden.

Header-Namen unterscheiden nicht zwischen Groß- und Kleinschreibung. set("Content-Type", …) und set("content-type", …) betreffen denselben Eintrag. Intern und beim Durchlaufen mit einer Schleife werden die Namen kleingeschrieben. Vom Wert entfernt der Browser führende und abschließende Leerzeichen, Tabs und Zeilenumbrüche.

Typische Einsatzfälle sind das Setzen von Authorization-, Content-Type- oder eigenen X--Headern, bevor eine fetch()-Anfrage gesendet wird. Außerdem können Sie damit gezielt Header in Service Workern oder Middleware überschreiben, etwa auf einer Kopie von response.headers.

Ob set() erlaubt ist, hängt vom Guard des Headers-Objekts ab. Bei Objekten mit dem Guard immutable wirft der Aufruf einen TypeError. Das betrifft zum Beispiel response.headers einer Antwort von fetch(). Verbotene Header wie Host oder Cookie werden im Browser bei Anfragen stillschweigend ignoriert.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des HTTP-Headers, zum Beispiel `"Content-Type"`. Groß- und Kleinschreibung spielen keine Rolle. Ein ungültiger Header-Name führt zu einem `TypeError`.
$value Pflicht	string		Neuer Wert des Headers. Andere Typen werden in einen String umgewandelt. Führende und abschließende Leerzeichen werden entfernt. Enthält der Wert ungültige Zeichen, zum Beispiel Zeilenumbrüche mitten im Wert, wird ein `TypeError` geworfen.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode gibt nichts zurück. Sie ändert das Headers-Objekt direkt, deshalb lassen sich Aufrufe nicht verketten.

Beispiele

Header anlegen und überschreiben

const headers = new Headers();

headers.set('Content-Type', 'text/plain');
console.log(headers.get('content-type'));

// Überschreibt den bestehenden Wert
headers.set('Content-Type', 'application/json');
console.log(headers.get('Content-Type'));

text/plain application/json

Unterschied zwischen set() und append()

const headers = new Headers();

headers.append('Accept', 'text/html');
headers.append('Accept', 'application/json');
console.log(headers.get('Accept'));

// set() ersetzt ALLE bisherigen Werte
headers.set('Accept', 'application/xml');
console.log(headers.get('Accept'));

text/html, application/json application/xml

Authentifizierte fetch-Anfrage mit JSON-Body

const sendeDaten = async (token, daten) => {
  const headers = new Headers();
  headers.set('Authorization', `Bearer ${token}`);
  headers.set('Content-Type', 'application/json');
  headers.set('X-Request-Id', crypto.randomUUID());

  const response = await fetch('https://api.example.com/items', {
    method: 'POST',
    headers,
    body: JSON.stringify(daten)
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

sendeDaten('abc123', { name: 'Test' }).then(console.log).catch(console.error);

Antwort-Header im Service Worker ändern

self.addEventListener('fetch', (event) => {
  event.respondWith((async () => {
    const original = await fetch(event.request);
    // original.headers ist immutable, deshalb eine Kopie anlegen
    const headers = new Headers(original.headers);
    headers.set('Cache-Control', 'no-store');
    headers.set('X-Served-By', 'service-worker');

    return new Response(original.body, {
      status: original.status,
      statusText: original.statusText,
      headers
    });
  })());
});

// Wichtig · Fallstricke

Unveränderliche Header: response.headers einer Antwort von fetch() und die Header von Request-Objekten im Service Worker sind unveränderlich (Guard immutable). Ein set()-Aufruf darauf wirft einen TypeError. Legen Sie vorher mit new Headers(original) eine Kopie an.
Verbotene Header: Im Browser werden verbotene Anfrage-Header wie Host, Cookie, Origin, Referer, Content-Length oder Sec-* stillschweigend ignoriert. Es gibt dabei keinen Fehler. Bei Anfragen mit mode: 'no-cors' sind nur CORS-sichere Header wie Accept, Accept-Language, Content-Language und bestimmte Content-Type-Werte erlaubt.
Set-Cookie: set('Set-Cookie', …) ersetzt alle vorhandenen Cookies. Wenn Sie mehrere Cookies setzen wollen, etwa in Node.js oder in Edge-Laufzeitumgebungen, verwenden Sie append(). Zum Auslesen dient getSetCookie().
CORS-Preflight: Eigene Header wie X-Request-Id oder Authorization lösen bei Anfragen an einen anderen Ursprung einen Preflight-Request aus. Der Server muss diese Header über Access-Control-Allow-Headers erlauben.
Sicherheit: Übernehmen Sie Benutzereingaben niemals ungeprüft in Header-Werte. Zeilenumbrüche werden zwar abgelehnt, sensible Header wie Authorization sollten aber nur aus vertrauenswürdigen Quellen kommen.
Kompatibilität: Unterstützt in allen modernen Browsern (seit etwa 2015/2016), in Web Workern, in Node.js ab Version 18 (globales fetch), in Deno und in Bun. Der Internet Explorer unterstützt es nicht.

Siehe auch

Headers Headers.append() Headers.get() Headers.has() Headers.delete() Request Response