PrestaShop: wyszukiwarka nie działa. Przyczyny i naprawa

Gdy w PrestaShop wyszukiwarka nie działa, pierwszym podejrzanym jest nieaktualny indeks: w panelu wejdź w Preferencje, potem Szukaj, i przebuduj cały indeks wyszukiwania. Jeśli to nie pomoże, sprawdź po kolei minimalną długość słowa, czarną listę słów, widoczność produktów i wyszukiwanie rozmyte. Osobny przypadek to polska odmiana: wbudowana wyszukiwarka nie wie, że „myjki” i „myjka” to jedno słowo, i żadne ustawienie tego nie zmieni. Zostaje ręczne dopisywanie aliasów, forma po formie.

Od czego zacząć, gdy PrestaShop nie wyszukuje produktów?

Zacznij od tabeli: znajdź swój objaw, wykonaj sprawdzenie z trzeciej kolumny i dopiero potem zmieniaj ustawienia. Prawie wszystko jest na jednym ekranie panelu: Preferencje, potem Szukaj (w angielskiej wersji Shop Parameters, potem Search).

Nazwy opcji podaję po angielsku, tak jak w dokumentacji i kodzie PrestaShop 1.7 i 8. W polskim panelu są przetłumaczone, a brzmienie zależy od wersji, dlatego dopisuję, co każda robi.

Objaw	Prawdopodobna przyczyna	Jak sprawdzić	Naprawa
Nowych produktów nie ma w wynikach	Produkty nie trafiły do indeksu	W sekcji Indexing licznik „Indexed products” pokazuje mniej produktów, niż ma katalog	Kliknij „Add missing products to the index” i włącz automatyczne indeksowanie
Żadne zapytanie nic nie zwraca	Pusty indeks, na przykład po migracji albo imporcie prosto do bazy	Licznik pokazuje zero albo ułamek katalogu	„Re-build the entire index”, potem zadanie cron
Krótkie nazwy modeli, np. „S9”, nie działają	Słowo jest krótsze niż minimalna długość	Pole „Minimum word length (in characters)”	Zmniejsz wartość do 2 i przebuduj indeks
Jedno konkretne słowo nigdy nic nie znajduje	Słowo jest na czarnej liście	Pole „Blacklisted words” dla danego języka	Usuń słowo z listy i przebuduj indeks
„Myjki” nie znajduje produktu „myjka”	Brak odmiany, dopasowanie od początku słowa	Wpisz obie formy i porównaj wyniki	Alias dla każdej formy i spójne nazwy produktów albo wyszukiwarka, która rozumie odmianę
Literówka kończy się pustą stroną	Wyłączone wyszukiwanie rozmyte albo wersja starsza niż 1.7.7	Przełącznik „Fuzzy search”	Włącz opcję, a częste literówki dopisz jako aliasy
Produkt jest w sklepie, ale wyszukiwarka go pomija	Produkt nieaktywny albo z widocznością, która nie obejmuje wyszukiwarki	Karta produktu: status i widoczność	Zmień widoczność i zapisz produkt
Wyniki są, ale właściwy produkt jest daleko	Wagi pól faworyzują opis zamiast nazwy	Sekcja Weight	Podnieś wagę nazwy, obniż wagę opisu
W sklepie nie ma pola wyszukiwania	Moduł ps_searchbar jest wyłączony albo odpięty	Menedżer modułów	Włącz moduł i sprawdź jego zaczepy

Jak przebudować indeks wyszukiwania w PrestaShop 1.7 i 8?

Wejdź w Preferencje, potem Szukaj, i w sekcji Indexing kliknij „Re-build the entire index”. Ta sama sekcja pokazuje, ile produktów jest w indeksie w porównaniu z całym katalogiem, więc od razu widzisz, czy problem leży właśnie tutaj.

Indeks to spis słów ze wszystkich produktów. PrestaShop szuka wpisanych słów w tym spisie, a nie w opisach. Produkt, którego nie ma w indeksie, dla wyszukiwarki nie istnieje, nawet jeśli wyświetla się w kategorii.

W sekcji Indexing masz dwa linki:

• „Add missing products to the index” dopisuje tylko produkty, których w indeksie jeszcze nie ma. Działa szybko.
• „Re-build the entire index” buduje spis od zera. Trwa dłużej, ale jest dokładniejszy. Dokumentacja zaleca go po wielu zmianach w zaindeksowanych produktach.

