Własny CSS i JavaScript w PrestaShop bez problemów po aktualizacjach

Ostatnia aktualizacja: czerwiec 2026, cztery opisane niżej metody odporne na aktualizacje dotyczą PrestaShop od wersji 1.7 do 9 (w tym potoku SCSS motywu Hummingbird). Przykłady kodu korzystają z API register* dla zasobów, dostępnego od wersji 1.7.

Zmieniasz kolor przycisku. Otwierasz arkusz stylów motywu, edytujesz go, przycisk wygląda jak trzeba. Trzy tygodnie później aktualizujesz motyw, żeby wgrać poprawkę bezpieczeństwa, a Twoja zmiana znika, po cichu nadpisana, bez ostrzeżenia i bez śladu tego, co zostało zmienione. Każdy sprzedawca korzystający z PrestaShop, który personalizuje sklep przez edycję plików rdzenia, prędzej czy później trafia na tę ścianę, a najbardziej frustrujące jest to, że można jej całkowicie uniknąć. Platforma daje kilka miejsc odpornych na aktualizacje, w których można umieścić własny CSS i JavaScript; rzecz w tym, żeby wiedzieć, które miejsce pasuje do konkretnej zmiany i dlaczego podejście „po prostu edytuj motyw” tak często kończy się cichą porażką. Ten poradnik jest dokładnie o tym: gdzie powinien znajdować się własny kod, aby aktualizacja motywu, rdzenia albo modułu nigdy go nie skasowała.

Dlaczego edycja plików motywu i modułów to pułapka

Motyw PrestaShop to zestaw plików na dysku: szablony Smarty (.tpl), arkusze stylów i JavaScript, wszystko umieszczone w katalogu /themes/your-theme/. Gdy aktualizujesz taki motyw, niezależnie od tego, czy ponownie wgrywasz nowszy plik ZIP, czy instalujesz poprawkę od dostawcy, proces aktualizacji zastępuje te pliki w całości nową wersją. Nie scala Twoich edycji; po prostu je nadpisuje. To samo dotyczy każdego modułu: jego zasoby znajdują się w /modules/module-name/views/, a aktualizacja modułu zastępuje cały ten katalog. Bez porównania zmian, bez pytania, bez kopii zapasowej. Twoja praca po prostu znika, a ponieważ nic nie zgłasza błędu, często zauważasz to dopiero wtedy, gdy zrobi to klient.

Co to oznacza w praktyce? Każda godzina poświęcona na edycję plików rdzenia to godzina, którą spędzisz ponownie przy następnej aktualizacji, a „następna aktualizacja” nie jest opcjonalna, bo właśnie tak do sklepu trafiają poprawki bezpieczeństwa i błędów. Cały sens poniższych metod polega na przerwaniu tego cyklu: zapisujesz własne modyfikacje raz, w miejscu, którego aktualizator nie dotyka, i przestajesz odtwarzać utraconą pracę.

Dopasuj metodę do zmiany

Nie istnieje jeden „właściwy” sposób dodawania własnego kodu, istnieje właściwy sposób dla Twojej zmiany. Jednolinijkowa korekta koloru i pełna przebudowa warstwy wizualnej powinny trafić w zupełnie inne miejsca. Wybierz najlżejszą metodę, która przetrwa aktualizacje i wykona zadanie:

Poniższe sekcje omawiają każdą z tych metod w szczegółach charakterystycznych dla PrestaShop. Dwie z nich zahaczają o tematy, które mają własne, osobne poradniki, motywy potomne i bloki HTML w panelu administracyjnym, dlatego zamiast powtarzać tutaj pełne omówienie, ten artykuł skupia się na elemencie wspólnym dla wszystkich czterech: zabezpieczeniu własnego kodu przed aktualizacjami.

Metoda 1, plik custom.css (dla małych korekt CSS)

Większość nowoczesnych motywów PrestaShop zawiera pusty plik custom.css, który motyw ładuje po wszystkich pozostałych arkuszach stylów. Ponieważ ładuje się jako ostatni, Twoje reguły naturalnie wygrywają kaskadę, co czyni go wygodnym miejscem na kilka szybkich poprawek. Trzeba jednak pamiętać, że custom.css zwykle znajduje się wewnątrz drzewa motywu, więc z definicji nie jest odporny na aktualizacje. Plik ZIP motywu albo aktualizacja od dostawcy mogą go zastąpić. Jeśli zależy Ci na rzeczywistym bezpieczeństwie przy aktualizacjach, umieść reguły w motywie potomnym albo w bloku kodu z panelu administracyjnego; własny custom.css motywu zostaw na tymczasowe korekty kolorów, odstępów lub krojów pisma, które w razie potrzeby możesz odtworzyć.

