Jak czyścić cache PrestaShop ręcznie

Ręczne czyszczenie cache w sklepie PrestaShop bywa konieczne, gdy panel nie odpowiada, zmiany w motywie nie są widoczne albo po aktualizacji pojawiają się błędy. To prosty, ale wrażliwy proces: dotykamy plików aplikacji, dlatego ważne są przygotowanie, kopia zapasowa i właściwa kolejność działań. Poniżej znajdziesz kompletną instrukcję dla wersji 1.6, 1.7 oraz 8.x, zarówno przez FTP/SSH, jak i z wiersza poleceń. Dobrze wykonane czyszczenie przywraca spójność sklepu i poprawia wydajność.

Kiedy i po co czyścić cache w PrestaShop ręcznie

Najczęstsze objawy wymagające interwencji

Ręczne czyszczenie jest wskazane, gdy:

• po wdrożeniu zmian w szablonie nadal widzisz starą wersję strony,
• panel administracyjny nie pozwala wyczyścić pamięci, bo operacja zawiesza się lub zwraca błąd,
• sklep wyświetla nielogiczne dane po aktualizacji modułów lub tłumaczeń,
• po migracji serwera pojawiają się komunikaty o braku klas lub błędnej kompilacji szablonów,
• występuje „biały ekran” (WSOD) i nie możesz włączyć trybu debug z panelu.

Jakie rodzaje pamięci podręcznej czyścimy

W PrestaShop funkcjonuje kilka warstw pamięci:

• kompilacja Smarty (szablony, widgety, fragmenty motywu),
• cache aplikacyjny (katalogi env dev/prod, pliki klas, kontenery DI),
• cache zasobów frontendu (skompilowane i zminifikowane CSS/JS),
• miniatury i pliki tymczasowe obrazów (generowane na żądanie),
• cache poziomu modułów (lokalne pliki, czasem we własnych katalogach).

Nie myl tego z mechanizmami zewnętrznymi, jak reverse proxy, CDN czy buforowanie PHP (OPcache). One mogą wymagać osobnego odświeżenia, ale w tym poradniku skupiamy się na strukturze plików sklepu.

Ryzyka i bezpieczne podejście

Usuwanie niektórych plików nie jest groźne (zostaną odtworzone), ale złe uprawnienia, przerwanie operacji czy czyszczenie nieodpowiedniego katalogu może unieruchomić sklep. Dlatego stosuj zasadę: przygotowanie, identyfikacja wersji, precyzyjne kasowanie i weryfikacja.

Przygotowanie środowiska: dostęp, kopia, tryb konserwacji

Narzędzia i dostęp

Do ręcznego czyszczenia potrzebujesz jednego z dwóch dostępów: klienta FTP (np. FileZilla, WinSCP) lub powłoki SSH (terminal). Gdy masz wybór, powłoka bywa szybsza i stabilniejsza na dużych katalogach. Przyda się także podstawowa znajomość struktury katalogów PrestaShop i statusu bieżącego środowiska (dev/prod).

Wykonanie pełnej kopii

Zanim cokolwiek usuniesz, zrób kopia plików i bazy. Minimum to archiwizacja katalogów cache, ale najlepsza praktyka to snapshot plików aplikacji i dump bazy (mysqldump lub eksport z panelu hostingu). Pozwala to wrócić do punktu wyjścia, gdyby cokolwiek poszło nie tak.

Tryb konserwacji i okno serwisowe

Na środowisku produkcyjnym ustaw krótkie okno serwisowe. Włącz tryb konserwacji w panelu (jeśli to możliwe) lub tymczasowo ogranicz dostęp regułami serwera www. Działania na pamięci podręcznej są zwykle szybkie, ale podczas odtwarzania kontenerów i kompilacji szablonów pierwsze żądania mogą być wolniejsze.

Właściwe uprawnienia i właściciel plików

Sprawdź, który użytkownik serwera www jest właścicielem plików (np. www-data, apache, nginx). Po czyszczeniu upewnij się, że katalogi cache mają prawa do zapisu dla procesu serwera. W środowiskach współdzielonych zwróć uwagę na restrykcje open_basedir i ewentualne ACL-e.

Czyszczenie cache w PrestaShop 1.6 i wczesnych 1.7

Gdzie znajdują się kluczowe katalogi

W PrestaShop 1.6 oraz wczesnych wydaniach 1.7 (do okolic 1.7.2) pamięć dla Smarty i klas znajduje się głównie w:

• /cache/smarty/compile – skompilowane szablony,
• /cache/smarty/cache – bufor treści Smarty,
• /cache/class_index.php – mapa klas, odtwarzana automatycznie,
• /img/tmp – pliki tymczasowe obrazów (warto czyścić, gdy miniatury „wariują”).

