Vary

Verwendung

Eine einzelne URL erzeugt oft unterschiedliche Antworten, je nachdem, was der Client sendet. Ein Server, der für den einen Client mit gzip und für den anderen mit Brotli komprimiert, liefert zwei verschiedene Repräsentationen derselben Ressource aus. Der Vary-Header hält fest, welche Anfrage-Header den Server dazu veranlasst haben, eine bestimmte Repräsentation auszuwählen, und gibt Caches damit die Informationen, die sie zum Speichern und Zuordnen der richtigen Kopie benötigen.

Wenn ein Cache eine Anfrage für eine URL erhält, zu der bereits eine Antwort gespeichert ist, vergleicht der Cache die aufgeführten Vary-Header zwischen der neuen und der gespeicherten Anfrage. Stimmen die Werte überein, ist die zwischengespeicherte Antwort gültig. Unterscheiden sie sich, holt der Cache eine frische Antwort vom Origin.

Die häufigsten Werte sind Accept-Encoding (für die Aushandlung der Komprimierung) und Accept (für die Inhaltsaushandlung). Dynamic-Serving-Konfigurationen, die Mobil- und Desktop-Clients anhand des User-Agent-Strings unterschiedliches HTML ausliefern, ergänzen Vary: User-Agent, um auf diese Variation hinzuweisen.

Der Platzhalterwert * bedeutet, dass jede Anfrage als einzigartig gilt, und deaktiviert damit faktisch das Caching für die Ressource. Das ist nur selten angemessen, und die meisten Caches behandeln eine Antwort mit Vary: * als nicht zwischenspeicherbar.

Hinweis

Google verwendet den Vary-Header nicht, um für die Suchindexierung die Beziehung zwischen Mobil- und Desktop-Version zu verstehen. Der Header ist ein Caching-Mechanismus, kein Suchsignal. Websites, die Dynamic Serving mit Vary: User-Agent einsetzen, profitieren weiterhin von korrektem Cache-Verhalten, doch der Header selbst hat keinen Einfluss darauf, wie Google mobile Inhalte entdeckt oder indexiert. Google rät trotz Mobile-First-Indexierung außerdem davon ab, m-dot-URLs zur kanonischen Version zu machen, und empfiehlt responsives Design als bevorzugte Konfiguration.

Accept-Encoding

Zeigt an, dass die Antwort je nach dem Anfrage-Header Accept-Encoding variiert. Unterschiedliche Komprimierungsalgorithmen (gzip, br, zstd) erzeugen für dieselbe Ressource unterschiedliche Antwort-Bodies. Dies ist der am weitesten verbreitete Vary-Wert.

Accept

Zeigt an, dass die Antwort je nach dem Anfrage-Header Accept variiert. Die Inhaltsaushandlung liefert abhängig von den Client-Präferenzen unterschiedliche Medientypen (HTML, JSON, XML) von derselben URL aus.

Accept-Language

Zeigt an, dass die Antwort je nach dem Anfrage-Header Accept-Language variiert. Mehrsprachige Websites, die lokalisierte Inhalte von derselben URL ausliefern, führen diesen Wert auf.

User-Agent

Zeigt an, dass die Antwort je nach dem Anfrage-Header User-Agent variiert. Dynamic-Serving-Konfigurationen liefern Mobil- und Desktop-Clients von derselben URL unterschiedliches HTML aus.

Cookie

Vary: Cookie bedeutet, dass sich die Antwort abhängig vom Wert des Cookie-Headers unterscheidet. Caches speichern für jeden eindeutigen Cookie-String eine eigene Variante, was zu erheblicher Cache-Fragmentierung führt, da jeder authentifizierte Nutzer ein anderes Session-Cookie besitzt. Beschränken Sie Vary: Cookie auf Antworten, die tatsächlich von Cookie-Werten abhängen (personalisierte Seiten, Dashboards), und vermeiden Sie es, den Wert bei öffentlichen statischen Assets zu setzen.

* (wildcard)

Der Platzhalterwert signalisiert, dass die Antwort von Faktoren abhängt, die kein Anfrage-Header erfasst. Caches behandeln dies als nicht zwischenspeicherbar. Wird nur selten absichtlich verwendet.

Beispiel

Ein Server komprimiert Antworten mit der vom Client angeforderten Kodierung. Der Header Vary: Accept-Encoding weist zwischengeschaltete Caches an, für gzip- und Brotli-Anfragen getrennte Kopien zu speichern, statt einem Brotli-fähigen Client eine gzip-komprimierte Antwort auszuliefern.

Vary: Accept-Encoding

