new Headers() — Methode · JavaScript-Referenz

Signatur

new Headers(init)

Beschreibung

Mit new Headers() erzeugst du eine Sammlung von HTTP-Headern, die du an fetch(), new Request() oder new Response() übergeben kannst. Anders als ein einfaches Objekt behandelt Headers Header-Namen ohne Beachtung der Groß-/Kleinschreibung, prüft Namen und Werte auf Gültigkeit und bietet Methoden wie append(), set(), get(), has() und delete().

Das optionale Argument init legt die Anfangswerte fest. Erlaubt sind ein einfaches Objekt ({ "Content-Type": "application/json" }), ein Array aus Name-Wert-Paaren ([["Accept", "text/html"]]) oder ein bestehendes Headers-Objekt, das dabei kopiert wird. Arrays sind nützlich, wenn derselbe Header mehrfach vorkommen soll.

Ein per Konstruktor erzeugtes Objekt hat den Guard none und ist damit frei veränderbar. Headers, die du über response.headers oder request.headers erhältst, können dagegen schreibgeschützt sein oder bestimmte Header verbieten. Wenn du sie ändern willst, kopierst du sie mit new Headers(response.headers).

Parameter

Name	Typ	Default	Beschreibung
$init	Headers \| Record<string, string> \| Array<[string, string]>		Anfangswerte: ein Objekt mit Header-Namen als Schlüsseln, ein Array aus `[name, wert]`-Paaren oder ein vorhandenes `Headers`-Objekt, das kopiert wird.

Rückgabewert

Typ

Headers

Beschreibung

Ein neues, veränderbares Headers-Objekt.

Beispiele

Headers aus einem Objekt erzeugen und mit fetch nutzen

const headers = new Headers({
  'Content-Type': 'application/json',
  Authorization: 'Bearer abc123'
});

console.log(headers.get('content-type')); // Groß-/Kleinschreibung egal

const res = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Anna' })
});

application/json

Array-Form mit doppeltem Header

const headers = new Headers([
  ['Accept', 'text/html'],
  ['Accept', 'application/json']
]);

console.log(headers.get('Accept'));
for (const [name, value] of headers) {
  console.log(`${name}: ${value}`);
}

text/html, application/json accept: text/html, application/json

Antwort-Header kopieren und ändern

const res = await fetch('/daten.json');

// response.headers ist schreibgeschützt, deshalb eine Kopie anlegen
const kopie = new Headers(res.headers);
kopie.set('X-Cache', 'HIT');

const neueAntwort = new Response(res.body, {
  status: res.status,
  headers: kopie
});
console.log(neueAntwort.headers.get('x-cache'));

HIT

Leeres Objekt schrittweise befüllen

const headers = new Headers();
headers.append('X-Request-Id', crypto.randomUUID());
headers.set('Accept-Language', 'de-DE');

console.log(headers.has('accept-language'));
console.log(Object.fromEntries(headers));

true { 'accept-language': 'de-DE', 'x-request-id': '…' }

// Wichtig · Fallstricke

Ungültige Header-Namen (z. B. mit Leerzeichen oder Umlauten) oder Werte mit Zeilenumbrüchen führen zu einem TypeError. Das Gleiche gilt, wenn ein Array-Eintrag nicht genau zwei Elemente hat.
Beim Iterieren werden die Namen kleingeschrieben und sortiert ausgegeben. Mehrfach vorhandene Werte fasst get() mit ", " zusammen. Ausnahme ist Set-Cookie: Diese Werte liest du mit getSetCookie() einzeln aus.
Verbotene Header wie Host, Cookie oder Content-Length kannst du zwar setzen, der Browser ignoriert sie bei fetch() aber stillschweigend.
Bei CORS-Anfragen lösen eigene Header (z. B. Authorization oder X-*) einen Preflight-Request aus.
Unterstützung: in allen modernen Browsern vorhanden, global in Node.js seit Version 18 (davor über node-fetch). In Web Workern ebenfalls verfügbar.

Siehe auch

Headers Headers.prototype.append() Headers.prototype.set() Headers.prototype.get() Request Response