Cache-Control i ETag – jak działa pamięć podręczna przeglądarki i jak uniknąć nieaktualnej strony?

Cache-Control i ETag – jak działa pamięć podręczna przeglądarki i jak uniknąć nieaktualnej strony?

Wprowadzasz poprawkę do strony, wdrożenie kończy się sukcesem, a klient nadal widzi stary wygląd albo skrypt sprzed aktualizacji. Odświeża stronę, próbuje ponownie i zgłasza błąd. Przyczyną nie musi być nieudany deployment. Często winna jest pamięć podręczna (cache) przeglądarki, pośredniego serwera proxy lub sieci CDN.

Cache nie jest usterką. Dobrze skonfigurowany przyspiesza witrynę, zmniejsza transfer i odciąża serwer. Problem pojawia się wtedy, gdy serwer nie mówi jasno, co można zapamiętać, na jak długo i kiedy trzeba sprawdzić aktualność zasobu. W tym poradniku nauczysz się czytać nagłówki HTTP, diagnozować nieaktualne pliki i dobierać reguły do różnych typów treści.

Najważniejsze informacje

  • Cache-Control określa zasady przechowywania i ponownego wykorzystania odpowiedzi HTTP.
  • max-age=3600 pozwala uznać odpowiedź za świeżą przez 3600 sekund; nie oznacza, że plik zostanie automatycznie usunięty po godzinie.
  • ETag i Last-Modified służą do warunkowej weryfikacji zasobu. Odpowiedź 304 Not Modified zwykle nie przesyła ponownie jego treści.
  • Dla plików CSS i JS z hashem w nazwie sprawdza się długi cache z immutable; dla dokumentów HTML zazwyczaj lepsza jest krótka świeżość albo rewalidacja.
  • no-cache nie oznacza zakazu zapisywania. Do ograniczenia przechowywania służy no-store.
  • Osobne warstwy cache – przeglądarka, CDN i aplikacja – mogą mieć odmienne zasady, więc diagnoza musi uwzględniać wszystkie.

Czym jest cache HTTP i dlaczego przeglądarka z niego korzysta?

Podczas pierwszego otwarcia strony przeglądarka pobiera dokument HTML, arkusze CSS, skrypty JavaScript, obrazy i czcionki. Jeśli odpowiedzi nadają się do zapamiętania, część danych może trafić do lokalnej pamięci podręcznej. Przy kolejnej wizycie przeglądarka nie musi pobierać wszystkiego od nowa.

Wyobraź sobie logo firmy o wielkości 120 KB. Jeśli plik nie zmienia się miesiącami, ponowne przesyłanie go przy każdej odsłonie jest niepotrzebne. Inaczej jest z HTML strony z aktualnościami: dokument może zmieniać się kilka razy dziennie.

Warto rozróżnić trzy miejsca, w których odpowiedź może zostać zapamiętana:

Warstwa Co przechowuje? Kto nią zarządza?
Cache przeglądarki Kopie zasobów dla danego użytkownika Przeglądarka i dyrektywy HTTP
Cache współdzielony / CDN Kopie odpowiedzi obsługujące wielu użytkowników Operator CDN, reverse proxy i konfiguracja HTTP
Cache aplikacji Wygenerowane strony, zapytania lub obiekty Aplikacja, framework, Redis lub inny mechanizm

Nagłówki HTTP dotyczą przede wszystkim cache odpowiedzi. Nie sterują automatycznie każdym wewnętrznym cache aplikacji. Dlatego wyczyszczenie cache przeglądarki nie naprawi nieaktualnej odpowiedzi generowanej już po stronie serwera.

Cache-Control – najważniejszy nagłówek

Serwer może odpowiedzieć na żądanie tak:

HTTP/2 200
Content-Type: text/css
Cache-Control: public, max-age=3600

Oznacza to, że odpowiedź może być przechowywana również przez cache współdzielony (public) i pozostaje świeża przez godzinę (max-age=3600). Gdy czas świeżości upłynie, kopia nie staje się automatycznie bezużyteczna: cache może spróbować zweryfikować ją u serwera.

Najczęściej spotykane dyrektywy:

