Fehlerbehebung

Fast jede “das Plugin funktioniert nicht”-Meldung stellt sich als einer der Punkte auf dieser Seite heraus. Gehen Sie sie von oben nach unten durch.

Die Seite rendert ohne Layout (leer oder Default)

Ursache: der Kategorie, dem Produkt oder der Landing-Seite ist kein Basislayout zugewiesen.

Das Plugin ist eine Ersetzungsschicht — es ersetzt ein bestehendes Layout. Es wählt keines aus dem Nichts. Wenn die zugrundeliegende Entity keine Layout-Zuweisung hat, gibt es nichts zu ersetzen und Shopware hat nichts zu rendern.

Lösung: ein Basislayout auf normalem Shopware-Weg zuweisen:

Kategorie → Kategorie öffnen → CMS-Seiten-Auswahl.
Produkt → Produkt öffnen → Tab Layout.
Landing-Seite → Landing-Seite öffnen → CMS-Seiten-Auswahl (oder ein Standard-Landing-Seiten-Layout setzen).

Das Alternativlayout erscheint nicht

Gehen Sie die Prüfungen in dieser Reihenfolge durch:

1. Ist die Regel dem Alternativlayout tatsächlich zugewiesen?

Öffnen Sie das Layout in Erlebniswelten → Layout-Zuweisung → Layout zuweisen → Tab Regeln. Die Regel sollte in der Liste sein. Wenn das Modal überhaupt keinen Tab Regeln hat, ist das Admin-Bundle des Plugins nicht geladen — Cache leeren und hart neu laden.

2. Enthält die Regel nicht unterstützte Bedingungen?

Sehen Sie sich die Spalte Status im Tab Regeln an:

✓ Alle unterstützt — gut.
⚠ Teilweise unterstützt — nicht unterstützte Bedingungen werden stillschweigend übersprungen; prüfen Sie nochmal, ob die unterstützten den gewünschten Treffer ergeben.
✗ Keine unterstützt — die Regel kann nicht passen. Das Layout wird nie ausgewählt.

Siehe Eigene Regelbedingungen für die unterstützte Liste.

3. Ist `Ist Startseite` in einem UND mit `Verkaufskanal`?

Der häufigste Konfigurationsfehler. Die Kombination passt nur auf der Stammnavigation des Kanals. Für Listings und andere Kategorienseiten passt die Regel nicht.

Lösung: siehe den Fallstrick im Mehrere-Verkaufskanäle-Rezept. Meist: Ist Startseite weglassen und nur Verkaufskanal verwenden.

4. Erlaubt der Ersetzungsmodus den Tausch?

Öffnen Sie Einstellungen → Erweiterungen → Advanced Layouts Assigner, wählen Sie den betroffenen Verkaufskanal und prüfen Sie den Modus:

Kategorienseite → wenn auf Mit Standardlayout gesetzt, die Kategorie aber ein eigenes Layout verwendet, wird das Plugin nicht agieren. Wechseln Sie zu Alle oder fügen Sie das eigene Layout zu Ersetzbare Layouts hinzu.
Produktseite → wenn auf Ohne zugewiesenes Layout gesetzt, das Produkt aber ein spezifisches Layout hat, wird das Plugin nicht agieren. Wechseln Sie zu Alle oder zu einem der anderen Modi.
Landing-Seite → wenn auf Mit Standardlayout gesetzt, die Landing-Seite aber ein eigenes Layout verwendet, wird das Plugin nicht agieren. Wechseln Sie zu Alle oder erweitern Sie die Allow-Liste.

Siehe Ersetzungsmodi.

5. Sind die Ersetzungstypen für die Art der Basis leer?

Prüfen Sie in der Karte Ersetzungstypen die Zeile, die zum Typ des Basislayouts passt (nicht zu dem der Alternative). Wenn die Zeile leer ist, sucht das Plugin keine Alternativen für diese Art. Fügen Sie den Typ der Alternative zu dieser Zeile hinzu.

