Cache-Control header

Der HTTP Cache-Control-Header enthält Direktiven (Anweisungen) in sowohl Anfragen als auch Antworten, die das Caching in Browsern und geteilten Caches (z.B. Proxys, CDNs) steuern.

Syntax

Cache-Control: <directive>, <directive>, ...

Cache-Direktiven folgen diesen Regeln:

• Caching-Direktiven sind nicht case-sensitiv. Jedoch wird empfohlen, Kleinschreibung zu verwenden, da einige Implementierungen Großbuchstaben-Direktiven nicht erkennen.
• Mehrere Direktiven sind erlaubt und müssen durch Kommas getrennt werden (z.B. Cache-control: max-age=180, public).
• Einige Direktiven haben ein optionales Argument. Wenn ein Argument angegeben ist, wird es durch ein Gleichheitszeichen (=) vom Direktivnamen getrennt. Typischerweise sind Argumente für die Direktiven Ganzzahlen und sind daher nicht in Anführungszeichen eingeschlossen (z.B. Cache-control: max-age=12).

Cache-Direktiven

Die folgende Tabelle listet die standardmäßigen Cache-Control-Direktiven auf:

Hinweis: Überprüfen Sie die Kompatibilitätsübersicht bezüglich ihrer Unterstützung; Benutzeragenten, die sie nicht erkennen, sollten sie ignorieren.

Vokabular

Dieser Abschnitt definiert die in diesem Dokument verwendeten Begriffe, von denen einige aus der Spezifikation stammen.

(HTTP) Cache

Implementierung, die Anfragen und Antworten speichert, um sie bei nachfolgenden Anfragen wiederzuverwenden. Es kann entweder ein geteilter Cache oder ein privater Cache sein.

Geteilter Cache

Cache, der zwischen dem Ursprungsserver und den Clients existiert (z.B. Proxy, CDN). Er speichert eine einzelne Antwort und verwendet sie bei mehreren Nutzern wieder – daher sollten Entwickler vermeiden, personalisierte Inhalte im geteilten Cache zu speichern.

Privater Cache

Cache, der im Client existiert. Er wird auch als lokaler Cache oder Browser-Cache bezeichnet. Er kann personalisierte Inhalte für einen einzelnen Nutzer speichern und wiederverwenden.

Antwort speichern

Eine Antwort in Caches speichern, wenn die Antwort zwischenspeicherbar ist. Die zwischengespeicherte Antwort wird jedoch nicht immer so wie sie ist wiederverwendet. (Normalerweise bedeutet "cache", eine Antwort zu speichern.)

Antwort wiederverwenden

Zwischengespeicherte Antworten für nachfolgende Anfragen wiederverwenden.

Antwort erneut validieren

Den Ursprungsserver fragen, ob die gespeicherte Antwort noch frisch ist. Normalerweise erfolgt die Wiedervalidierung durch eine bedingte Anfrage.

Frische Antwort

Zeigt an, dass die Antwort frisch ist. Dies bedeutet normalerweise, dass die Antwort für nachfolgende Anfragen wiederverwendet werden kann, abhängig von den Anfragedirektiven.

Alte Antwort

Zeigt an, dass die Antwort eine abgestandene Antwort ist. Dies bedeutet normalerweise, dass die Antwort nicht so wie sie ist wiederverwendet werden kann. Die Cache-Speicherung muss abgestandene Antworten nicht sofort entfernen, da eine Wiedervalidierung die Antwort von abgestanden zu frisch ändern könnte.

Alter

Die Zeit seit Erstellung einer Antwort. Sie ist ein Kriterium dafür, ob eine Antwort frisch oder abgestanden ist.

Direktiven

Dieser Abschnitt listet direktiven auf, die das Caching beeinflussen — sowohl für Antwortdirektiven als auch Anfragedirektiven.

Antwortdirektiven

max-age

Die max-age=N-Antwortdirektive zeigt an, dass die Antwort N Sekunden nach der Erzeugung der Antwort frisch bleibt.