Dyrektywa Znaczenie praktyczne
max-age=60 Odpowiedź jest świeża przez maksymalnie 60 sekund od czasu określonego regułami HTTP cache.
public Odpowiedź może być przechowywana także w cache współdzielonym, o ile inne reguły na to pozwalają.
private Odpowiedź przeznaczona do prywatnego cache, np. przeglądarki; nie do współdzielonego cache.
no-cache Odpowiedź można przechować, ale przed ponownym użyciem trzeba ją zweryfikować.
no-store Cache nie powinien przechowywać odpowiedzi ani żądania.
must-revalidate Gdy odpowiedź jest nieświeża, cache nie powinien używać jej bez skutecznej walidacji, z uwzględnieniem zasad protokołu.
immutable W okresie świeżości zasób nie powinien się zmieniać; przeglądarka może ograniczyć niepotrzebne rewalidacje.
s-maxage=300 Określa świeżość dla cache współdzielonych i ma pierwszeństwo przed max-age w tej warstwie.

no-cache a no-store – różnica, która często powoduje błędy

Te nazwy są mylące. Cache-Control: no-cache nie wyłącza przechowywania. Pozwala zapisać odpowiedź, ale wymaga sprawdzenia u serwera, czy można ją ponownie wykorzystać. Jest to przydatne na przykład dla HTML, którego aktualność ma znaczenie.

Cache-Control: no-store nakazuje nie przechowywać odpowiedzi. Stosuje się je między innymi dla szczególnie wrażliwych danych, jeśli ich zapisanie w cache byłoby niepożądane. Sam nagłówek nie gwarantuje jednak usunięcia wcześniej zapisanych kopii, nie zastępuje wylogowania ani innych zabezpieczeń.

Dla strony z indywidualnymi danymi użytkownika nie ustawiaj pochopnie public. W zależności od rodzaju danych użyj private, no-cache albo no-store i sprawdź zachowanie CDN. Błąd w tym miejscu może skutkować nie tylko nieaktualną stroną, ale również ujawnieniem treści innemu użytkownikowi.

ETag i 304 Not Modified – jak działa sprawdzanie aktualności?

Serwer może dołączyć identyfikator wersji odpowiedzi:

HTTP/2 200
ETag: "article-v17"
Cache-Control: no-cache
Content-Type: text/html

Gdy przeglądarka chce ponownie użyć zapisanej kopii, może wysłać:

GET /artykul HTTP/2
If-None-Match: "article-v17"

Jeśli wybrana reprezentacja zasobu nadal pasuje do znacznika, serwer może odpowiedzieć:

HTTP/2 304 Not Modified
ETag: "article-v17"

Przeglądarka korzysta wtedy z posiadanej treści zamiast pobierać pełną odpowiedź 200 OK. 304 oszczędza transfer, ale nadal wymaga kontaktu z serwerem. Dlatego nie jest tym samym co wykorzystanie świeżego zasobu bez żądania sieciowego.

ETag jest nieprzezroczystym identyfikatorem wersji reprezentacji: nie zakładaj, że zawsze jest skrótem kryptograficznym pliku. Istnieją także słabe znaczniki, np. W/"article-v17", dopuszczające porównanie semantycznie równoważnych reprezentacji. Implementacja powinna uwzględniać warianty kompresji i nagłówek Vary, jeśli treść zależy od nagłówków żądania.

A co z Last-Modified?

Alternatywny mechanizm korzysta z daty modyfikacji:

Last-Modified: Tue, 10 Nov 2026 10:00:00 GMT

Przeglądarka może później wysłać If-Modified-Since. Serwer odpowie 304, jeśli zasób nie został zmieniony zgodnie z zasadami warunkowego żądania. Data ma ograniczoną dokładność, dlatego ETag bywa lepszy przy szybkich zmianach. Jeśli w żądaniu występują oba warunki, If-None-Match ma pierwszeństwo przed If-Modified-Since.

Dlaczego po wdrożeniu nadal widać starą wersję strony?

Najczęstszy scenariusz wygląda tak: aplikacja publikuje nowy plik /assets/app.js, ale URL pozostaje taki sam. Wcześniejsza odpowiedź miała Cache-Control: public, max-age=31536000. Przeglądarka może uznawać starą kopię za świeżą nawet przez rok, więc w ogóle nie pyta serwera o nowy skrypt.