Beispiel: Basis ist eine Listing-Seite (Typ product_list), Alternative ist eine Landing-Seite (landingpage). Die Zeile Listing-Seite muss Landing-Seite auflisten.

Siehe Ersetzungstypen.

6. Liegen Sie über der 500-Layouts-Obergrenze?

Das Plugin wertet höchstens 500 regelgebundene Layouts pro Request aus (LIMIT_TOTAL in PageLoadedSubscriber). Wenn Sie mehr haben, werden Layouts jenseits der Obergrenze (in rule.priority ASC-Reihenfolge) übersprungen. Senken Sie den Prioritätswert auf den Regeln, die zuerst gewinnen sollen.

Siehe Performance.

Die Alternative erscheint auf zu vielen Seiten

Ursache: die Regel ist zu breit. Wahrscheinliche Verdächtige:

Eine Regel mit nur Immer gültig passt auf jeder Seite.
Eine Regel ohne Bedingungen (oder nur mit nicht unterstützten) wird als ✗ nicht unterstützt behandelt und übersprungen — aber eine teilweise unterstützte Regel kann breiter passen als gedacht, weil die nicht unterstützten Bedingungen stillschweigend weggelassen werden.

Lösung: eine Verkaufskanal-Bedingung hinzufügen. Eine Ist Startseite-Bedingung hinzufügen, wenn Sie wirklich nur die Startseite wollen. Die Status-Spalte im Layout-Zuweisungsmodal inspizieren.

Die falsche Alternative erscheint

Ursache: mehrere Layouts passen für diesen Request, und das falsche gewinnt.

Der Matcher wählt den ersten Treffer in rule.priority ASC-Reihenfolge. Niedrigere Priorität gewinnt zuerst.

Lösung: setzen Sie die Regel des gewünschten Layouts auf einen niedrigeren Prioritätswert als ihre Konkurrenten (Einstellungen → Regeln → Regel bearbeiten → Priorität).

Der Tab Regeln fehlt im Layout-Zuweisungsmodal

Das Admin-Bundle des Plugins ist nicht geladen.

Lösungen:

Bestätigen Sie, dass das Plugin unter Erweiterungen → Meine Erweiterungen aktiviert ist.
Admin-Cache leeren: bin/console cache:clear.
Admin hart neu laden (Strg+Umschalt+R), um das gecachte JS abzuwerfen.
Wenn Sie die Administration selbst bauen, bin/build-administration.sh erneut ausführen.
Prüfen Sie, ob Ihre Benutzerrolle Zugriff auf die neuen ACL-Schlüssel hat.

Die drei eigenen Regelbedingungen erscheinen nicht im Regel-Builder

Dieselbe Lösung wie oben — das Admin-Bundle ist nicht geladen. Bedingungen werden zur Admin-Laufzeit registriert.

Dieser Widget-XHR hat seine eigene Prüfung (onCategoryEntityLoaded), die durch den Ersetzungsmodus geschützt ist. Wenn Ihr Modus Kategorienseite Mit Standardlayout ist und die Kategorie ein eigenes Layout verwendet, wird der Widget-XHR ebenfalls nicht angerührt. Siehe 5. Sind die Ersetzungstypen leer und 6. Erlaubt der Ersetzungsmodus oben.

Nach Änderungen am Ersetzungsmodus hat sich in der Storefront nichts geändert

Storefront-Cache leeren: bin/console cache:clear (und ggf. Ihren HTTP-Cache / Varnish). Die Plugin-Einstellungen werden über Shopwares SystemConfigService gelesen, der pro Request gecached wird — eine veraltete Seite im HTTP-Cache überlebt eine Einstellungsänderung.

Verwandt

Funktionsweise — das Modell. Lesen Sie dies nochmal, wenn die Prüfungen 1–5 oben Sie ratlos zurücklassen.
Mehrere-Verkaufskanäle-Rezept — die kanonische Konfiguration mit dem häufigsten herausgehobenen Fallstrick.
Interna des Ersetzungsflusses — für Plugin-Entwickler, die das Verhalten debuggen.