Rozwiązywanie problemów

Niemal każdy raport “plugin nie działa” okazuje się jednym z punktów na tej stronie. Przejdź ją od góry do dołu.

Strona renderuje się bez layoutu (pusta lub domyślna)

Przyczyna: kategoria, produkt lub strona docelowa nie ma przypisanego bazowego layoutu.

Plugin to warstwa zastępowania — zastępuje istniejący layout. Nie wybiera go z niczego. Jeśli ukryta encja nie ma przypisanego layoutu, nie ma czego zastąpić, a Shopware nie ma czego renderować.

Rozwiązanie: przypisz bazowy layout w normalny sposób Shopware:

• Kategoria → otwórz kategorię → selektor strony CMS.
• Produkt → otwórz produkt → zakładka Layout.
• Strona docelowa → otwórz stronę docelową → selektor strony CMS (lub ustaw Default landing page layout).

Alternatywny layout się nie pojawia

Przejdź sprawdzenia w tej kolejności:

1. Czy reguła jest faktycznie przypięta do alternatywnego layoutu?

Otwórz layout w Shopping Experiences → Layout assignment → Assign layout → zakładka Rules. Reguła powinna być na liście. Jeśli modal w ogóle nie ma zakładki Rules, bundle admina plugina się nie załadował — wyczyść cache i przeładuj twardo.

2. Czy reguła zawiera niewspierane warunki?

Spójrz na kolumnę Status w zakładce Rules:

• ✓ Wszystkie wspierane — dobrze.
• ⚠ Częściowo wspierane — niewspierane warunki są po cichu pomijane; sprawdź jeszcze raz, czy wspierane nadal produkują trafienie, którego chcesz.
• ✗ Żadne nie wspierane — reguła nie może pasować. Layout nigdy nie zostanie wybrany.

Zobacz Własne warunki reguł dla wspieranej listy.

3. Czy Is homepage jest w AND z Sales Channel?

Najczęstszy błąd konfiguracji. Kombinacja pasuje tylko na navigation root kanału. Dla listingów i innych stron kategorii reguła nie pasuje.

Rozwiązanie: zobacz pułapkę w przepisie multi-sales-channel. Zwykle: usuń Is homepage i użyj samego Sales Channel.

4. Czy tryb zastępowania pozwala na podmianę?

Otwórz Settings → Extensions → Advanced Layouts Assigner, wybierz dotknięty kanał sprzedaży i sprawdź tryb:

• Category page → jeśli ustawione na With default layout, a kategoria używa niestandardowego layoutu, plugin nie zareaguje. Przełącz na All lub dodaj niestandardowy layout do Replaceable layouts.
• Product page → jeśli ustawione na Without assigned layout, a produkt ma specyficzny layout, plugin nie zareaguje. Przełącz na All lub jeden z innych trybów.
• Landing page → jeśli ustawione na With default layout, a strona docelowa używa niestandardowego layoutu, plugin nie zareaguje. Przełącz na All lub rozszerz allow-listę.

Zobacz Tryby zastępowania.

5. Czy typy zastępowania są puste dla rodzaju bazy?

W karcie Replacement types sprawdź wiersz pasujący do typu bazowego layoutu (nie alternatywy). Jeśli wiersz jest pusty, plugin nie szuka alternatyw dla tego rodzaju. Dodaj typ alternatywy do tego wiersza.

Przykład: baza to Listing page (typ product_list), alternatywa to Landing page (landingpage). Wiersz Listing page musi wymieniać Landing page.

Zobacz Typy zastępowania.

6. Czy jesteś powyżej cap 500 layoutów?

Plugin ewaluuje najwyżej 500 layoutów z regułami na request (LIMIT_TOTAL w PageLoadedSubscriber). Jeśli masz więcej, layouty powyżej cap (w kolejności rule.priority ASC) są pomijane. Obniż wartość priorytetu na regułach, które powinny wygrywać pierwsze.

Zobacz Wydajność.

Alternatywa pokazuje się na zbyt wielu stronach

Przyczyna: reguła jest za szeroka. Prawdopodobni winowajcy:

• Reguła z samym Always valid pasuje na każdej stronie.
• Reguła bez warunków w ogóle (lub tylko z niewspieranymi) jest traktowana jako ✗ niewspierana i pomijana — ale częściowo wspierana reguła może pasować szerzej niż myślisz, bo niewspierane warunki są po cichu usuwane.

Rozwiązanie: dodaj warunek Sales Channel. Dodaj warunek Is homepage jeśli naprawdę chcesz tylko strony głównej. Zainspektuj kolumnę Status w modal przypisania layoutu.

Pokazuje się zła alternatywa

Przyczyna: wiele layoutów pasuje do tego requesta i zła wygrywa.

Matcher wybiera pierwsze trafienie w kolejności rule.priority ASC. Niższy priorytet wygrywa pierwszy.

Rozwiązanie: ustaw regułę pożądanego layoutu na niższą wartość priorytetu niż jej konkurentów (Settings → Rules → Edit rule → Priority).

Zakładka Rules brakuje w modalu przypisania layoutu

Bundle admina plugina się nie załadował.

Rozwiązania:

• Potwierdź, że plugin jest aktywowany w Extensions → My extensions.
• Wyczyść cache admina: bin/console cache:clear.
• Przeładuj admin twardo (Ctrl+Shift+R), by porzucić cache’owane JS.
• Jeśli budujesz administrację samodzielnie, uruchom bin/build-administration.sh ponownie.
• Sprawdź, czy twoja rola użytkownika ma dostęp do nowych kluczy ACL.

Trzy własne warunki reguł nie pojawiają się w Rule Builderze

To samo rozwiązanie co powyżej — bundle admina się nie załadował. Warunki są rejestrowane w runtime admina.

Zastępowanie działa w storefront, ale nie w XHR widgetu nawigacji CMS

Ten widget XHR ma własne sprawdzenie (onCategoryEntityLoaded) bramkowane przez tryb zastępowania. Jeśli twój tryb Category page to With default layout, a kategoria używa niestandardowego layoutu, widget XHR też nie zostanie ruszony. Zobacz 5. Czy typy zastępowania są puste i 6. Czy tryb zastępowania pozwala powyżej.

Po zmianie trybów zastępowania nic się nie zmieniło w storefront

Wyczyść cache storefront: bin/console cache:clear (i prawdopodobnie twój cache HTTP / Varnish). Ustawienia plugina są czytane przez SystemConfigService Shopware, który jest cache’owany per request — przeterminowana strona w cache HTTP przeżyje zmianę ustawień.

Powiązane

• Jak to działa — model. Przeczytaj to ponownie najpierw, jeśli sprawdzenia 1–5 powyżej pozostawiają cię w niezrozumieniu.
• Przepis multi-sales-channel — kanoniczna konfiguracja z najczęstszą pułapką wymienioną wprost.
• Wewnętrzności przepływu zastępowania — dla deweloperów pluginu debugujących zachowanie.