Shopware 6 — Remote-Thumbnails

Ab Shopware 6.6.4 unterstützt Shopware die Remote-Thumbnail-Generierung. Anstatt beim Medien-Upload physische Thumbnail-Dateien auf der Festplatte zu erzeugen, generiert Shopware Thumbnail-URLs, die auf einen externen Dienst verweisen — und smoxy kann die eigentliche Skalierung on the fly über die Bildmanipulation-Funktion übernehmen.

Damit entfällt die Notwendigkeit vorab generierter Thumbnails vollständig. Kein bin/console media:generate-thumbnails mehr, kein verschwendeter Speicherplatz und sofortige Unterstützung für jede Thumbnail-Größe, die das Storefront anfordert.

WARNING

Haftungsausschluss: Dieser Leitfaden basiert auf der Shopware-6-Entwicklerdokumentation mit Stand Februar 2026. Shopware kann die Remote-Thumbnail-Funktion, deren Konfigurationsoptionen oder die verfügbaren Pattern-Variablen in zukünftigen Versionen ändern. Für aktuelle Informationen stets die offizielle Shopware-Dokumentation heranziehen. smoxy kann keine Kompatibilität mit zukünftigen Shopware-Änderungen garantieren.

So funktioniert es

Normalerweise erzeugt Shopware physische Thumbnail-Dateien (z. B. product_400x400.jpg, product_800x800.jpg) und speichert diese im /thumbnail/-Verzeichnis. Mit aktivierten Remote-Thumbnails überspringt Shopware diesen Schritt und schreibt stattdessen alle Thumbnail-URLs in ein konfigurierbares Muster um. Dieses Muster lässt sich so konfigurieren, dass smoxy die URLs über eine Rewrite Rule abfängt und on the fly verarbeitet.

Der Ablauf sieht folgendermaßen aus:

1. Ein Besucher ruft eine Produktseite im Storefront auf.
2. Shopware generiert eine Thumbnail-URL anhand des konfigurierten Musters (z. B. /thumbnail/800/media/ab/cd/product.jpg).
3. Der Browser fordert diese URL über smoxy an.
4. smoxy erkennt die URL anhand einer Rewrite Rule und skaliert das Originalbild on the fly.
5. Das verarbeitete Bild wird ausgeliefert und von smoxy gecached.

Voraussetzungen

• Shopware 6.6.4 oder neuer
• Die Bildmanipulation-Funktion von smoxy
• Eine konfigurierte Rewrite Rule in smoxy (siehe unten)

Schritt 1: Shopware konfigurieren

Die Datei config/packages/shopware.yaml in der Shopware-Installation bearbeiten und die Remote-Thumbnail-Konfiguration hinzufügen:

shopware:
  media:
    remote_thumbnails:
      enable: true
      pattern: '{mediaUrl}/thumbnail/{width}/{mediaPath}?ts={mediaUpdatedAt}'

Damit generiert Shopware Thumbnail-URLs im folgenden Format:

https://shop.example.com/thumbnail/800/media/ab/cd/ef/product.jpg?ts=1716882050

Verfügbare Pattern-Variablen

Shopware stellt folgende Variablen für das Muster bereit:

Variable	Beispiel	Beschreibung
{mediaUrl}	https://shop.example.com	Basis-URL des Medienspeichers
{mediaPath}	media/ab/cd/ef/product.jpg	Relativer Pfad zum Originalbild
{width}	800	Angeforderte Thumbnail-Breite
{height}	800	Angeforderte Thumbnail-Höhe
{mediaUpdatedAt}	1716882050	Unix-Zeitstempel der letzten Medienaktualisierung (dient als Cache-Buster)

INFO

Hinweis: Der Query-Parameter ?ts={mediaUpdatedAt} beeinflusst die smoxy Rewrite Rule nicht, stellt aber sicher, dass Browser und CDN-Caches aktuelle Versionen ausliefern, wenn ein Bild in Shopware aktualisiert wird.

Schritt 2: Rewrite Rule in smoxy erstellen

Im smoxy Dashboard eine Rewrite Rule erstellen, die die von Shopware generierten Thumbnail-URLs abfängt und durch die Bildmanipulation leitet.

Nur Breite (Empfohlen)

Das ist die einfachste und häufigste Konfiguration. Die Standard-Thumbnail-Größen von Shopware (400×400, 800×800, 1920×1920) sind quadratisch, aber das Storefront-srcset variiert typischerweise nur nach Breite, wobei die Höhe automatisch aus dem Seitenverhältnis berechnet wird.

Shopware-Pattern:

pattern: '{mediaUrl}/thumbnail/{width}/{mediaPath}?ts={mediaUpdatedAt}'

smoxy Rewrite Rule:

Feld	Wert
Regex	^/thumbnail/(\d+)/(.*)
Target Path	/_sx/img/_/w:$1/q:80/plain/$2