Cache-Control: max-age=604800

Zeigt an, dass Caches diese Antwort speichern und für nachfolgende Anfragen wiederverwenden können, solange sie frisch ist.

Beachten Sie, dass max-age nicht die abgelaufene Zeit seit Empfang der Antwort ist; es ist die vergangene Zeit seit der Antworterstellung auf dem Ursprungsserver. Wenn andere Caches — auf dem vom Netzwerk zurückgelegten Weg der Antwort — die Antwort für 100 Sekunden speichern (angezeigt durch das Age-Antwortheader-Feld), dann würde der Browser-Cache 100 Sekunden von seiner Frischezeit abziehen.

Wenn der max-age-Wert negativ ist (zum Beispiel -1) oder keine Ganzzahl (zum Beispiel 3599.99), dann ist das Caching-Verhalten nicht spezifiziert. Caches werden ermutigt, den Wert so zu behandeln, als ob er 0 wäre (dies wird im Abschnitt Berechnung der Frischlifetime der HTTP-Spezifikation erwähnt).

Cache-Control: max-age=604800
Age: 100

s-maxage

Die s-maxage-Antwortdirektive gibt an, wie lange die Antwort in einem geteilten Cache frisch bleibt. Die s-maxage-Direktive wird von privaten Caches ignoriert und überschreibt den durch die max-age-Direktive oder den Expires-Header spezifizierten Wert für geteilte Caches, wenn sie vorhanden sind.

Cache-Control: s-maxage=604800

no-cache

Die no-cache-Antwortdirektive zeigt an, dass die Antwort in Caches gespeichert werden kann, aber die Antwort mit dem Ursprungsserver vor jeder Wiederverwendung validiert werden muss, selbst wenn der Cache vom Ursprungsserver getrennt ist.

Cache-Control: no-cache

Wenn Sie möchten, dass Caches beim Wiederverwenden gespeicherter Inhalte immer nach Aktualisierungen suchen, ist no-cache die zu verwendende Direktive. Dies geschieht, indem Caches angewiesen werden, jede Anfrage beim Ursprungsserver erneut zu validieren.

Beachten Sie, dass no-cache nicht "nicht cachen" bedeutet. no-cache erlaubt Caches, eine Antwort zu speichern, verlangt jedoch von ihnen, sie vor der Wiederverwendung erneut zu validieren. Wenn die von Ihnen gewünschte Bedeutung von "nicht cachen" tatsächlich "nicht speichern" ist, dann ist no-store die zu verwendende Direktive.

Die must-revalidate-Antwortdirektive gibt an, dass die Antwort in Caches gespeichert und wiederverwendet werden kann, solange sie frisch ist. Wenn die Antwort abgestanden wird, muss sie vor der Wiederverwendung mit dem Ursprungsserver validiert werden.

Typischerweise wird must-revalidate zusammen mit max-age verwendet.

Cache-Control: max-age=604800, must-revalidate

HTTP erlaubt es Caches, abgestandene Antworten wiederzuverwenden, wenn sie vom Ursprungsserver getrennt sind. must-revalidate ist eine Möglichkeit, dies zu verhindern - entweder wird die gespeicherte Antwort mit dem Ursprungsserver erneut validiert oder eine 504 (Gateway Timeout)-Antwort wird generiert.

proxy-revalidate

Die proxy-revalidate-Antwortdirektive ist das Gegenstück zu must-revalidate, aber speziell nur für geteilte Caches.

no-store

Die no-store-Antwortdirektive gibt an, dass keine Caches jeglicher Art (privat oder geteilt) diese Antwort speichern sollten.

Cache-Control: no-store

private

Die private-Antwortdirektive zeigt an, dass die Antwort nur in einem privaten Cache (z.B. lokale Caches in Browsern) gespeichert werden kann.

Cache-Control: private

Sie sollten die private-Direktive für benutzerpersonalisierte Inhalte hinzufügen, insbesondere für Antworten, die nach der Anmeldung erhalten wurden, und für Sitzungen, die über Cookies verwaltet werden.