W niektórych konfiguracjach wczesnego 1.7 występuje także /app/cache/[dev|prod], ale jeśli nie widzisz tego katalogu, skup się na strukturze /cache i Smarty.

Czyszczenie przez FTP: krok po kroku

• Połącz się z serwerem przez klienta FTP i przejdź do katalogu instalacji sklepu.
• Wejdź do /cache/smarty/compile i usuń całą zawartość katalogu (pozostaw plik zabezpieczający index.php, jeśli istnieje).
• Wejdź do /cache/smarty/cache i usuń całą zawartość.
• Usuń plik /cache/class_index.php (zostanie odbudowany przy pierwszym żądaniu).
• Opcjonalnie wyczyść /img/tmp, jeśli modyfikowałeś rozmiary obrazów lub regenerowałeś miniatury.

Uwaga: nie usuwaj katalogu /cache ani /cache/smarty jako takich, a jedynie ich zawartość. Foldery te są oczekiwane przez aplikację.

Czyszczenie przez terminal (SSH)

Jeżeli masz powłokę, wykonasz operacje szybciej i bez ryzyka częściowego usunięcia plików, np. przy bardzo dużej liczbie obiektów:

• Przejdź do katalogu głównego sklepu: cd /ścieżka/do/sklepu
• Usuń zawartość katalogów kompilacji:
  • rm -rf cache/smarty/compile/*
  • rm -rf cache/smarty/cache/*
• Usuń mapę klas: rm -f cache/class_index.php
• Wyczyść pliki tymczasowe obrazów: rm -rf img/tmp/*

Po operacji zweryfikuj właściciela i prawa do zapisu: jeśli serwer nie może odtworzyć plików, pojawią się błędy uprawnień.

Dodatkowe czynności naprawcze

• Gdy sklep nadal nie działa, tymczasowo wyłącz nadpisania (overrides), zmieniając odpowiednią stałą w pliku konfiguracji (PS_DISABLE_OVERRIDES na true w defines.inc.php w 1.6). Następnie odśwież cache klas.
• Jeżeli zmieniałeś motyw, sprawdź uprawnienia katalogu themes/nazwa_motywu/cache lub themes/nazwa_motywu/assets (jeśli istnieją) i wyczyść ich zawartość.
• W przypadku niestandardowych modułów mających własne katalogi buforów zajrzyj do folderów modułów i usuń ich pliki cache, jeśli producent je tworzy.

Weryfikacja po czyszczeniu

Wejdź na stronę sklepu i panel administracyjny. Pierwsze wywołania mogą być wolniejsze (przebudowa). Zwróć uwagę na poprawność wyświetlania hooków, tłumaczeń i list produktów. Jeżeli widzisz błąd 500, sprawdź logi serwera www i katalóg /log/ (jeśli skonfigurowany).

Czyszczenie cache w PrestaShop 1.7/8 (warstwa Symfony)

Struktura katalogów: var/cache i środowiska

W PrestaShop 1.7.3+ i 8.x główna pamięć aplikacyjna znajduje się w katalogu var/cache. Występują co najmniej dwa środowiska:

• var/cache/prod – środowisko produkcyjny, używane przez sklep online,
• var/cache/dev – środowisko developerskie, używane podczas debugowania.

Kompilacja Smarty i zawartość kontenera DI lądują w podkatalogach var/cache/[env], dlatego czyszczenie zwykle sprowadza się do usunięcia całej zawartości tych katalogów. Dodatkowe artefakty frontendu mogą znaleźć się w public/assets lub themes/nazwa_motywu/assets.

Usuwanie ręczne przez FTP/SSH

• Połącz się z serwerem i przejdź do katalogu głównego instalacji.
• Usuń zawartość var/cache/prod oraz, jeśli używasz trybu dev, także var/cache/dev. Nie usuwaj samego katalogu var/cache – tylko jego zawartość.
• Opcjonalnie usuń zawartość public/assets (lub themes/…/assets), jeśli przebudowujesz pakiety frontendu i widzisz niespójności w wersjonowaniu plików.
• Wyczyść img/tmp, jeżeli regenerowałeś obrazy i widzisz zduplikowane miniatury.

Po tej operacji PrestaShop sam odbuduje katalogi cache przy pierwszym żądaniu. Jeśli masz ograniczenia wydajności na hostingu współdzielonym, pierwsze wejścia mogą chwilę potrwać.

Czyszczenie z wiersza poleceń (CLI)

W PrestaShop 1.7/8 dostępne są komendy oparte na Symfony Console, które szybko i poprawnie czyszczą bufor oraz przebudowują zależności:

• php bin/console cache:clear –env=prod –no-warmup
• php bin/console cache:warmup –env=prod

Dla trybu dev odpowiednio użyj –env=dev. Jeśli sklep jest aktywny, zastosuj najpierw clear bez warmupu, a następnie warmup, aby zminimalizować obciążenie pierwszych odwiedzin.

Elementy powiązane: Smarty, tłumaczenia, assets

• Jeśli korzystasz z mechanizmu opakowującego zasoby (kompilacja SCSS/JS), odśwież je zgodnie z instrukcją motywu (np. npm run build lub skrypt modułu). W przeciwnym razie stare pliki w public/assets mogą nadpisywać zmiany.
• W tłumaczeniach, po istotnych zmianach, czyszczenie var/cache zwykle wystarcza, ale w razie problemów wygeneruj ponownie katalogi tłumaczeń motywu.
• Po aktualizacji modułów skontroluj ich własne katalogi cache – niektóre tworzą lokalne bufory w modules/nazwa_modułu/var lub cache.

Sprawdzenie i rozgrzanie pamięci

Po czyszczeniu odwiedź kluczowe podstrony: strona główna, listing kategorii, karta produktu, koszyk, checkout, panel administracyjny. Sprawdź logi aplikacji (var/logs w trybie dev lub logi serwera) i upewnij się, że nie pojawiają się wyjątki kontenera DI ani błędy kompilacji Smarty. Jeśli korzystasz z narzędzi do monitoringu, potwierdź stabilizację czasu odpowiedzi.

Rozszerzone scenariusze i rozwiązywanie problemów

Biały ekran lub 500 po czyszczeniu

Jeżeli po usunięciu cache pojawia się błąd 500 lub „biały ekran”:

• Włącz tryb debug (1.7/8: edycja config/defines.inc.php, ustawienie _PS_MODE_DEV_ na true; następnie sprawdź komunikaty błędów na froncie/panelu).
• Zweryfikuj, czy usunąłeś zawartość, a nie sam katalog var/cache. Brak katalogów może blokować odtworzenie.
• Sprawdź prawa do zapisu i właściciela plików – serwer www musi móc utworzyć nowe pliki (patrz poniżej: uprawnienia).
• Jeśli błąd dotyczy modułu, tymczasowo wyłącz go przez zmianę nazwy folderu w modules/ lub wyłączenie nadpisań.
• W 1.6 usuń cache/class_index.php oraz katalogi cache Smarty jeszcze raz i odśwież stronę.

Prawa dostępu, SELinux i open_basedir

Najczęstsze problemy po czyszczeniu to błędne prawa lub właściciel. Katalogi var/ i cache/ muszą być zapisywalne przez użytkownika procesu www. Na serwerach z SELinux sprawdź konteksty (httpd_sys_rw_content_t). W środowiskach z open_basedir upewnij się, że ścieżki var/cache i img/tmp mieszczą się w dozwolonych katalogach. Po migracji między serwerami zastosuj chown do właściwego użytkownika i odśwież ACL-e, jeśli to konieczne.

Cache modułów, CDN i reverse proxy

Nawet po wyczyszczeniu pamięci aplikacyjnej zmiany mogą być nadal niewidoczne, jeśli:

• moduł posiada własny bufor i serwuje stare dane – zajrzyj do jego dokumentacji i katalogów modules/nazwa_modułu/cache lub var,
• stosujesz CDN z agresywnym TTL – odśwież zasoby lub dokonaj purge po patternie ścieżek,
• używasz reverse proxy (np. Varnish) – wykonaj purge ban (np. na host lub URL) albo tymczasowo omijaj cache po nagłówkach,
• przeglądarka trzyma lokalny cache – przetestuj na trybie prywatnym lub z parametrem wersjonującym w URL.

Automatyzacja i bezpieczne wdrażanie

W środowiskach CI/CD warto zautomatyzować sekwencję: build motywu, invalidate assets, cache:clear, cache:warmup, purge CDN. Dla PrestaShop 1.7/8 skrypty post-deploy mogą wywoływać komendy Console. W praktyce najlepsze rezultaty daje krótki warm-up bez ruchu klientów, a następnie przywrócenie ruchu i wykonanie purge na CDN.

Dobre praktyki po każdej operacji

• Trzymaj porządek w katalogach cache – nie kopiuj ręcznie artefaktów między środowiskami.
• Po większych zmianach motywu zawsze czyść var/cache (1.7/8) lub katalogi Smarty (1.6) oraz zweryfikuj assets.
• Ustal procedurę: backup, tryb konserwacji, czyszczenie, warm-up, testy dymne, powrót do normalnego trybu.
• Dokumentuj, które katalogi czyścisz i dlaczego – to ułatwia audyt oraz szybką diagnozę w przyszłości.

Stosując powyższe wskazówki oraz zachowując ostrożność i porządek, ręczne czyszczenie pamięci podręcznej PrestaShop stanie się bezpiecznym narzędziem w Twojej codziennej pracy administracyjnej, a sklep odzyska pełną stabilność i szybkość działania.