Niżej jest przełącznik „Indexing”, czyli automatyczne indeksowanie. Gdy jest włączony, produkt trafia do indeksu przy zapisie w panelu, a według dokumentacji deweloperskiej także przy dodaniu lub zmianie przez Webservice. Produkty wgrane inną drogą, na przykład skryptem prosto do bazy danych, omijają ten mechanizm i wymagają ręcznej przebudowy albo zadania cron.

Po czym poznasz, że zadziałało: liczba zaindeksowanych produktów zbliżyła się do liczby produktów w katalogu, a testowe zapytania o nowe produkty zwracają wyniki. Do indeksu trafiają tylko produkty aktywne, z widocznością obejmującą wyszukiwarkę, więc licznik nie musi być równy całemu katalogowi.

Jak ustawić zadanie cron do indeksowania PrestaShop?

Gotowy adres do zadania cron PrestaShop wyświetla w sekcji Indexing, pod linkami do przebudowy. Wklej go do harmonogramu zadań na hostingu i ustaw wywołanie raz na dobę, w godzinach najmniejszego ruchu.

Przykład wpisu z dokumentacji deweloperskiej, pełna przebudowa codziennie o szóstej rano:

0 6 * * * curl "https://twojsklep.pl/admin-xxx/index.php?controller=AdminSearch&action=searchCron&ajax=1&full=1&token=xxxxxxxx"

• admin-xxx to nazwa katalogu panelu w Twoim sklepie.
• full=1 oznacza pełną przebudowę. Bez tego parametru albo z wartością 0 zadanie dopisze tylko brakujące produkty.
• token jest unikalny dla sklepu. Skopiuj cały adres z panelu i traktuj go jak hasło.

Dokumentacja zaznacza, że przy włączonym automatycznym indeksowaniu ręczne linki i cron nie są konieczne. Cron ma sens wtedy, gdy produkty trafiają do sklepu importem albo integracją z hurtownią.

Dlaczego „myjki” nie znajduje produktu „myjka”?

Bo wbudowana wyszukiwarka PrestaShop nie zna odmiany słów. Porównuje litery: domyślnie szuka w indeksie słów, które zaczynają się od wpisanego tekstu, a „myjka” nie zaczyna się od „myjki”.

W kodzie wyszukiwarki zapytanie jest czyszczone (małe litery, usunięcie znaków specjalnych), ale nie ma kroku, który sprowadza słowo do formy podstawowej. W praktyce:

• „myjk” znajdzie i „myjka”, i „myjki”, bo oba słowa tak się zaczynają,
• „myjki” znajdzie tylko produkty, w których to słowo występuje w tej właśnie formie,
• „myjek” nie pasuje do żadnej z tych form, więc o wyniku decyduje wyszukiwanie rozmyte.

Wyszukiwanie rozmyte pomaga tu tylko częściowo. Uruchamia się dopiero wtedy, gdy wpisane słowo nie pasuje do niczego w indeksie, i samo dobiera najbliższe słowo. Jeśli forma „myjki” występuje gdziekolwiek w katalogu, na przykład w nazwie „Wąż do myjki”, klient zobaczy akcesoria, a same myjki zostaną pominięte. Pustej strony nie będzie, więc tego problemu nie widać w statystykach zapytań bez wyników.

Masz dwa sposoby obejścia:

1. Alias, który zamienia formę wpisywaną przez klientów na formę z nazw produktów (opis w następnej sekcji).
2. Spójne nazewnictwo. Nazwa kategorii domyślnej też trafia do indeksu, więc kategoria „Myjki ciśnieniowe” z produktami „Myjka ciśnieniowa …” pokrywa obie formy.

Oba sposoby to obejścia, a nie naprawa: działają dla słów, które przewidziałeś, i tylko dopóki ktoś pilnuje listy. Opcja „Search within word” nie rozwiąże odmiany: „myjki” nadal nie jest fragmentem słowa „myjka”. W Searchkeen ten problem nie występuje, bo wyszukiwarka rozumie polską odmianę słów: „myjki”, „myjek” i „myjkę” prowadzą do tych samych produktów bez żadnego aliasu. Ten sam mechanizm stoi za częścią pustych stron opisanych w tekście o tym, skąd bierze się brak wyników wyszukiwania w sklepie.