Wenn Sie vergessen, private zu einer Antwort mit personalisierten Inhalten hinzuzufügen, könnte diese Antwort im geteilten Cache gespeichert und möglicherweise für mehrere Benutzer wiederverwendet werden, was zu einem Leck von persönlichen Informationen führen kann.

public

Die public-Antwortdirektive zeigt an, dass die Antwort in einem geteilten Cache gespeichert werden kann. Antworten auf Anfragen mit Authorization-Header-Feldern dürfen nicht in einem geteilten Cache gespeichert werden; jedoch wird die public-Direktive dazu führen, dass solche Antworten in einem geteilten Cache gespeichert werden.

Cache-Control: public

Im Allgemeinen senden Browser bei Zugriffen, die durch Basis- oder Digest-Authentifizierung gesichert sind, Anfragen mit dem Authorization-Header. Dies bedeutet, dass die Antwort bei eingeschränktem Zugriff (für Benutzer mit Konten) in ihrem Kern nicht für geteilte Caches verfügbar ist, selbst wenn sie max-age enthält.

Sie können die public-Direktive verwenden, um diese Einschränkung aufzuheben.

Cache-Control: public, max-age=604800

Beachten Sie, dass s-maxage oder must-revalidate diese Einschränkung ebenfalls aufheben.

Wenn eine Anfrage keinen Authorization-Header hat, oder Sie bereits s-maxage oder must-revalidate in der Antwort verwenden, dann brauchen Sie public nicht zu verwenden.

must-understand

Die must-understand-Antwortdirektive zeigt an, dass ein Cache die Antwort nur speichern sollte, wenn er die Anforderungen an das Caching basierend auf dem Statuscode versteht.

must-understand sollte mit no-store für das Fallback-Verhalten gekoppelt werden.

Cache-Control: must-understand, no-store

Wenn ein Cache must-understand nicht unterstützt, wird es ignoriert. Wenn no-store ebenfalls vorhanden ist, wird die Antwort nicht gespeichert.

Wenn ein Cache must-understand unterstützt, speichert es die Antwort mit einem Verständnis der Caching-Anforderungen basierend auf dessen Statuscode.

no-transform

Einige Vermittler transformieren Inhalte aus verschiedenen Gründen. Zum Beispiel konvertieren einige Bilder, um die Übertragungsgröße zu reduzieren. In einigen Fällen ist dies für den Inhaltsanbieter unerwünscht.

no-transform gibt an, dass kein Vermittler (egal, ob er einen Cache implementiert oder nicht) die Antwortinhalte transformieren sollte.

immutable

Die immutable-Antwortdirektive gibt an, dass die Antwort nicht aktualisiert wird, solange sie frisch ist.

Cache-Control: public, max-age=604800, immutable

Eine moderne bewährte Praxis für statische Ressourcen beinhaltet, Versionsnummern/Hashes in deren URLs zu integrieren, während die Ressourcen niemals geändert werden — stattdessen werden sie bei Bedarf mit neueren Versionen aktualisiert, die neue Versionsnummern/Hashes enthalten, sodass ihre URLs unterschiedlich sind. Das wird als Cache-Busting-Muster bezeichnet.

<script src="https://example.com/react.0.0.0.js"></script>

Wenn ein Benutzer den Browser neu lädt, sendet der Browser bedingte Anfragen zur Validierung an den Ursprungsserver. Aber es ist nicht notwendig, solche Arten von statischen Ressourcen erneut zu validieren, selbst wenn ein Benutzer den Browser neu lädt, weil sie niemals geändert werden. immutable teilt einem Cache mit, dass die Antwort unveränderlich ist, solange sie frisch ist, und vermeidet solche Arten von unnötigen bedingten Anfragen an den Server.

Wenn Sie ein Cache-Busting-Muster für Ressourcen verwenden und es auf eine lange max-age anwenden, können Sie auch immutable hinzufügen, um die Wiedervalidierung zu vermeiden.