Wiele motywów, w tym motywy w stylu Classic (Classic jest domyślnym motywem PrestaShop 8), ładuje /themes/your-theme/assets/css/custom.css; nowszy motyw Hummingbird to kolejna nowoczesna opcja. Obsługa custom.css i dokładna ścieżka zależą jednak od motywu, więc nie zakładaj, że to uniwersalne natywne zachowanie, niektóre starsze lub komercyjne motywy używają zamiast tego /themes/your-theme/css/custom.css, a niewielka część nie podłącza go w ogóle. Sprawdź rejestrację zasobów aktywnego motywu albo jego dokumentację i poszukaj istniejącego, często pustego pliku custom.css, zanim utworzysz własny. Wrzucasz reguły, na przykład nadpisanie głównego przycisku w stylu .btn-primary { background-color: #2c3e50; border-color: #2c3e50; }, czyścisz pamięć podręczną i gotowe.

Zanim oprzesz się na tym rozwiązaniu, poznaj jego ograniczenia. custom.css obsługuje tylko CSS, bez JavaScriptu. Ładuje się na każdej stronie, niezależnie od tego, czy dana reguła jest tam potrzebna, i nie daje możliwości kierowania zmian na konkretny typ strony, grupę klientów czy sklep. Poza tym niewielka część motywów w ogóle go nie podłącza. Przy kilku poprawkach te ograniczenia nie mają znaczenia; gdy tylko zaczną mieć, przejdź do jednej z metod poniżej.

Metoda 2, motyw potomny (dla dużej, stałej personalizacji)

Gdy wprowadzasz więcej niż kilka zmian, edytujesz szablony, przebudowujesz wygląd całych sekcji, dokładasz własny JavaScript, motyw potomny jest odpornym na aktualizacje miejscem na całość. Motyw potomny dziedziczy wszystko po motywie nadrzędnym i pozwala nadpisywać tylko te konkretne pliki, na których Ci zależy, w osobnym katalogu, do którego aktualizacje rodzica nie sięgają. Wskazujesz rodzica w config/theme.yml (klucz parent: zawiera nazwę folderu motywu nadrzędnego), kopiujesz wyłącznie pliki, które nadpisujesz, i dodajesz obok nich własny custom.css oraz pliki .js.

To właściwe rozwiązanie dla poważniejszej personalizacji, a temat jest na tyle szeroki, że zasługuje na osobne omówienie zamiast pośpiesznego akapitu, łącznie z najważniejszym powodem, dla którego buduje się motyw potomny zamiast edytować rodzica bezpośrednio. Opisaliśmy to szczegółowo w artykule motywy potomne w PrestaShop: dlaczego nigdy nie należy edytować motywu nadrzędnego. Jeśli nie masz jeszcze wybranego motywu do personalizacji, zacznij krok wcześniej od poradnika jak wybrać właściwy motyw PrestaShop dla swojego biznesu, motyw nadrzędny przyjazny motywom potomnym oszczędzi Ci później wielu problemów.

Metoda 3, wstrzykiwanie kodu z panelu administracyjnego (bez dostępu do plików)

Bloki w panelu administracyjnym trzymają małe fragmenty HTML, CSS i JavaScriptu poza plikami motywu.

Jeśli nie masz dostępu przez SSH lub FTP, nie chcesz go mieć albo po prostu nie chcesz ponownie wdrażać plików z powodu jednolinijkowego fragmentu śledzącego, moduł bloków kodu pozwala dodać własny CSS, JavaScript i HTML bezpośrednio z panelu administracyjnego PrestaShop. Kod trafia do bazy danych, a nie do żadnego pliku motywu czy modułu, i właśnie dlatego aktualizacja motywu albo rdzenia nie może go ruszyć, a Ty możesz wyłączyć blok, aby natychmiast cofnąć jego efekt, bez usuwania czegokolwiek.

To codzienne narzędzie do dodania skryptu Google Analytics lub Meta Pixel, wrzucenia sezonowego nadpisania CSS do sekcji head strony albo umieszczenia banera promocyjnego, i temat zdecydowanie zasługuje na własny poradnik, a nie tylko akapit tutaj. Pokazujemy to krok po kroku w artykule Bloki HTML: dodawanie własnej treści w dowolnym miejscu sklepu PrestaShop, który obejmuje przypisywanie bloków do hooków oraz wyświetlanie ich tylko na wybranych stronach lub wybranym grupom klientów. Nasz moduł mprhtmlblocks został zbudowany dokładnie do tego, własny kod zarządzany z panelu administracyjnego, kierowany do konkretnych hooków i wyświetlany warunkowo, bez niczego, co kolejna aktualizacja mogłaby nadpisać.

Metoda 4, mały własny moduł z hookami zasobów (dla programistów)

Dla programistów najczystszym i najbardziej kontrolowalnym miejscem na własne zasoby jest niewielki moduł, który rejestruje je przez natywny mechanizm zarządzania zasobami PrestaShop. Jest całkowicie niezależny od motywu, w drzewie motywu nie ma nic do nadpisania, więc przetrwa zarówno zmianę motywu, jak i aktualizację rdzenia, a dodatkowo daje warunkowe ładowanie, którego nie da się uzyskać z custom.css.

Cała praca odbywa się w jednym hooku, hookActionFrontControllerSetMedia(). W jego wnętrzu wywołujesz na kontrolerze registerStylesheet() i registerJavascript(), przekazując identyfikator zasobu, ścieżkę w swoim module oraz tablicę opcji. Właśnie te opcje są przewagą nad starszymi wywołaniami addCSS() / addJS() z czasów 1.6: priority (wyższe liczby ładują się później, co pozwala zagwarantować, że skrypt uruchomi się po skryptach motywu), zapytanie media, pozycja JS position ustawiona na bottom oraz atrybuty async/defer. W PrestaShop 1.7 i nowszych preferuj metody register*; po addCSS/addJS sięgaj tylko wtedy, gdy utrzymujesz sklep na 1.6.

public function install()
{
    return parent::install()
        && $this->registerHook('actionFrontControllerSetMedia');
}

public function hookActionFrontControllerSetMedia($params)
{
    if (!$this->context->controller instanceof ProductController) {
        return;
    }

    $this->context->controller->registerStylesheet(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/css/product.css',
        ['media' => 'all', 'priority' => 200]
    );

    $this->context->controller->registerJavascript(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/js/product.js',
        ['position' => 'bottom', 'priority' => 200]
    );
}

Błąd addCSS z parametrem w adresie, który warto znać

Istnieje stara pułapka, w której addCSS() użyte z parametrem do omijania pamięci podręcznej (czymś w rodzaju ?v=1.2.3) może wygenerować ścieżkę, którą PrestaShop zniekształca, przez co arkusz stylów widać w źródle strony, ale przeglądarka nigdy go nie stosuje. To wyjątkowo irytujące przy debugowaniu, bo nie pojawia się żaden błąd 404. Jeśli wersjonujesz zasoby, użyj registerStylesheet(), które obsługuje wersjonowanie poprawnie.

Ładowanie warunkowe. Tylko tam, gdzie jest potrzebne

Prawdziwym powodem, dla którego programiści sięgają po moduł, jest ładowanie warunkowe. W tym samym hooku możesz sprawdzić $this->context->controller i zarejestrować zasoby tylko wtedy, gdy pasują do danej sytuacji, na przykład sprawdzając instanceof ProductController przed dodaniem CSS dla strony produktu albo instanceof OrderController przed dodaniem JavaScriptu do finalizacji zamówienia. Korzyść jest konkretna: własny kod nie trafia na 90% stron, które go nie potrzebują, więc nie płacisz za niego czasem ładowania każdej strony. Ta sama zasada, ładuj lekko, ładuj późno, pomaga utrzymać szybkość spersonalizowanego sklepu i stoi za tym, aby małe elementy front-endowe, takie jak przycisk powrotu na górę, dostarczać jako właściwe zasoby warunkowe, a nie jako skrypt inline wrzucony do szablonu.

JavaScript wymaga więcej ostrożności niż CSS

CSS rzadko stawia opór; JavaScript potrafi. Większość problemów bierze się z dwóch rzeczy. Po pierwsze, jQuery: PrestaShop 1.7+ dostarcza jQuery 3.x w części sklepowej, więc jeśli Twój skrypt zależy od jQuery, nadaj mu wystarczająco wysoki priorytet, aby załadował się po jQuery, w przeciwnym razie zobaczysz „$ is not defined” już przy pierwszym renderowaniu. Panel administracyjny rządzi się własnymi prawami (starsze wersje miały jQuery 1.x, nowsze 3.x), więc zanim napiszesz skrypt administracyjny pod założoną wersję, sprawdź źródło strony.

Po drugie, i to jest zasada, którą najczęściej chce się złamać: nigdy nie umieszczaj surowego tagu <script> w szablonie Smarty. Wydaje się szybkie, ale skrypt inline omija zarządzanie zasobami PrestaShop. Nie będzie zarządzany ani łączony przez CCC (Combine, Compress, Cache), i może wejść w konflikt z Content Security Policy w sklepach, które ustawiają nagłówek CSP. JavaScript zawsze dostarczaj jako zewnętrzny plik .js zarejestrowany przez właściwy hook. Jeśli chodzi o nowoczesną składnię, funkcje strzałkowe, async/await, moduły ES. W PrestaShop 8 i 9 jest w porządku, bo IE11 nie jest już problemem; jeśli nadal obsługujesz sklepy 1.7 z ruchem ze starszych przeglądarek, może być potrzebna transpilacja przez Babel.

Gdy własny CSS „nie działa”: specyficzność

Najczęstsza sytuacja typu „mój własny CSS jest ignorowany” wcale nie jest problemem aktualizacji, to specyficzność. Twoja reguła ładuje się poprawnie, ale selektor motywu jest bardziej szczegółowy, więc przeglądarka stosuje styl z motywu. Rozwiązanie, w preferowanej kolejności:

• Dopasuj selektor motywu. Otwórz narzędzia deweloperskie, znajdź dokładny selektor używany przez motyw i napisz własny tak, aby mu odpowiadał. Ponieważ custom.css ładuje się jako ostatni, równie szczegółowy selektor już wygrywa.
• Dodaj rodzica, żeby zwiększyć wagę. Jeśli samo dopasowanie nie wystarcza, zawęź zakres, #wrapper .btn-primary wygrywa z samym .btn-primary bez uciekania się do siłowych metod.
• Używaj !important tylko naprawdę w ostateczności. Działa, ale każde dodane !important utrudnia kolejne nadpisanie i prowadzi do wyścigu specyficzności, który później trzeba będzie rozplątać.

Testowanie: dlaczego „zmieniłem to i nic się nie stało”

Zmiany własnego CSS i JS, które wyglądają tak, jakby nic nie robiły, prawie zawsze zatrzymują się na którejś warstwie pamięci podręcznej, a nie na samym kodzie. Sprawdź po kolei:

• Wyczyść pamięć podręczną PrestaShop. Przejdź do Zaawansowane → Wydajność i po każdej zmianie kliknij Wyczyść pamięć podręczną. Podczas pracy nad szablonami ustaw Wymuś kompilację na Tak, aby Smarty renderował je ponownie.
• Uważaj na CCC. Gdy Combine, Compress, Cache jest włączone, pojedyncze pliki są łączone w paczki, co może zmienić kolejność ładowania. Jeśli coś zachowuje się dziwnie, tymczasowo wyłącz CCC, żeby odizolować problem, a potem włącz je ponownie na produkcji.
• Skorzystaj z przeglądarki. Karta Network potwierdzi, że plik faktycznie się załadował (200, nie 404); karta Elements pokaże, czy reguła została zastosowana, czy przekreślona przez bardziej szczegółową.
• Wyczyść CDN. Jeśli używasz Cloudflare albo innego CDN, wyczyść go po zmianach zasobów, nieaktualne kopie na brzegu sieci stoją za ogromną częścią zgłoszeń typu „ale przecież już to zmieniłem”.

Krótka wersja

• Nigdy nie edytuj bezpośrednio plików motywu ani modułu, kolejna aktualizacja nadpisze je bez ostrzeżenia.
• 1–5 małych korekt CSS: wrzuć je do custom.css.
• Duże, stałe zmiany: zbuduj motyw potomny.
• Brak dostępu do plików albo szybkie fragmenty kodu: użyj bloku HTML/kodu w panelu administracyjnym.
• Programista, ładowanie warunkowe: mały moduł z registerStylesheet() / registerJavascript().
• Dostarczaj JS jako pliki zewnętrzne, ładuj je na dole, po zmianach czyść każdą pamięć podręczną i trzymaj kopię własnych modyfikacji poza katalogiem motywu.

Personalizacja PrestaShop i przetrwanie aktualizacji nie stoją ze sobą w sprzeczności, tak wygląda to tylko wtedy, gdy kod znajduje się w złym miejscu. Wybierz najlżejszą metodę odporną na aktualizacje dla zmiany, którą masz przed sobą, a aktualizacja motywu stanie się tym, czym powinna być: rutynowym kliknięciem, nie dniem odtwarzania utraconej pracy. Jeśli wolisz zarządzać własnym kodem z panelu administracyjnego, zamiast w ogóle dotykać plików, nasz moduł mprhtmlblocks pozwala wstrzykiwać i włączać lub wyłączać bloki HTML, CSS i JavaScriptu blok po bloku, zapisane w bazie danych i nietknięte przez kolejną aktualizację.

Najczęściej zadawane pytania

Czy plik custom.css motywu naprawdę jest odporny na aktualizacje?

Nie w pełni. Ponieważ custom.css zwykle znajduje się w drzewie motywu, plik ZIP motywu albo aktualizacja od dostawcy mogą zastąpić go razem z całą resztą. Jest wygodny, ładuje się jako ostatni, więc Twoje reguły wygrywają kaskadę, ale traktuj go jako miejsce na tymczasowe poprawki, które możesz odtworzyć. Dla rzeczywistego bezpieczeństwa przy aktualizacjach umieszczaj reguły w motywie potomnym albo w bloku kodu w panelu administracyjnym, gdzie aktualizator ich nie dosięgnie.

Mój własny CSS się ładuje, ale styl motywu nadal wygrywa. Co jest nie tak?

To problem specyficzności, a nie aktualizacji czy pamięci podręcznej. Selektor motywu jest bardziej szczegółowy niż Twój, więc przeglądarka stosuje styl motywu. Otwórz narzędzia deweloperskie, znajdź dokładny selektor używany przez motyw i napisz własny tak, aby mu odpowiadał, ponieważ custom.css ładuje się jako ostatni, równoważny selektor już wygrywa. Dodaj rodzica zawężającego, na przykład #wrapper, tylko jeśli dopasowanie nie wystarcza, a po !important sięgaj wyłącznie naprawdę w ostateczności.

Czy mogę po prostu wkleić tag <script> do szablonu?

Nie. Skrypt inline omija zarządzanie zasobami PrestaShop, więc nie zostanie połączony przez CCC, a w sklepach z nagłówkiem Content Security Policy może przestać działać. JavaScript zawsze dostarczaj jako zewnętrzny plik .js zarejestrowany przez hookActionFrontControllerSetMedia() za pomocą registerJavascript() albo przez blok kodu w panelu administracyjnym, nigdy jako surowy kod w .tpl.

Jak ładować mój CSS lub JS tylko na wybranych stronach?

To główny powód, żeby użyć małego modułu zamiast custom.css. Wewnątrz hookActionFrontControllerSetMedia() sprawdzasz $this->context->controller i rejestrujesz zasób tylko wtedy, gdy pasuje, na przykład instanceof ProductController dla CSS strony produktu albo instanceof OrderController dla JS finalizacji zamówienia. Dzięki temu kod nie trafia na strony, które go nie potrzebują, więc nie płacisz za niego przy każdym ładowaniu strony.

Dlaczego mój skrypt zgłasza „$ is not defined”?

Twój JavaScript uruchamia się, zanim załaduje się jQuery. PrestaShop 1.7+ dostarcza jQuery 3.x w części sklepowej, więc ustaw skryptowi wystarczająco wysokie priority w registerJavascript(), aby ładował się po jQuery. Panel administracyjny to osobne środowisko, starsze wersje miały jQuery 1.x, dlatego przed pisaniem skryptu administracyjnego pod założoną wersję sprawdź źródło strony.

Zmieniłem CSS i nic się nie stało. Gdzie szukać?

Prawie zawsze na warstwie pamięci podręcznej, nie w samym kodzie. Idź po kolei: wyczyść pamięć podręczną PrestaShop w Zaawansowane → Wydajność; tymczasowo wyłącz CCC (Combine, Compress, Cache), jeśli kolejność ładowania wygląda podejrzanie; potwierdź w karcie Network przeglądarki, że plik załadował się ze statusem 200, a nie 404; i wyczyść CDN (Cloudflare oraz podobne usługi), nieaktualne kopie na brzegu sieci powodują ogromną część zgłoszeń typu „ale przecież już to zmieniłem”.

Czy nadal używać addCSS() i addJS()?

Tylko w sklepie 1.6. W PrestaShop 1.7 i nowszych preferuj registerStylesheet() oraz registerJavascript(), pozwalają ustawić priority, zapytania media, pozycję JS na dole, async/defer i poprawnie obsługują wersjonowanie omijające pamięć podręczną. Stare addCSS() ma od dawna znany błąd, przez który parametr ?v= może zniekształcić ścieżkę tak, że plik pojawia się w źródle, ale nigdy się nie stosuje, bez żadnego błędu 404, który naprowadziłby Cię na problem.

Powiązane poradniki

• Motywy potomne w PrestaShop: dlaczego nigdy nie należy edytować motywu nadrzędnego
• Bloki HTML: dodawanie własnej treści w dowolnym miejscu sklepu PrestaShop
• Przycisk powrotu na górę: mały detal UX, który zaskakująco dużo znaczy