Eine Anfrage an /thumbnail/800/media/ab/cd/ef/product.jpg?ts=1716882050 wird:

1. Das Originalbild von /media/ab/cd/ef/product.jpg auf dem Origin-Server abrufen.
2. Es auf 800px Breite skalieren (Höhe wird automatisch aus dem Seitenverhältnis berechnet).
3. Die Ausgabequalität auf 80 % setzen.
4. Das verarbeitete Bild ausliefern.

Breite und Höhe

Wenn sowohl Breite als auch Höhe berücksichtigt werden sollen (z. B. für strikt dimensionierte Raster-Layouts), kann das Muster beide Dimensionen enthalten.

Shopware-Pattern:

pattern: '{mediaUrl}/thumbnail/{width}x{height}/{mediaPath}?ts={mediaUpdatedAt}'

smoxy Rewrite Rule:

Feld	Wert
Regex	^/thumbnail/(\d+)x(\d+)/(.*)
Target Path	/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3

INFO

Tipp: rs:fit durch rs:fill ersetzen, wenn das Bild die angegebenen Abmessungen vollständig ausfüllen soll (Überschuss wird abgeschnitten), anstatt sich darin einzupassen. Alle verfügbaren Optionen finden sich in der Skalierungstypen-Referenz.

Schritt 3: Bestehende Thumbnails aufräumen (Optional)

Sobald die Remote-Thumbnails funktionieren, werden die bestehenden physischen Thumbnail-Dateien auf dem Server nicht mehr benötigt. Diese lassen sich entfernen, um Speicherplatz freizugeben:

# Alle generierten Thumbnails entfernen
bin/console media:delete-thumbnails

WARNING

Wichtig: Vor dem Löschen bestehender Thumbnail-Dateien sicherstellen, dass die Remote-Thumbnails im Storefront korrekt funktionieren. In den Entwicklertools des Browsers (Tab „Netzwerk") prüfen, ob Thumbnail-Anfragen über smoxy ausgeliefert werden.

Erweiterte Beispiele

Höhere Qualität für große Bilder

Mit zwei separaten Rewrite Rules lassen sich unterschiedliche Qualitätsstufen je nach Thumbnail-Größe anwenden:

Regel 1 — Kleine Thumbnails (niedrige Qualität, schnelles Laden):

Feld	Wert
Regex	^/thumbnail/small/(\d+)/(.*)
Target Path	/_sx/img/_/w:$1/q:60/plain/$2

Regel 2 — Große Thumbnails (hohe Qualität):

Feld	Wert
Regex	^/thumbnail/large/(\d+)/(.*)
Target Path	/_sx/img/_/w:$1/q:90/sh:0.5/plain/$2

Dies erfordert zwei separate Shopware-Patterns (oder ein Plugin, das das Pattern je nach Thumbnail-Kontext anpasst).

Smart Cropping für Produkt-Thumbnails

Smart Gravity verwenden, damit beim Zuschnitt automatisch der visuell interessanteste Bereich des Bildes fokussiert wird:

Shopware-Pattern:

pattern: '{mediaUrl}/thumbnail/{width}x{height}/{mediaPath}?ts={mediaUpdatedAt}'

smoxy Rewrite Rule:

Feld	Wert
Regex	^/thumbnail/(\d+)x(\d+)/(.*)
Target Path	/_sx/img/_/rs:fill:$1:$2/g:sm/q:80/plain/$3

Die Option g:sm (Smart Gravity) stellt sicher, dass Produktbilder um den visuell relevantesten Bereich zugeschnitten werden, anstatt immer von der Mitte aus.

Fehlerbehebung

Bilder werden nicht geladen

• Prüfen, ob das Shopware-Pattern URLs erzeugt, die zur smoxy Rewrite Rule passen. Eine Produktseite öffnen, ein Bild im Browser inspizieren und die generierte src- oder srcset-URL kontrollieren.
• Sicherstellen, dass die Rewrite Rule aktiv ist und in der smoxy Regel-Liste korrekt positioniert ist.

Falsche Bildabmessungen

• Prüfen, ob Shopware nur {width} oder sowohl {width} als auch {height} übergibt — und sicherstellen, dass der Regex der Rewrite Rule entsprechend matcht.
• Wenn Bilder verzerrt erscheinen, von rs:force auf rs:fit oder rs:fill wechseln.

Veraltete Bilder nach Aktualisierung

• Der {mediaUpdatedAt}-Zeitstempel im Query-String sollte die Cache-Invalidierung automatisch übernehmen. Falls weiterhin veraltete Bilder ausgeliefert werden, kann ein Cache-Purge in smoxy notwendig sein.

Weiterführende Informationen

• Bildmanipulation — Übersicht
• Skalierung & Zuschnitt — Referenz
• Effekte & Anpassungen — Referenz
• Ausgabe, Metadaten & Auslieferung — Referenz