stale-while-revalidate

Die stale-while-revalidate-Antwortdirektive gibt an, dass der Cache eine abgestandene Antwort wiederverwenden könnte, während er sie im Hintergrund validiert.

Cache-Control: max-age=604800, stale-while-revalidate=86400

Im obigen Beispiel ist die Antwort für 7 Tage (604800s) frisch. Nach 7 Tagen wird sie abgestanden, aber der Cache darf sie für Anfragen, die im folgenden Tag (86400s) gestellt werden, wiederverwenden, vorausgesetzt, dass sie die Antwort im Hintergrund validieren.

Die Wiedervalidierung wird den Cache wieder frisch machen, sodass es den Clients so erscheint, als wäre sie immer frisch während dieses Zeitraums — effektiv wird die Latenzstrafe der Wiedervalidierung vor ihnen verborgen.

Wenn während dieses Zeitraums keine Anfrage erfolgte, wird der Cache abgestanden und die nächste Anfrage wird normal validiert.

stale-if-error

Die stale-if-error-Antwortdirektive zeigt an, dass der Cache eine abgestandene Antwort wiederverwenden kann, wenn ein upstream Server einen Fehler generiert oder wenn der Fehler lokal generiert wird. Hier wird ein Fehler als jede Antwort mit einem Statuscode von 500, 502, 503 oder 504 betrachtet.

Cache-Control: max-age=604800, stale-if-error=86400

Im obigen Beispiel ist die Antwort für 7 Tage (604800s) frisch. Danach wird sie abgestanden, kann aber für weitere 1 Tag (86400s) verwendet werden, wenn ein Fehler auftritt.

Nach Ablauf des stale-if-error-Zeitraums erhält der Client jeden generierten Fehler.

Anfrage-Direktiven

no-cache

Die no-cache-Anfragedirektive fordert Caches auf, die Antwort mit dem Ursprungsserver zu validieren, bevor sie wiederverwendet wird.

Cache-Control: no-cache

no-cache ermöglicht es Clients, die aktuellste Antwort anzufordern, auch wenn der Cache eine frische Antwort hat.

Browser fügen Anfragen normalerweise no-cache hinzu, wenn Benutzer eine Seite erzwungen neu laden.

no-store

Die no-store-Anfragedirektive erlaubt es einem Client, Caches zu bitten, das Speichern der Anfrage und der entsprechenden Antwort zu vermeiden — selbst wenn die Antwort des Ursprungsservers zwischenspeicherbar wäre.

Cache-Control: no-store

max-age

Die max-age=N-Anfragedirektive zeigt an, dass der Client eine gespeicherte Antwort erlaubt, die auf dem Ursprungsserver innerhalb von N Sekunden generiert wurde — wobei N jede nicht negative Ganzzahl (einschließlich 0) sein kann.

Cache-Control: max-age=10800

Im obigen Fall, wenn die Antwort mit Cache-Control: max-age=10800 vor mehr als 3 Stunden (berechnet aus max-age und dem Age-Header) generiert wurde, könnte der Cache diese Antwort nicht wiederverwenden.

Viele Browser verwenden diese Direktive für Neuladen, wie unten erklärt.

Cache-Control: max-age=0

max-age=0 ist ein Workaround für no-cache, weil viele alte (HTTP/1.0) Cache-Implementierungen no-cache nicht unterstützen. Kürzlich verwenden Browser immer noch max-age=0 beim "Neuladen" — aus Gründen der Rückwärtskompatibilität — und alternativ verwenden sie no-cache für ein "erzwungenes Neuladen".

Wenn der max-age-Wert negativ ist (zum Beispiel -1) oder keine Ganzzahl (zum Beispiel 3599.99), dann ist das Caching-Verhalten nicht spezifiziert. Caches werden ermutigt, den Wert so zu behandeln, als ob er 0 wäre.

max-stale