Jak działają aliasy w PrestaShop?

Alias to reguła „gdy klient wpisze X, szukaj Y”. Dodajesz ją na górze ekranu ustawień wyszukiwania przyciskiem „Add new alias”. Działa od razu po zapisaniu, bez przebudowy indeksu.

Formularz ma dwa pola. W polu „Alias” wpisujesz słowa klientów, oddzielone przecinkami. W polu „Result” wpisujesz słowo, którego sklep ma szukać zamiast nich.

Alias	Result
myjki, myjek, myjke	myjka
adidasy, adidasow	sneakersy

Skąd brać listę? Dokumentacja wskazuje zakładkę „Shop search” na stronie statystyk, gdzie widać frazy wpisywane przez klientów.

Ograniczenie jest jedno, ale poważne: to praca ręczna i bez końca. Polski rzeczownik ma kilka do kilkunastu form, a każdą trzeba dopisać osobno, dla każdego ważnego słowa w katalogu i od nowa przy każdym nowym asortymencie. Alias nie obejmie też formy, której nikt nie przewidział. Jak zbudować taki słownik i nie zepsuć wyników zbyt szerokimi regułami, opisuje poradnik jak ustawić synonimy w wyszukiwarce sklepu.

Które ustawienia wyszukiwania mogą po cichu ucinać wyniki?

Pięć opcji z sekcji Search: minimalna długość słowa, czarna lista, dwa tryby dopasowania i wyszukiwanie rozmyte. Każda potrafi wyciąć z wyników poprawne zapytania, a po zmianie dwóch pierwszych trzeba przebudować indeks.

• Minimum word length (in characters). Do indeksu trafiają tylko słowa tej długości lub dłuższe. Wpis zespołu PrestaShop o wyszukiwaniu rozmytym podaje wartość domyślną 3 i radzi zejść do 2, gdy masz krótkie nazwy modeli w rodzaju „S9”. Uwaga na zapis ze spacją: „K 5” to dla wyszukiwarki dwa jednoznakowe słowa i oba są za krótkie.
• Blacklisted words. Lista słów pomijanych przy indeksowaniu i szukaniu, osobna dla każdego języka, ze słowami oddzielonymi pionową kreską. Domyślnie zawiera krótkie, pospolite słowa. Jeśli ktoś dopisał tam wyraz, który u Ciebie jest nazwą produktu, wyszukiwarka będzie go ignorować.
• Search within word. Domyślnie dopasowanie zaczyna się od początku słowa. Po włączeniu wpisany tekst może być fragmentem w dowolnym miejscu (przykład z dokumentacji: „lou” znajduje „blouse”). Wyników będzie więcej, ale mniej trafnych.
• Search exact end match. Wymusza zgodność końca słowa. Według dokumentacji „book” znajdzie wtedy „notebook”, ale nie „bookcase”. Włączona przez przypadek wyłącza szukanie po początku słowa, czyli „myjk” przestaje znajdować „myjka”.
• Fuzzy search. Tolerancja literówek, dostępna od wersji 1.7.7 (przykład z dokumentacji: „ummingbird” znajduje „hummingbird”). Towarzyszą jej dwa pola: „Maximum approximate words allowed by fuzzy search”, domyślnie 4, oraz „Maximum word length (in characters)”, dla którego dokumentacja zaleca 15.

Jak ustawić wagi pól, żeby właściwy produkt był na górze?

Wagi w sekcji Weight decydują, które pole produktu liczy się bardziej przy układaniu wyników. Jeśli klient wpisuje nazwę, a na górze lądują produkty, które mają to słowo tylko w opisie, podnieś wagę nazwy i obniż wagę opisu.

Wartości domyślne z dokumentacji deweloperskiej:

Pole (etykieta w panelu)	Co obejmuje	Waga domyślna
Reference weight	Indeks, EAN13, ISBN, UPC, MPN, także z kombinacji	10
Product name weight	Nazwa produktu	6
Tags weight	Tagi	4
Category weight	Nazwa kategorii	3
Brand weight	Marka	3
Attributes weight	Atrybuty kombinacji	2
Features weight	Cechy	2
Short description weight	Krótki opis	1
Description weight	Opis	1