Eine Inhaltsaushandlung liefert JSON oder HTML vom selben Endpunkt aus. Der Cache speichert abhängig vom Wert des Accept-Headers getrennte Antworten.

Vary: Accept

Mehrere Header, welche die Antwort beeinflussen, werden als kommagetrennter Wert aufgeführt. Hier hängt die Antwort sowohl von der akzeptierten Kodierung als auch von der bevorzugten Sprache ab.

Vary: Accept-Encoding, Accept-Language

Eine Dynamic-Serving-Konfiguration liefert Mobil- und Desktop-User-Agents unterschiedliches HTML aus. Der Cache speichert getrennte Versionen, die über den vollständigen User-Agent-String geschlüsselt sind.

Vary: User-Agent

Die Kombination von Vary mit Cache-Control steuert sowohl, was variiert, als auch, wie lange jede Variante frisch bleibt.

Cache-Control: public, max-age=3600
Vary: Accept-Encoding

Fehlersuche

Caching-Probleme durch einen fehlenden oder zu weit gefassten Vary-Header zeigen sich häufig darin, dass Nutzer falsche Inhalte erhalten.

Das CDN liefert die falsche zwischengespeicherte Variante aus. Ein Server gibt abhängig von einem Anfrage-Header unterschiedliche Inhalte zurück, lässt aber den passenden Vary-Wert weg. Das CDN speichert die erste Antwort und liefert dieselbe Kopie an alle Clients aus, unabhängig von deren Anfrage-Headern. Ergänzen Sie den betreffenden Header-Namen in der Vary-Liste. Testen Sie dies, indem Sie mit curl Anfragen mit unterschiedlichen Header-Werten senden und die Antwort-Header X-Cache oder Age vergleichen: curl -H “Accept-Encoding: gzip” -v https://cdn.example.re/style.css curl -H “Accept-Encoding: br” -v https://cdn.example.re/style.css

Cache-Fragmentierung durch Vary: User-Agent. Der User-Agent-String hat Tausende eindeutiger Werte. Wird User-Agent im Vary-Header aufgeführt, entsteht für nahezu jeden Besucher ein eigener Cache-Eintrag, was die Trefferquote des Caches zerstört. CDNs wie Cloudflare und Fastly normalisieren den User-Agent zu Geräteklassen. Verwenden Sie nach Möglichkeit einen normalisierten Header wie Sec-CH-UA-Mobile oder einen CDN-spezifischen Gerätetyp-Header anstelle des rohen User-Agent.

Vary: * deaktiviert das Caching vollständig. Der Platzhalter teilt Caches mit, dass die Antwort von Faktoren außerhalb jedes Anfrage-Headers abhängt. Die meisten Caches behandeln dies als nicht zwischenspeicherbar und liefern niemals eine gespeicherte Kopie aus. Entfernen Sie Vary: *, sofern nicht die Absicht besteht, sämtliches Caching für die Ressource zu deaktivieren. Wenn ein bestimmter Anfrage-Header die Variation steuert, benennen Sie diesen Header explizit.

Fehlendes Vary: Origin verursacht CORS-Cache-Poisoning. Ein Server gibt abhängig vom Origin-Anfrage-Header einen dynamischen Access-Control-Allow-Origin-Wert zurück, nimmt aber Vary: Origin nicht auf. Ein CDN speichert die Antwort mit einem Origin und liefert denselben CORS-Header an einen anderen Origin aus, woraufhin Browser die Antwort blockieren. Fügen Sie Vary: Origin zu jeder Antwort hinzu, die einen dynamischen Origin-Wert widerspiegelt. Zur Diagnose senden Sie zwei curl-Anfragen von unterschiedlichen Origins und prüfen, ob sich das zwischengespeicherte Access-Control-Allow-Origin ändert: curl -H “Origin: https://a.example.re” -v https://api.example.re/data curl -H “Origin: https://b.example.re” -v https://api.example.re/data

Inkonsistenzen bei Vary: Accept-Encoding zwischen gzip und Brotli. Manche Origin-Server komprimieren mit gzip, während ein CDN-Edge erneut zu Brotli komprimiert, wodurch die zwischengespeicherte Kodierung und der Vary-Schlüssel nicht mehr zusammenpassen. Stellen Sie sicher, dass Origin und CDN beim Kodierungsverhalten übereinstimmen. Setzen Sie in nginx gzip_vary on;, um Vary: Accept-Encoding automatisch hinzuzufügen. Wenn Sie Brotli neben gzip einsetzen, vergewissern Sie sich, dass beide Module denselben Vary-Wert ergänzen, damit der Cache pro Kodierung getrennte Einträge speichert.