Inne możliwe przyczyny to:

  • CDN nadal przechowuje starszy HTML albo starsze pliki statyczne.
  • HTML wskazuje poprzednią nazwę bundla JS po niepełnym wdrożeniu.
  • Service worker przechwytuje żądania i zwraca własne kopie z Cache Storage.
  • Reverse proxy dodaje lub nadpisuje nagłówki Cache-Control.
  • Serwer ma niepoprawny ETag lub Last-Modified i błędnie zwraca 304 mimo zmiany treści.
  • Zasób różni się dla zalogowanych i niezalogowanych, ale brakuje prawidłowego rozdzielenia wariantów cache.

Najważniejsza zasada: nie ustawiaj wielomiesięcznego cache dla zasobu, którego treść zmieniasz pod niezmiennym adresem URL.

Najbezpieczniejsza strategia: wersjonowanie plików statycznych

Nowoczesne narzędzia budowania aplikacji często generują pliki z hashem zawartości:

/assets/app.8f2c1a.js
/assets/styles.71b9d4.css

Po zmianie kodu powstaje nowa nazwa. Dzięki temu można stosować długi cache:

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

Stary plik może pozostać w pamięci przeglądarki, ale nowy HTML wskazuje nowy URL, więc użytkownik pobiera nową wersję. To znacznie bezpieczniejsze niż ręczne czyszczenie cache po każdej publikacji.

Dla HTML można zastosować na przykład:

Cache-Control: no-cache

Wówczas przeglądarka może przechowywać dokument, ale przed jego ponownym wykorzystaniem musi sprawdzić aktualność. Jeśli treść HTML zawiera dane wrażliwe lub jest indywidualna, polityka powinna być odpowiednio bardziej restrykcyjna.

Uwaga: po wdrożeniu nie usuwaj natychmiast wszystkich poprzednich plików z hashem. Użytkownik z wcześniej otwartą kartą może nadal próbować pobrać starszy chunk JavaScript. Krótki okres współistnienia wersji ogranicza błędy przy aktualizacjach.

Jak sprawdzić nagłówki cache w przeglądarce?

W Chrome lub Firefox otwórz narzędzia deweloperskie (zwykle F12), przejdź do zakładki Network / Sieć i załaduj stronę. Kliknij żądanie dokumentu HTML, a następnie plik CSS lub JS.

Sprawdź przede wszystkim:

  1. Status – 200, 304 albo odpowiedź obsłużona z lokalnego cache.
  2. Response Headers – Cache-Control, ETag, Last-Modified, Age, Vary.
  3. Size / Transferred – czy zasób rzeczywiście pobrano z sieci, czy z pamięci.
  4. Request Headers – czy pojawiły się If-None-Match lub If-Modified-Since.
  5. Service Workers – czy strona ma aktywny worker mogący przechwytywać żądania.

Opcja Disable cache w DevTools jest przydatna diagnostycznie, ale zwykle działa tylko przy otwartych narzędziach. Nie pokazuje więc w pełni zachowania zwykłego użytkownika. Przetestuj zarówno normalne odświeżenie, jak i wariant z wyłączonym cache.

Nie utożsamiaj także 304 z błędem: to prawidłowy wynik warunkowego żądania, jeśli lokalna kopia jest nadal aktualna.

Diagnostyka przez curl – przykłady do skopiowania

Najpierw pobierz same nagłówki:

curl -I https://example.com/
curl -I https://example.com/assets/app.js

-I wykonuje żądanie HEAD. Jeśli serwer lub CDN inaczej obsługuje HEAD niż GET, sprawdź także prawdziwe żądanie GET, bez zapisywania treści na ekran:

curl -sS -D - -o /dev/null https://example.com/

Aby sprawdzić warunkowe żądanie z ETag, najpierw odczytaj wartość z odpowiedzi, a następnie podstaw ją dosłownie:

curl -sS -D - -o /dev/null \
  -H 'If-None-Match: "article-v17"' \
  https://example.com/artykul

Odpowiedź 304 będzie poprawna tylko wtedy, gdy identyfikator nadal odpowiada bieżącej reprezentacji. Jeśli mimo zmiany pliku serwer nadal zwraca 304, sprawdź sposób generowania ETag i ewentualne cache pośrednie.

