Cache-Control header

Syntax

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

Cache-Direktiven folgen diesen Regeln:

• Caching-Direktiven sind nicht zwischen Groß- und Kleinschreibung unterscheidend. Es wird jedoch empfohlen, Kleinbuchstaben zu verwenden, da einige Implementierungen Großbuchstaben-Direktiven nicht erkennen.
• Mehrere Direktiven sind erlaubt und müssen durch Kommata getrennt werden (z.B. Cache-control: max-age=180, public).
• Einige Direktiven haben ein optionales Argument. Wenn ein Argument angegeben wird, wird es durch ein Gleichheitszeichen (=) vom Direktiven-Namen getrennt. Typischerweise sind die 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 führt die Standard-Cache-Control-Direktiven auf:

Hinweis: Überprüfen Sie die Kompatibilitätstabelle auf deren 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 für die Wiederverwendung bei nachfolgenden Anfragen speichert. Es kann entweder ein geteilter Cache oder ein privater Cache sein.

Geteilter Cache

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

Privater Cache

Ein 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

Speichern einer Antwort in Caches, wenn die Antwort zwischenspeicherbar ist. Allerdings wird die zwischengespeicherte Antwort nicht immer unverändert wiederverwendet. (Normalerweise bedeutet "cachen" das Speichern einer Antwort.)

Antwort wiederverwenden

Wiederverwenden zwischengespeicherter Antworten für nachfolgende Anfragen.

Antwort erneut validieren

Den Ursprungsserver fragen, ob die gespeicherte Antwort noch frisch ist. Üblicherweise erfolgt die erneute Validierung durch eine bedingte Anfrage.

Frische Antwort

Zeigt an, dass die Antwort frisch ist. Das bedeutet üblicherweise, dass die Antwort für nachfolgende Anfragen erneut verwendet werden kann, abhängig von den Anfragedirektiven.

Abgestandene Antwort

Zeigt an, dass die Antwort eine abgestandene Antwort ist. Das bedeutet üblicherweise, dass die Antwort nicht unverändert wiederverwendet werden kann. Cache-Speicher müssen abgestandene Antworten nicht sofort entfernen, da die erneute Validierung die Antwort von abgelaufen zu frisch ändern könnte.

Alter

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

Direktiven

Dieser Abschnitt listet die Direktiven auf, die das Caching beeinflussen — sowohl Antwortdirektiven als auch Anfragedirektiven.

Antwortdirektiven

max-age

Die max-age=N-Antwortdirektive gibt an, dass die Antwort N Sekunden, nachdem sie generiert wurde, weiterhin frisch bleibt.

Cache-Control: max-age=604800

Sie 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 verstrichene Zeit seit dem Empfang der Antwort ist; es ist die verstrichene Zeit seit der Erzeugung der Antwort auf dem Ursprungsserver. Wenn der andere Cache — auf dem Netzwerkpfad der Antwort — die Antwort 100 Sekunden lang speichert (angezeigt durch das Age-Antwortfeld), zieht der Browser diese 100 Sekunden von seiner Frische-Lebenszeit ab.

Wenn der Wert von max-age negativ ist (zum Beispiel -1) oder keine Ganzzahl ist (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 Frische-Lebenszeit der HTTP-Spezifikation angemerkt).

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 angegebenen Wert für geteilte Caches, falls diese vorhanden sind.

Cache-Control: s-maxage=604800

no-cache

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

Cache-Control: no-cache

Wenn Sie möchten, dass Caches immer nach Inhaltsaktualisierungen suchen, während gespeicherte Inhalte wiederverwendet werden, ist no-cache die zu verwendende Direktive. Sie erzwingt dies, indem sie Caches anweist, jede Anfrage mit dem Ursprungsserver zu validieren.

Beachten Sie, dass no-cache nicht "nicht cachen" bedeutet. no-cache erlaubt es Caches, eine Antwort zu speichern, erfordert jedoch, dass diese vor der Wiederverwendung erneut validiert wird. Wenn Sie mit "nicht cachen" tatsächlich "nicht speichern" meinen, dann ist no-store die Direktive, die verwendet werden sollte.

must-revalidate

