Generator reguł cache Nginx

Generator reguł cache Nginx

Cache to najprostszy sposób na przyspieszenie strony. Zasoby statyczne (obrazy, CSS, JS) zmieniają się rzadko, więc przeglądarka może trzymać je długo. Nginx decyduje, jak długo.

Jak długo cache’ować?

Plikom z hashem w nazwie (np. app.a1b2c3.js) można ustawić cache „na zawsze” — zmiana treści zmienia nazwę pliku.

Cache proxy

Gdy Nginx stoi przed aplikacją (PHP, Node), można cache’ować całe odpowiedzi. Wymaga to strefy proxy_cache_path w bloku http i włączenia cache w lokalizacji proxy.

Jak działa expires i skąd bierze się czas cache

Dyrektywa expires nie jest osobnym mechanizmem przechowywania plików. To instrukcja dla Nginx, aby do odpowiedzi dołożył dwa nagłówki: Expires z datą bezwzględną oraz Cache-Control z wartością max-age podaną w sekundach. Zapis 30d jest przez Nginx przeliczany na 2 592 000 sekund, a 1y na 31 536 000 sekund, jeśli rok liczysz jako 365 dni. Data w nagłówku Expires powstaje przez dodanie tego czasu do momentu wygenerowania odpowiedzi, dlatego przy każdym pobraniu pliku jest inna.

Zasada działania jest prosta: przez cały czas ważności wpisu przeglądarka korzysta z kopii lokalnej i nie wysyła zapytania do serwera. Dopiero po przekroczeniu max-age wraca po plik, zwykle z zapytaniem warunkowym, na które serwer odpowiada kodem 304, jeśli treść się nie zmieniła. Nagłówek immutable zmienia to zachowanie: mówi przeglądarce, że plik nigdy się nie zmieni, więc nie rewaliduje go nawet przy odświeżeniu strony. Ma to sens wyłącznie dla plików z hashem w nazwie, bo wtedy każda zmiana treści tworzy nowy adres.

Drugi poziom to proxy_cache, czyli cache trzymany po stronie serwera, a nie przeglądarki. Tu liczą się trzy elementy: strefa pamięci opisana w proxy_cache_path, klucz wpisu budowany między innymi z metody i adresu URI oraz czas ważności odpowiedzi. Nginx sam decyduje, czy oddać zapisany wpis, czy przepuścić żądanie do aplikacji, a stan decyzji pokazuje nagłówek X-Cache-Status z wartościami takimi jak HIT, MISS, EXPIRED, STALE albo BYPASS. Te dwa mechanizmy się nie zastępują: expires przyspiesza kolejne wizyty użytkownika, a proxy_cache odciąża aplikację przy ruchu od wielu różnych osób.

Przykład krok po kroku dla typowego serwisu

1. Policz zasoby w projekcie. Załóżmy, że strona ma 120 obrazów, 8 plików CSS i JS bez hasha w nazwie, 5 plików CSS i JS z hashem oraz 3 pliki czcionek. Razem 136 plików statycznych.
2. Dla obrazów ustaw 30 dni, czyli najkrótszą wartość z zalecanego zakresu. W sekundach to 30 razy 86 400, czyli 2 592 000. W konfiguracji zapisujesz to jako expires 30d.
3. Dla 8 plików bez hasha zostaw 30 dni, czyli 2 592 000 sekund. Bezpieczniej jest trzymać je krócej, bo po podmianie treści użytkownik z kopią lokalną zobaczy starą wersję aż do wygaśnięcia wpisu.
4. Dla 5 plików z hashem w nazwie ustaw 1 rok, czyli 365 razy 86 400, czyli 31 536 000 sekund, i dodaj nagłówek immutable. Zmiana treści zmieni nazwę pliku, więc stara kopia nie jest problemem.
5. Dla 3 plików czcionek ustaw również 1 rok, czyli 31 536 000 sekund, w osobnym bloku location obejmującym rozszerzenia woff, woff2, ttf, otf i eot.
6. Pliki HTML zostaw bez cache albo z bardzo krótkim czasem, a dla odpowiedzi z aplikacji włącz proxy_cache dla żądań GET. Na koniec sprawdź wynik w narzędziach deweloperskich, a przy proxy także nagłówek X-Cache-Status.

Wynik: 8 plików, czyli 5 z hashem i 3 czcionki, przeglądarka trzyma przez 365 dni bez odpytywania serwera, a pozostałe 128 plików odświeża po 30 dniach, czyli po 2 592 000 sekundach.

Czas cache i wartość w sekundach

Jak używać generatora w praktyce

• Jeden location na kategorię plików — obrazy, style i skrypty oraz czcionki mają różne zalecane czasy, więc trzymaj je w osobnych blokach location. Łatwiej wtedy zmienić jedną wartość bez ruszania pozostałych reguł.
• Nie mieszaj expires z ręcznym Cache-Control — jeśli dodajesz Cache-Control przez add_header, a obok stoi expires, w odpowiedzi mogą pojawić się sprzeczne wartości. Wybierz jeden sposób ustawiania czasu życia i trzymaj się go w całej konfiguracji.
• immutable tylko z hashem — nagłówek ten zakłada, że plik nigdy się nie zmieni. Bez hasha w nazwie po podmianie treści użytkownik nie dostanie nowej wersji, dopóki nie wyczyści cache ręcznie.
• Zaczynaj od krótszego czasu — jeśli nie masz pewności, jak często zmieniają się zasoby, ustaw dolny koniec zakresu, czyli 30 dni. Wydłużenie do roku wykonaj dopiero po sprawdzeniu, że wdrożenia nie zaskakują użytkowników.
• Rozdziel cache przeglądarki od cache proxy — expires działa lokalnie u użytkownika i nie wymaga zmian w aplikacji. proxy_cache wymaga strefy w bloku http i włączenia w lokalizacji proxy oraz ostrożności przy treściach spersonalizowanych.

Czego generator nie uwzględnia

• Nie zna Twojego ruchu i wzorca wdrożeń — narzędzie podaje wartości typowe dla danego typu zasobu, a nie dopasowane do częstotliwości publikacji w konkretnym projekcie. Przy codziennych wdrożeniach nawet 30 dni dla plików bez hasha bywa zbyt długo.
• Nie wykryje hasha w nazwie pliku — decyzję o tym, czy plik ma wersjonowaną nazwę, podejmuje operator. Generator nie analizuje projektu ani listy plików, więc nie zgadnie, czy można bezpiecznie dodać immutable.
• Pomija warstwy przed Nginx — CDN, serwer pośredniczący albo proxy firmowe mogą nadpisywać lub ignorować nagłówki. Efekt w przeglądarce może się wtedy różnić od tego, co generuje konfiguracja.
• Nie sprawdza poprawności całej konfiguracji — wynik to fragment reguł do wklejenia. Kolejność bloków, kontekst http, server i location oraz składnia całości pozostają po Twojej stronie.

Najczęstsze pytania