Możesz również wysłać żądanie z Cache-Control: no-cache:

curl -sS -D - -o /dev/null \
  -H 'Cache-Control: no-cache' \
  https://example.com/

To prośba o walidację po stronie cache, nie gwarancja całkowitego ominięcia wszystkich warstw CDN czy cache aplikacji. Dodawanie losowego parametru do URL też może zmienić klucz cache, ale nie jest uniwersalnym testem: konfiguracja CDN może ignorować query string.

Co oznaczają nagłówki Age i Vary?

Age pomaga ocenić, jak długo odpowiedź znajdowała się w cache od momentu wygenerowania lub walidacji zgodnie z regułami HTTP. Przykład:

Cache-Control: public, max-age=600
Age: 420

W uproszczeniu odpowiedź ma jeszcze około trzech minut deklarowanej świeżości, choć dokładne obliczenie wieku uwzględnia również inne informacje protokołu.

Vary informuje, że wybór reprezentacji zależy od wskazanych nagłówków żądania. Przykładowo Vary: Accept-Encoding pomaga rozdzielić odpowiedzi skompresowane różnymi metodami. Nie traktuj jednak Vary: Cookie jako zamiennika właściwej polityki prywatności: dla stron z danymi użytkownika trzeba świadomie kontrolować przechowywanie i konfigurację CDN.

Cache w CDN: dlaczego wyczyszczenie przeglądarki nie wystarcza?

CDN może przechowywać kopię odpowiedzi niezależnie od cache użytkownika. Czasem stosuje osobne reguły dla plików statycznych, HTML, parametrów zapytania i ciasteczek. Zdarza się też, że konfiguracja panelu CDN nadpisuje nagłówki serwera źródłowego.

Przy podejrzeniu nieaktualnej odpowiedzi sprawdź:

  • Czy problem występuje tylko w jednej lokalizacji albo sieci?
  • Czy odpowiedź ma Age lub charakterystyczny nagłówek statusu cache dostawcy?
  • Czy zasób na serwerze źródłowym jest już nowy?
  • Czy po purge konkretnego URL problem znika?
  • Czy reguły CDN nie cache'ują stron konta, koszyka lub panelu administracyjnego?

W panelach CDN opcja purge cache usuwa wybrane kopie, ale jej działanie i czas propagacji zależą od dostawcy. Nie używaj masowego purge jako codziennego substytutu poprawnego wersjonowania zasobów.

Przykładowa konfiguracja Nginx

Poniższy fragment pokazuje ideę: HTML wymaga rewalidacji, a pliki z hashem w nazwie mogą mieć długi cache. Wzorzec dopasowania należy dostosować do rzeczywistego sposobu nazywania plików w projekcie.

# Dokumenty HTML: sprawdzaj aktualność przed ponownym użyciem.
location ~* \.html$ {
    add_header Cache-Control "no-cache" always;
}

# Pliki CSS/JS z hashem w nazwie, np. app.a1b2c3d4.js.
location ~* \.[a-f0-9]{8,}\.(css|js)$ {
    add_header Cache-Control "public, max-age=31536000, immutable" always;
}

Ważne: lokalizacje location w Nginx mają określone zasady pierwszeństwa, a add_header może współistnieć z nagłówkami dodawanymi przez aplikację lub upstream. Przed wdrożeniem sprawdź pełną konfigurację (nginx -t), faktyczne nagłówki curl i zachowanie ścieżki /, która nie musi kończyć się na .html. Powyższy przykład nie jest gotową konfiguracją wszystkich tras aplikacji.

W Apache podobne reguły można ustawić za pomocą mod_headers, ale również tutaj trzeba uwzględnić istniejące nagłówki i reguły serwera.

Czy cache może powodować błędy bezpieczeństwa?

Tak. Jeśli współdzielony cache zapisze odpowiedź zawierającą dane zalogowanego użytkownika i później poda ją innej osobie, może dojść do wycieku. Niebezpieczne są też błędne klucze cache i tzw. cache poisoning – gdy atakujący wpływa na zapamiętaną odpowiedź.

