Request.headers — Eigenschaft · JavaScript-Referenz

Signatur

Request.headers

Beschreibung

Die Eigenschaft headers einer Request-Instanz liefert das zugehörige Headers-Objekt. Darüber lassen sich die HTTP-Header der Anfrage lesen, zum Beispiel Content-Type, Authorization oder Accept. Das kommt vor allem in Service Workern, in Middleware-Schichten (Next.js, Cloudflare Workers, Deno, Node.js) und in eigenen fetch-Wrappern vor.

Schreibgeschützt bedeutet: Man kann der Eigenschaft kein neues Objekt zuweisen. Das Headers-Objekt selbst lässt sich dagegen oft mit set(), append() oder delete() ändern. Ob das erlaubt ist, hängt von seinem internen Guard ab. Bei selbst erzeugten Anfragen (new Request()) ist das Ändern erlaubt. Verbotene Header wie Host, Cookie oder Content-Length werden dabei aber ohne Fehlermeldung ignoriert. Bei mode: "no-cors" sind nur CORS-sichere Header erlaubt (Accept, Accept-Language, Content-Language und Content-Type mit eingeschränkten Werten).

Die Header einer Anfrage, die ein Service Worker in event.request erhält, lassen sich nicht ändern. Für geänderte Header erzeugt man eine neue Anfrage: new Request(original, { headers }). Header-Namen sind unabhängig von Groß- und Kleinschreibung. Beim Durchlaufen des Objekts werden sie kleingeschrieben und sortiert ausgegeben.

Rückgabewert

Typ

Headers

Beschreibung

Das Headers-Objekt der Anfrage. Es ist iterierbar und bietet die Methoden get(), has(), set(), append(), delete(), entries() und forEach().

Beispiele

Header einer selbst erstellten Anfrage lesen

const request = new Request('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Request-Id': 'abc-123'
  },
  body: JSON.stringify({ name: 'Ada' })
});

console.log(request.headers.get('content-type'));
console.log(request.headers.has('X-Request-Id'));
console.log(request.headers.get('Authorization'));

application/json true null

Alle Header durchlaufen und als Objekt ausgeben

const request = new Request('/api/data', {
  headers: new Headers([
    ['Accept', 'application/json'],
    ['Accept-Language', 'de-DE'],
    ['X-Client', 'web']
  ])
});

// Headers ist iterierbar – Namen werden kleingeschrieben
const plain = Object.fromEntries(request.headers);
console.log(plain);

{ accept: 'application/json', 'accept-language': 'de-DE', 'x-client': 'web' }

Service Worker: Anfrage mit zusätzlichem Header weiterleiten

// sw.js
self.addEventListener('fetch', (event) => {
  const { request } = event;
  if (!request.url.startsWith(self.location.origin + '/api/')) return;

  // event.request.headers ist unveränderlich → Kopie anlegen
  const headers = new Headers(request.headers);
  headers.set('X-From-Service-Worker', '1');

  const modified = new Request(request, { headers });
  event.respondWith(fetch(modified));
});

Token in einem fetch-Wrapper ergänzen

const authFetch = async (input, init = {}) => {
  const request = new Request(input, init);
  if (!request.headers.has('Authorization')) {
    request.headers.set('Authorization', `Bearer ${localStorage.getItem('token')}`);
  }
  const response = await fetch(request);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

const users = await authFetch('/api/users');
console.log(users.length);

// Wichtig · Fallstricke

Nicht zuweisbar: request.headers = new Headers() hat keine Wirkung und löst im Strict Mode einen TypeError aus. Einzelne Header ändert man stattdessen mit request.headers.set().
Unveränderliche Header: Bei event.request im Service Worker lösen set(), append() und delete() einen TypeError aus. Abhilfe schafft new Request(req, { headers }).
Verbotene Header: Header wie Cookie, Host, Origin, Referer, Content-Length oder solche mit dem Präfix Sec- bzw. Proxy- kann ein Skript im Browser nicht setzen. Sie werden ohne Fehlermeldung verworfen. In Node.js und Deno gelten teils andere Regeln.
no-cors: Mit mode: "no-cors" werden nicht CORS-sichere Header ohne Fehlermeldung entfernt.
Mehrfache Werte: get() fasst mehrere Werte zu einer kommagetrennten Zeichenkette zusammen. Set-Cookie ist in Anfragen nicht relevant. In Antworten liest man es über getSetCookie().
Sicherheit: Header, die von außen kommen, etwa in Middleware, sind nicht vertrauenswürdig. X-Forwarded-For und ähnliche Header können gefälscht sein.
Die Eigenschaft wird von allen modernen Browsern unterstützt. In Node.js ist Request ab Version 18 ohne Import verfügbar.

Siehe auch

Headers Request Response.headers Headers.prototype.get() Headers.prototype.set() PaymentRequest.payerName