Die must-revalidate-Antwortdirektive gibt an, dass die Antwort in Caches gespeichert werden kann 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 die gespeicherte Antwort wird mit dem Ursprungsserver validiert oder es wird eine 504 (Gateway Timeout) Antwort generiert.

proxy-revalidate

Die proxy-revalidate-Antwortdirektive ist das Äquivalent zu must-revalidate, jedoch speziell nur für geteilte Caches.

no-store

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

Cache-Control: no-store

private

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

Cache-Control: private

Sie sollten die private-Direktive für benutzerpersonalisierte Inhalte hinzufügen, insbesondere für Antworten, die nach einem Login empfangen werden und für Sitzungen, die über Cookies verwaltet werden.

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

public

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

Cache-Control: public

Im Allgemeinen senden Browser Anfragen mit dem Authorization-Header, wenn Seiten unter Basis-Authentifizierung oder Digest-Authentifizierung stehen. Das bedeutet, dass die Antwort für eingeschränkte Benutzer (die Konten haben) zugangskontrolliert ist und grundsätzlich nicht geteilten Cache-fähig ist, auch wenn sie max-age hat.

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 auch aufheben.

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

must-understand

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

must-understand sollte mit no-store für ein Fallback-Verhalten kombiniert 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 er die Antwort mit einem Verständnis der Cache-Anforderungen, basierend auf ihrem Statuscode.

no-transform

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

