Headers.append() — Methode · JavaScript-Referenz

Signatur

Headers.prototype.append(name, value)

Beschreibung

append() hängt einen Wert an einen HTTP-Header in einem Headers-Objekt an. Gibt es den Header noch nicht, wird er angelegt. Gibt es ihn schon, wird der neue Wert zusätzlich gespeichert. Beim Auslesen mit get() kommen die Werte dann als eine Zeichenkette zurück, getrennt durch Komma und Leerzeichen (", "). Genau hier liegt der Unterschied zu set(): set() ersetzt alle bisherigen Werte.

Sinnvoll ist append() vor allem bei Headern, die mehrere Werte haben dürfen, zum Beispiel Accept, Accept-Language oder Cache-Control. Das gilt auch, wenn man Header Schritt für Schritt zusammenbaut, bevor man sie an fetch() oder new Request() übergibt.

Bei Header-Namen spielt die Groß- und Kleinschreibung keine Rolle. Intern werden sie kleingeschrieben gespeichert. Am Anfang und Ende des Werts entfernt die Methode Leerzeichen, Tabs und Zeilenumbrüche. Ungültige Namen oder Werte, etwa mit Zeilenumbrüchen in der Mitte, lösen einen TypeError aus.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des HTTP-Headers, z. B. `"Accept"`. Groß- und Kleinschreibung spielt keine Rolle.
$value Pflicht	string		Wert, der angehängt werden soll. Andere Typen werden in eine Zeichenkette umgewandelt.

Beispiele

Header neu anlegen und Werte anhängen

const headers = new Headers();

headers.append('Accept', 'application/json');
headers.append('Accept', 'text/plain');

console.log(headers.get('accept'));

application/json, text/plain

Unterschied zwischen append() und set()

const headers = new Headers({ 'Cache-Control': 'no-cache' });

headers.append('Cache-Control', 'no-store');
console.log(headers.get('Cache-Control'));

// set() ersetzt alle bisherigen Werte
headers.set('Cache-Control', 'max-age=60');
console.log(headers.get('Cache-Control'));

no-cache, no-store max-age=60

Header für einen fetch-Aufruf zusammenbauen

const loadUser = async (id, token) => {
  const headers = new Headers();
  headers.append('Accept', 'application/json');
  headers.append('Accept-Language', 'de-DE');
  if (token) {
    headers.append('Authorization', `Bearer ${token}`);
  }

  const response = await fetch(`/api/users/${id}`, { headers });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

loadUser(42, 'abc123').then(user => console.log(user));

Mehrere Set-Cookie-Header (z. B. in Node.js oder einem Service Worker)

const headers = new Headers();
headers.append('Set-Cookie', 'session=xyz; HttpOnly');
headers.append('Set-Cookie', 'theme=dark');

// getSetCookie() liefert die Werte einzeln, ohne sie zusammenzufassen
console.log(headers.getSetCookie());

[ 'session=xyz; HttpOnly', 'theme=dark' ]

// Wichtig · Fallstricke

Werte werden verdoppelt: Wer append() mehrmals mit demselben Wert aufruft, zum Beispiel in einer Schleife oder bei einem erneuten Versuch, bekommt Werte wie "application/json, application/json". Soll ein Header genau einen Wert haben, nimmt man set().
Schreibgeschützte Header-Objekte: Die Header von Response-Objekten aus fetch() sind unveränderlich (guard immutable). Ein Aufruf von append() löst dann einen TypeError aus. Zum Ändern legt man zuerst eine Kopie an: new Headers(response.headers).
Verbotene Header: Im Browser werden manche Header einer Anfrage stillschweigend ignoriert, zum Beispiel Host, Cookie, Content-Length und Origin. Bei mode: 'no-cors' sind nur Header erlaubt, die als CORS-sicher gelten (CORS-safelisted).
CORS: Eigene Header wie Authorization oder X-* lösen bei Anfragen an andere Ursprünge eine Preflight-Anfrage aus. Der Server muss diese Header in Access-Control-Allow-Headers freigeben.
Set-Cookie: Mit get() kommen die Werte zusammengefasst zurück. Die einzelnen Werte liefert getSetCookie() (in neueren Browsern und in Node.js 19.7+).
Kompatibilität: Funktioniert in allen modernen Browsern, in Web Workern und in Node.js ab Version 18, wo fetch global verfügbar ist. Der Internet Explorer unterstützt die Methode nicht.

Siehe auch

Headers Headers.set() Headers.get() Headers.delete() Headers.has() Headers.getSetCookie() Request