Die max-stale=N-Anfragedirektive zeigt an, dass der Client eine gespeicherte Antwort erlaubt, die innerhalb von N Sekunden abgestanden ist. Wenn kein N-Wert angegeben ist, akzeptiert der Client eine abgestandene Antwort jeden Alters.

Cache-Control: max-stale=3600

Zum Beispiel zeigt eine Anfrage mit dem obigen Header an, dass der Browser eine abgestandene Antwort aus dem Cache akzeptiert, die innerhalb der letzten Stunde abgelaufen ist.

Clients können diesen Header verwenden, wenn der Ursprungsserver nicht verfügbar oder zu langsam ist und sie zwischengespeicherte Antworten akzeptieren können, selbst wenn sie ein wenig veraltet sind.

Beachten Sie, dass die meisten großen Browser Anfragen mit max-stale nicht unterstützen.

min-fresh

Die min-fresh=N-Anfragedirektive zeigt an, dass der Client eine gespeicherte Antwort erlaubt, die für mindestens N Sekunden frisch ist.

Cache-Control: min-fresh=600

Im obigen Fall, wenn die Antwort mit Cache-Control: max-age=3600 vor 51 Minuten in Caches gespeichert wurde, könnte der Cache diese Antwort nicht wiederverwenden.

Clients können diesen Header verwenden, wenn der Benutzer erfordert, dass die Antwort nicht nur frisch ist, sondern auch, dass sie für eine bestimmte Zeitspanne nicht aktualisiert wird.

Beachten Sie, dass die meisten großen Browser Anfragen mit min-fresh nicht unterstützen.

no-transform

Gleiche Bedeutung wie no-transform für eine Antwort, aber stattdessen für eine Anfrage.

only-if-cached

Der Client gibt an, dass eine bereits zwischengespeicherte Antwort zurückgegeben werden sollte. Wenn ein Cache eine gespeicherte Antwort hat, selbst eine abgestandene, wird sie zurückgegeben. Wenn keine zwischengespeicherte Antwort verfügbar ist, wird eine 504 Gateway Timeout-Antwort zurückgegeben.

stale-if-error

Die stale-if-error-Anfragedirektive zeigt an, dass der Browser daran interessiert ist, abgestandene Inhalte bei einem Fehler von einem beliebigen Zwischensever für einen bestimmten Ursprung zu erhalten. Dies wird von keinem Browser unterstützt (siehe Browser-Kompatibilität).

Anwendungsfälle

Speicherung verhindern

Wenn Sie nicht möchten, dass eine Antwort in Caches gespeichert wird, verwenden Sie die Direktive no-store.

Cache-Control: no-store

Beachten Sie, dass no-cache bedeutet "es kann gespeichert werden, aber nicht wiederverwenden, bevor es validiert wird" — daher ist es nicht dafür gedacht, eine Antwort daran zu hindern, gespeichert zu werden.

Cache-Control: no-cache

Theoretisch sollte bei widersprüchlichen Direktiven die restriktivste Direktive eingehalten werden. Daher ist das folgende Beispiel praktisch bedeutungslos, weil private, no-cache, max-age=0 und must-revalidate mit no-store in Konflikt stehen.

# conflicted
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
# equivalent to
Cache-Control: no-store

Caching statischer Ressourcen mit "Cache-Busting"

Wenn Sie statische Ressourcen mit Versionierungs-/Hashing-Mechanismen erstellen, ist das Hinzufügen einer Versionsnummer/eines Hashs zum Dateinamen oder zum Abfrage-String eine gute Möglichkeit, das Caching zu verwalten.

Zum Beispiel:

<!-- index.html -->
<script src="/assets/react.min.js"></script>
<img src="/assets/hero.png" width="900" height="400" />

Die Version der React-Bibliothek wird sich ändern, wenn Sie die Bibliothek aktualisieren, und hero.png wird sich auch ändern, wenn Sie das Bild bearbeiten. Daher sind diese schwer in einem Cache mit max-age zu speichern.