Dlatego:

  • Nie ustawiaj public dla odpowiedzi z prywatnymi danymi bez świadomego projektu cache.
  • Testuj osobno żądania zalogowane i anonimowe oraz różne konta.
  • Nie zakładaj, że sama obecność ciasteczka automatycznie wyłącza cache CDN.
  • Sprawdź, czy cache różnicuje odpowiedzi zależne od nagłówków, hosta i ścieżki.
  • Dla wrażliwych stron rozważ Cache-Control: no-store, a przy wylogowaniu także odpowiednie unieważnianie sesji.

Więcej o zabezpieczaniu odpowiedzi HTTP przeczytasz w poradniku Nagłówki bezpieczeństwa HTTP – jak sprawdzić i skonfigurować?.

Lista kontrolna przed publikacją nowej wersji strony

  1. Upewnij się, że HTML nie jest bez potrzeby cache'owany przez długi czas.
  2. Generuj nowe nazwy CSS i JS przy zmianie zawartości; dopiero wtedy stosuj immutable i długi max-age.
  3. Pozostaw poprzednie wersje chunków dostępne na czas przejściowy.
  4. Zweryfikuj nagłówki dla dokumentu, plików statycznych, API i stron zalogowanych.
  5. Sprawdź CDN, reverse proxy oraz ewentualnego service workera.
  6. Przetestuj stronę na nowej sesji i w przeglądarce, która odwiedzała ją wcześniej.
  7. Po wdrożeniu monitoruj błędy ładowania zasobów i działanie kluczowych podstron.

Jeśli zależy Ci na wykrywaniu awarii po wdrożeniu, zobacz również Monitoring dostępności strony – jak szybko wykrywać awarie?. Sam cache może ukryć część problemów przed prostym sprawdzaniem HTTP, dlatego warto monitorować także rzeczywiste scenariusze działania aplikacji. Narzędzia do monitoringu stron oferuje również Ping.pl.

FAQ – najczęstsze pytania o cache HTTP

Czy Ctrl+F5 usuwa cały cache?

Nie. Wymuszone odświeżenie zwykle powoduje ponowne pobranie lub rewalidację zasobów bieżącej strony, ale nie jest równoznaczne z usunięciem wszystkich danych przeglądarki, Cache Storage czy kopii CDN.

Czy 304 Not Modified oznacza awarię serwera?

Nie. 304 informuje, że przy warunkowym żądaniu istniejąca kopia może zostać użyta ponownie. To normalny mechanizm optymalizacji transferu.

Czy dla każdego pliku warto ustawić max-age na rok?

Nie. Rok ma sens przede wszystkim dla zasobów o niezmiennym URL i niezmiennej treści, np. plików z hashem zawartości. Dla HTML lub plików aktualizowanych pod stałym adresem może prowadzić do pokazywania starej wersji.

Czy ETag jest obowiązkowy?

Nie. Rewalidacja może opierać się na Last-Modified, a zasoby z odpowiednio dobranym czasem świeżości nie wymagają sprawdzania przy każdym użyciu. ETag często pozwala jednak dokładniej identyfikować wersję odpowiedzi.

Czy usunięcie cache CDN naprawi problem u wszystkich?

Niekoniecznie. Użytkownicy mogą mieć własne świeże kopie w przeglądarkach, a service worker może korzystać z odrębnej pamięci. Trzeba ustalić, która warstwa zwraca nieaktualną treść.

Podsumowanie

Dobra polityka cache to kompromis między szybkością a aktualnością. HTML powinien prowadzić użytkownika do bieżącej wersji aplikacji, natomiast pliki statyczne z wersjonowanymi nazwami mogą być przechowywane długo. Cache-Control określa zasady ponownego użycia, a ETag i Last-Modified pozwalają tanio sprawdzić, czy kopia nadal jest poprawna.

Jeżeli po wdrożeniu część użytkowników widzi starą stronę, nie zaczynaj od polecenia „wyczyść pamięć przeglądarki”. Najpierw sprawdź odpowiedzi HTTP, identyfikatory wersji plików, CDN i service workera. Dzięki temu usuniesz przyczynę problemu zamiast przerzucać go na użytkowników.

Źródła i dokumentacja

Ta strona jest chroniona przez reCAPTCHA. Obowiązuje Polityka prywatności oraz Warunki korzystania Google. Zdjęcia i grafiki: Magnific.