no-transform zeigt an, dass kein Intermediär (unabhängig davon, 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 Best Practice für statische Ressourcen ist es, Versionen/Hashes in ihre URLs aufzunehmen, während die Ressourcen niemals modifiziert werden — sondern stattdessen bei Bedarf die Ressourcen mit neueren Versionen zu aktualisieren, die neue Versionsnummern/Hashes haben, 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 für die Validierung an den Ursprungsserver. Aber es ist nicht notwendig, diese Art von statischen Ressourcen erneut zu validieren, auch wenn ein Benutzer den Browser neu lädt, da sie nie modifiziert werden. immutable teilt einem Cache mit, dass die Antwort unveränderlich ist, solange sie frisch ist, und vermeidet diese Art von unnötigen bedingten Anfragen an den Server.

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

stale-while-revalidate

Die stale-while-revalidate-Antwortdirektive gibt an, dass der Cache eine abgestandene Antwort erneut verwenden kann, während sie erneut validiert wird, um in einem Cache zu landen.

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 alle Anfragen, die am folgenden Tag (86400s) gestellt werden, wiederverwenden, vorausgesetzt, sie validieren die Antwort im Hintergrund.

Die erneute Validierung macht den Cache wieder frisch, sodass es für Clients so aussieht, als wäre er während dieses Zeitraums immer frisch gewesen — was effektiv die Latenzstrafe der erneuten Validierung für sie verbirgt.

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

stale-if-error

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

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 jedoch für einen zusätzlichen Tag (86400s) verwendet werden, wenn ein Fehler auftritt.

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

Anfragedirektiven

no-cache

Die no-cache-Anfragedirektive fordert Caches auf, die Antwort mit dem Ursprungsserver vor der Wiederverwendung zu validieren.

Cache-Control: no-cache

no-cache erlaubt 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 erzwingend neu laden.

no-store

Die no-store-Anfragedirektive erlaubt es einem Client, Caches zu bitten, auf die Speicherung der Anfrage und der entsprechenden Antwort zu verzichten — selbst wenn die Antwort des Ursprungsservers gespeichert werden könnte.

Cache-Control: no-store

max-age

Die max-age=N-Anfragedirektive gibt an, dass der Client eine gespeicherte Antwort akzeptiert, die innerhalb von N Sekunden auf dem Ursprungsserver generiert wurde — wobei N eine 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 generiert wurde (berechnet aus max-age und dem Age-Header), kann der Cache diese Antwort nicht wiederverwenden.

Viele Browser verwenden diese Direktive für das Neuladen, wie unten erläutert.

Cache-Control: max-age=0

max-age=0 ist ein Workaround für no-cache, da 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 Abwärtskompatibilität — und verwenden alternativ no-cache, um ein "erzwingendes Neuladen" zu verursachen.

Wenn der Wert von max-age negativ ist (zum Beispiel, -1) oder keine Ganzzahl ist (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 gibt an, dass der Client eine zwischengespeicherte Antwort akzeptiert, 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 zwischengespeicherte Antworten von Caches akzeptieren kann, auch wenn diese etwas älter sind.

Beachten Sie, dass die gängigen Browser Anfragen mit max-stale nicht unterstützen.

min-fresh

Die min-fresh=N-Anfragedirektive gibt an, dass der Client eine zwischengespeicherte Antwort akzeptiert, die für mindestens N Sekunden frisch ist.

Cache-Control: min-fresh=600

Im obigen Fall würde der Cache die Antwort mit Cache-Control: max-age=3600 nicht akzeptieren, wenn sie vor 51 Minuten in Caches gespeichert wurde.

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

Beachten Sie, dass die gängigen Browser Anfragen mit min-fresh nicht unterstützen.

no-transform

Hat dieselbe Bedeutung wie no-transform für eine Antwort, jedoch 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 wenn sie veraltet ist, 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 gibt an, dass der Browser daran interessiert ist, bei einem Fehler von einem beliebigen Zwischenserver für einen bestimmten Ursprungsserver abgestandene Inhalte zu erhalten. Dies wird von keinem Browser unterstützt (siehe Browser-Kompatibilität).

Anwendungsfälle

Verhinderung der Speicherung

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

Cache-Control: no-store

Beachten Sie, dass no-cache bedeutet "es kann gespeichert werden, aber nicht wiederverwenden, bevor es validiert wird" — also ist es nicht dafür gedacht, das Speichern einer Antwort zu verhindern.

Cache-Control: no-cache

Theoretisch sollte, wenn Direktiven in Konflikt stehen, die restriktivste Direktive beachtet werden. Das folgende Beispiel ist also im Grunde bedeutungslos, da private, no-cache, max-age=0 und must-revalidate in Konflikt mit no-store stehen.

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

# equivalent to
Cache-Control: no-store

Caching von statischen Assets mit "Cache Busting"

Wenn Sie statische Assets mit Versionierungs-/Hashing-Mechanismen erstellen, ist das Hinzufügen einer Version/eines Hashes zum Dateinamen oder zur Abfragezeichenfolge 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 ändert sich, wenn Sie die Bibliothek aktualisieren, und hero.png ändert sich auch, wenn Sie das Bild bearbeiten. Diese sind also schwer in einem Cache mit max-age zu speichern.

In einem solchen Fall könnten Sie die Caching-Anforderungen durch die Verwendung einer bestimmten, nummerierten Version der Bibliothek ansprechen und den Hash des Bildes in seiner 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, da der Inhalt niemals geändert 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 Caches werden nicht wiederverwendet. Das wird als "Cache-Busting"-Muster bezeichnet.

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

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

Hinweis: Wenn index.html unter Basis-Authentifizierung oder Digest-Authentifizierung kontrolliert wird, werden Dateien unter /assets nicht im geteilten Cache gespeichert. Wenn /assets/-Dateien geeignet sind, um im geteilten Cache gespeichert zu werden, benötigen Sie zusätzlich zu public, s-maxage oder must-revalidate.

Immer aktuelle Inhalte

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

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

Das Hinzufügen von no-cache zur Antwort verursacht eine erneute Validierung beim 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 keine no-cache-Direktiven, daher wurde historisch max-age=0 als Workaround verwendet. Aber nur max-age=0 könnte eine abgestandene Antwort verursachen, die wiederverwendet wird, wenn Caches vom Ursprungsserver getrennt sind. must-revalidate behebt dies. Deshalb ist das folgende Beispiel gleichwertig mit 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, um bereits gespeicherte Antworten aus Caches auf mittleren Servern zu löschen.

Stellen Sie sich vor, dass Clients/Caches eine frische Antwort für einen Pfad speichern, ohne dass eine Anforderungsflug zum Server erfolgt. Es gibt nichts, was ein Server für diesen Pfad tun könnte.

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• HTTP-Caching
• Caching-Tutorial für Web-Autoren und Webmastern
• Caching Best Practices & Max-Age Besonderheiten
• Cache-Control für Zivilisten
• RFC 9111 – HTTP-Caching
• RFC 5861 – HTTP Cache-Control Extensions für veraltete Inhalte
• RFC 8246 – HTTP Unveränderliche Antworten