In einem solchen Fall könnten Sie die Caching-Bedürfnisse durch die Verwendung einer spezifischen, nummerierten Version der Bibliothek adressieren und den Hash des Bildes in seine URL einfügen.

<!-- index.html -->
<script src="/assets/react.0.0.0min.js"></script>
<img src="/assets/hero.png?hash=deadbeef" width="900" height="400" />

Sie können einen langen max-age-Wert und immutable hinzufügen, weil der Inhalt sich nie ändern wird.

# /assets/*
Cache-Control: max-age=31536000, immutable

Wenn Sie die Bibliothek aktualisieren oder das Bild bearbeiten, sollten neue Inhalte eine neue URL haben und die Caches werden nicht wiederverwendet. Das wird als "Cache-Busting"-Muster bezeichnet.

Verwenden Sie no-cache, um sicherzustellen, dass die HTML-Antwort selbst nicht zwischengespeichert wird. no-cache könnte eine Wiedervalidierung verursachen und der Client wird korrekt eine neue Version der HTML-Antwort und der statischen Ressourcen erhalten.

# /index.html
Cache-Control: no-cache

Hinweis: Wenn index.html unter einer Basis- oder Digest-Authentifizierung kontrolliert wird, werden Dateien unter /assets nicht im geteilten Cache gespeichert. Wenn die Dateien unter /assets/ für die Speicherung in einem geteilten Cache geeignet sind, benötigen Sie außerdem eine der folgenden Direktiven: public, s-maxage oder must-revalidate.

Immer aktuelle Inhalte

Für Inhalte, die dynamisch generiert werden oder die statisch, aber häufig aktualisiert werden, möchten Sie, dass ein Benutzer immer die aktuellste Version erhält.

Wenn Sie keinen Cache-Control-Header hinzufügen, weil die Antwort nicht zwischengespeichert werden soll, könnte das zu einem unerwarteten Ergebnis führen. Die Cache-Speicherung darf es heuristisch zwischenspeichern — daher sollten Sie, wenn Sie Anforderungen an das Caching haben, diese immer explizit im Cache-Control-Header angeben.

Das Hinzufügen von no-cache zur Antwort verursacht eine Wiedervalidierung mit dem Server, sodass Sie jedes Mal eine frische Antwort bereitstellen können — oder wenn der Client bereits eine neue hat, einfach mit 304 Not Modified antworten.

Cache-Control: no-cache

Die meisten HTTP/1.0-Caches unterstützen no-cache-Direktiven nicht, weshalb historisch max-age=0 als Workaround verwendet wurde. Aber nur max-age=0 könnte eine abgestandene Antwort wiederverwenden, wenn Caches vom Ursprungsserver getrennt sind. must-revalidate adressiert das. Deshalb ist das folgende Beispiel äquivalent zu no-cache.

Cache-Control: max-age=0, must-revalidate

Aber jetzt können Sie einfach no-cache verwenden.

Löschen eines bereits gespeicherten Caches

Es gibt keine Cache-Direktiven zum Löschen bereits gespeicherter Antworten aus Caches auf Zwischenservern.

Stellen Sie sich vor, dass Clients/Caches eine frische Antwort für einen Pfad speichern, ohne Anfrageflug zum Server. Der Server könnte nichts an diesem Pfad ändern.

Clear-Site-Data: cache kann verwendet werden, um jede gespeicherte Antwort für eine Site im Browser-Cache zu löschen, daher verwenden Sie dies mit Vorsicht. Beachten Sie, dass dies keine Auswirkungen auf geteilte oder Zwischen-Caches hat.

Spezifikationen

Browser-Kompatibilität

Weitere Informationen

• HTTP-Caching
• Caching-Tutorial für Web-Autoren und Webmasters
• Caching Best Practices & Max-Age Gotchas
• Cache-Control für Zivilisten
• RFC 9111 – HTTP-Caching
• RFC 5861 – HTTP-Cache-Control-Erweiterungen für abgestandene Inhalte
• RFC 8246 – HTTP Unveränderliche Antworten