Zasada z panelu: słowo z wagą 8 jest warte cztery razy więcej niż słowo z wagą 2. Waga 0 wyłącza pole z indeksu, a zmiana na zero lub z zera wymaga pełnej przebudowy. Wyłączenie opisu pomaga tam, gdzie opisy wymieniają inne produkty („pasuje do modeli…”) i ściągają do wyników niewłaściwe pozycje.

Co sprawdzić w module ps_searchbar?

Moduł ps_searchbar odpowiada tylko za pole wyszukiwania i listę podpowiedzi w nagłówku sklepu, a nie za trafność wyników. Zajrzyj do niego wtedy, gdy pole zniknęło albo podpowiedzi przestały się rozwijać.

Z repozytorium modułu wynika kilka faktów przydatnych przy diagnozie:

• bieżąca wersja wymaga PrestaShop 1.7.8.0 lub nowszego,
• moduł podpina się do zaczepów displayTop, displaySearch i displayHeader, więc szablon sklepu musi któryś z nich wywoływać,
• nie ma własnego ekranu konfiguracji: wszystko, co dotyczy wyników, ustawiasz w Preferencjach,
• podpowiedzi pobierają do dziesięciu produktów z tej samej wyszukiwarki, więc przy pustym indeksie też będą puste.

Jeśli pole zniknęło po zmianie szablonu, zacznij od menedżera modułów: sprawdź, czy moduł jest zainstalowany i włączony.

Jak zapobiec powrotowi problemu?

Awariom indeksu zapobiegają trzy nawyki: nocny cron z pełną przebudową, krótki test po każdym imporcie i comiesięczny przegląd fraz wpisywanych przez klientów. Odmiany i zapisu modeli te nawyki nie naprawią: tam zostaje stałe dopisywanie aliasów.

• Ustaw w harmonogramie hostingu nocne zadanie cron z parametrem pełnej przebudowy indeksu.
• Trzymaj listę 10–20 zapytań testowych: nazwy bestsellerów, numery modeli, formy w liczbie mnogiej, jedna literówka. Wpisuj je po każdym imporcie, aktualizacji sklepu i zmianie ustawień.
• Raz w miesiącu przejrzyj statystyki wyszukiwania i dopisz aliasy dla powtarzających się fraz.

Pełną listę usprawnień znajdziesz w przewodniku jak zoptymalizować wyszukiwarkę w sklepie w 12 krokach. Jeśli oprócz wyszukiwania kuleją filtry w kategoriach, osobny poradnik opisuje konfigurację nawigacji fasetowej w PrestaShop.

Czego wbudowana wyszukiwarka PrestaShop nie zrobi?

Nie odmieni polskiego słowa, nie połączy różnych zapisów tego samego modelu i nie pokaże, że odmieniona fraza zwróciła akcesoria zamiast produktu. Indeks, cron i wagi naprawisz raz. Te trzy rzeczy wracają, bo wynikają z konstrukcji mechanizmu, a nie z błędu w ustawieniach.

Sygnały, że doszedłeś do tej granicy:

• klienci wpisują formy odmienione i dostają akcesoria zamiast produktów głównych,
• model wpisany ze spacją nie znajduje produktu, który w nazwie ma zapis łączny,
• lista aliasów rośnie szybciej, niż jesteś w stanie ją utrzymać, a każdy nowy asortyment oznacza kolejną turę dopisywania,
• raport pustych wyników wygląda dobrze, a klienci i tak dzwonią, że nie mogą znaleźć produktu.

Możesz dalej łatać to aliasami albo mieć to rozwiązane. Searchkeen to wyszukiwarka produktów podłączana do sklepu jednym skryptem: czyta produkty z API PrestaShop w trybie tylko do odczytu, rozumie polską odmianę słów, literówki, brak polskich znaków i numery modeli zapisane na różne sposoby. Panel pokazuje wyszukiwane frazy i zapytania bez wyników oraz podpowiada synonimy na podstawie wyszukiwań. Gdy przedpłacone tokeny się skończą, wraca dotychczasowa wyszukiwarka sklepu, więc klient nie zostaje bez pola szukania. Podłączenie krok po kroku opisuje strona Searchkeen dla PrestaShop, a zasady rozliczenia cennik pakietów tokenów.