URL-Rewrites in Magento 2 verwalten: Redirects, SEO-Slugs, Massenpflege

1. Einordnung: was die url_rewrite-Tabelle wirklich speichert

Die Tabelle url_rewrite ist das Rückgrat jeder SEO-freundlichen URL in Magento 2. Sie bildet die Brücke zwischen dem, was ein Besucher in der Adresszeile sieht, etwa damen/kleider/sommerkleid-blau.html, und dem internen Controller-Pfad, den Magento tatsächlich ausführt, etwa catalog/product/view/id/482. Ohne diese Tabelle würde jede Produkt- und Kategorieseite unter kryptischen, technischen Pfaden erreichbar sein, was sowohl für Suchmaschinen als auch für Kunden unbrauchbar wäre. URL-Rewrites sind damit keine Nebensache, sondern ein zentraler Bestandteil der Storefront-Architektur.

Der entscheidende Punkt, der in vielen Projekten unterschätzt wird: Die Tabelle ist kein statischer Export, der einmal generiert und dann in Ruhe gelassen wird. Sie wird kontinuierlich durch Indexer, Admin-Aktionen und Custom-Code beschrieben. Jede Umbenennung einer Kategorie, jede Verschiebung eines Produkts in eine andere Kategorie, jede Änderung am URL-Key-Attribut erzeugt neue Einträge und kann alte Einträge invalidieren. Wer URL-Rewrites als einmaliges Setup-Thema behandelt, übersieht, dass die Pflege ein fortlaufender Prozess ist, der über den gesamten Lebenszyklus eines Shops aktiv gesteuert werden muss, ähnlich wie DNS-Einträge in einer wachsenden Infrastruktur.

Diese fortlaufende Pflege betrifft nicht nur Katalogentitäten. CMS-Seiten, Custom-Redirects aus Marketing-Kampagnen und manuell angelegte Weiterleitungen landen in derselben Tabelle und folgen denselben Regeln. Ein sauberes Verständnis der Struktur ist deshalb die Voraussetzung für alles, was in den folgenden Abschnitten programmatisch, per Massenimport oder über Monitoring-Skripte gelöst wird.

2. Tabellenstruktur: request_path, target_path, redirect_type, entity_type, store_id

Die wichtigsten Spalten der Tabelle sind schnell benannt, ihre Zusammenspiel ist jedoch der eigentliche Kern. request_path ist die eingehende URL ohne führenden Slash, wie sie im Browser aufgerufen wird. target_path ist der interne Pfad, auf den Magento intern weiterleitet oder direkt rendert. redirect_type unterscheidet zwischen einem direkten Rewrite ohne sichtbare Weiterleitung (Wert 0) und einer echten HTTP-Weiterleitung mit 301 oder 302. entity_type gibt an, zu welcher Art von Objekt der Eintrag gehört, typischerweise product, category, cms-page oder custom für manuell angelegte URL-Rewrites. store_id schließlich macht jeden Eintrag store-spezifisch, da derselbe Produktpfad in unterschiedlichen Store Views unterschiedliche URL-Keys tragen kann.

Intern unterscheidet Magento Katalog- von CMS-Rewrites nicht über eine separate Tabelle, sondern ausschließlich über das Feld entity_type in Kombination mit entity_id. Für Kategorie-Rewrites kommt zusätzlich die Spalte metadata ins Spiel, in der ein serialisiertes Array mit dem category_id-Pfad hinterlegt wird, das für die Auflösung verschachtelter Kategoriebäume benötigt wird. Die Spalte is_autogenerated markiert, ob ein Eintrag vom Indexer erzeugt wurde oder manuell angelegt ist, was für Aufräum- und Monitoring-Skripte eine wichtige Unterscheidung ist, wie später im Abschnitt zum Monitoring gezeigt wird.

-- Typical url_rewrite query: catalog and CMS entries mixed together
SELECT
    url_rewrite_id,
    entity_type,
    entity_id,
    request_path,
    target_path,
    redirect_type,
    store_id,
    is_autogenerated,
    description
FROM url_rewrite
WHERE store_id = 1
  AND entity_type IN ('product', 'category', 'cms-page', 'custom')
ORDER BY request_path
LIMIT 20;

-- redirect_type: 0 = direct rewrite without redirect, 301 = permanent, 302 = temporary
-- is_autogenerated: 1 = generated by a Magento indexer, 0 = manually created entry

3. Programmatische Rewrites über Service Contracts

Direkte INSERT- oder UPDATE-Statements gegen url_rewrite sind ein häufiger Anti-Pattern, weil sie Magentos Caching, Event-Dispatching und Validierung umgehen. Der korrekte Weg für programmatische URL-Rewrites führt über UrlPersistInterface. Dieses Service Contract stellt die Methode replace() bereit, die ein Array von UrlRewrite-Objekten entgegennimmt, Duplikate erkennt und Konflikte über eine UrlAlreadyExistsException meldet, statt sie stillschweigend zu überschreiben. Die Objekte selbst werden nicht per new instanziiert, sondern über UrlRewriteFactory erzeugt, was Magentos Objekterzeugungskonventionen entspricht und Tests mit Mocks erheblich vereinfacht.

In PHP 8.4 lässt sich ein solcher Service sauber mit Constructor Property Promotion formulieren. Statt Abhängigkeiten im Konstruktorkörper einzeln zuzuweisen, werden UrlPersistInterface und UrlRewriteFactory direkt als private readonly Properties deklariert. Das reduziert Boilerplate, macht die Klasse aber gleichzeitig strikt typisiert und unveränderlich nach der Konstruktion, was für einen Dienst, der ausschließlich Redirect-Definitionen entgegennimmt und persistiert, genau die richtige Semantik ist.

Wichtig ist, die Verantwortung klar zu trennen: Die Service-Klasse kennt nur die Domäne, aus der ein Redirect stammt, etwa eine Marketing-Kampagne oder eine URL-Migration, und delegiert die eigentliche Persistenz vollständig an das Framework. So bleiben URL-Rewrites, die programmatisch erzeugt werden, mit denen aus dem Admin-Grid und den Indexern konsistent.

<?php

declare(strict_types=1);

namespace Mironsoft\SeoSuite\Service;

use Magento\UrlRewrite\Model\UrlRewriteFactory;
use Magento\UrlRewrite\Model\OptionProvider;
use Magento\UrlRewrite\Service\V1\UrlPersistInterface;
use Magento\Framework\Exception\UrlAlreadyExistsException;

/**
 * Creates a single custom redirect via the UrlPersistInterface service contract.
 */
class CustomRedirectCreator
{
    /**
     * @param UrlPersistInterface $urlPersist Persists url_rewrite entries through the service contract.
     * @param UrlRewriteFactory $urlRewriteFactory Builds UrlRewrite value objects.
     */
    public function __construct(
        private readonly UrlPersistInterface $urlPersist,
        private readonly UrlRewriteFactory $urlRewriteFactory,
    ) {
    }

    /**
     * Creates or replaces a permanent redirect between two request paths.
     *
     * @param string $requestPath Old, SEO relevant request path without leading slash.
     * @param string $targetPath New target path the request should redirect to.
     * @param int $storeId Store view the redirect applies to.
     * @return void
     * @throws UrlAlreadyExistsException
     */
    public function createPermanentRedirect(string $requestPath, string $targetPath, int $storeId): void
    {
        $urlRewrite = $this->urlRewriteFactory->create()
            ->setEntityType('custom')
            ->setEntityId(0)
            ->setRequestPath($requestPath)
            ->setTargetPath($targetPath)
            ->setRedirectType(OptionProvider::PERMANENT)
            ->setStoreId($storeId)
            ->setDescription('Programmatic redirect via Service Contract')
            ->setIsAutogenerated(0);

        $this->urlPersist->replace([$urlRewrite]);
    }
}

4. Massenpflege: CSV-Import-Modul für Redirects

Sobald mehr als eine Handvoll Redirects gepflegt werden müssen, etwa nach einer Domain-Migration oder einem Kategorie-Relaunch, wird die Admin-Oberfläche unter Marketing zu einem Flaschenhals. Der robuste Ansatz ist ein eigenes kleines Modul mit einem Symfony-Console-Command, das über di.xml unter Magento\Framework\Console\CommandListInterface registriert wird und eine CSV-Datei zeilenweise in UrlRewrite-Objekte übersetzt. Statt jeden Redirect einzeln zu persistieren, sammelt der Command die Objekte in Batches und übergibt sie gebündelt an UrlPersistInterface::replace(), was die Anzahl der Datenbank-Roundtrips drastisch reduziert.

Bei der Batch-Größe gilt ein Kompromiss: Zu große Batches erhöhen den Speicherbedarf und das Risiko, dass ein einzelner fehlerhafter Datensatz den gesamten Batch scheitern lässt, zu kleine Batches verlieren den Performance-Vorteil der Bündelung. In der Praxis haben sich Batch-Größen zwischen 100 und 500 Zeilen bewährt, abhängig von der Serverhardware und davon, ob der Import während des laufenden Betriebs oder in einem Wartungsfenster ausgeführt wird. Für URL-Rewrites, die aus externen Systemen wie einem PIM oder einem alten Shop-Export stammen, lohnt sich zusätzlich eine Vorab-Validierung der Spalten, bevor überhaupt ein Factory-Aufruf erfolgt.

Die di.xml-Bindung selbst ist unspektakulär, aber entscheidend: Ohne den Eintrag im CommandListInterface-Array taucht der Befehl in bin/magento list nicht auf. Diese Bindung gehört zur Grundausstattung jedes Moduls, das URL-Rewrites per CLI verwaltet, und sollte ebenso wie acl.xml und system.xml von Anfang an mitgeliefert werden.

<?php

declare(strict_types=1);

namespace Mironsoft\SeoSuite\Console\Command;

use Magento\UrlRewrite\Model\OptionProvider;
use Magento\UrlRewrite\Model\UrlRewriteFactory;
use Magento\UrlRewrite\Service\V1\UrlPersistInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Imports a batch of URL-Rewrites redirects from a CSV file in a single persistence call per batch.
 */
class ImportRedirectsCommand extends Command
{
    private const BATCH_SIZE = 200;

    /**
     * @param UrlPersistInterface $urlPersist Persists batches of url_rewrite entries.
     * @param UrlRewriteFactory $urlRewriteFactory Builds UrlRewrite value objects per CSV row.
     * @param string|null $name Optional Symfony command name.
     */
    public function __construct(
        private readonly UrlPersistInterface $urlPersist,
        private readonly UrlRewriteFactory $urlRewriteFactory,
        ?string $name = null,
    ) {
        parent::__construct($name);
    }

    /**
     * Configures the command name, description and CSV path argument.
     *
     * @return void
     */
    protected function configure(): void
    {
        $this->setName('mironsoft:redirects:import')
            ->setDescription('Bulk imports URL-Rewrites redirects from a CSV file')
            ->addArgument('file', InputArgument::REQUIRED, 'Path to the redirects CSV file');
    }

    /**
     * Reads the CSV file and persists redirects in fixed size batches.
     *
     * @param InputInterface $input Console input, holds the file argument.
     * @param OutputInterface $output Console output for progress messages.
     * @return int Symfony exit code.
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $handle = fopen((string) $input->getArgument('file'), 'r');
        $batch = [];
        $imported = 0;

        while (($row = fgetcsv($handle)) !== false) {
            [$requestPath, $targetPath, $storeId, $type] = $row;

            $batch[] = $this->urlRewriteFactory->create()
                ->setEntityType('custom')
                ->setEntityId(0)
                ->setRequestPath($requestPath)
                ->setTargetPath($targetPath)
                ->setRedirectType($type === '302' ? OptionProvider::TEMPORARY : OptionProvider::PERMANENT)
                ->setStoreId((int) $storeId)
                ->setIsAutogenerated(0);

            if (count($batch) >= self::BATCH_SIZE) {
                $this->urlPersist->replace($batch);
                $imported += count($batch);
                $batch = [];
            }
        }

        if ($batch !== []) {
            $this->urlPersist->replace($batch);
            $imported += count($batch);
        }

        fclose($handle);
        $output->writeln(sprintf('<info>%d URL-Rewrites redirects imported.</info>', $imported));

        return Command::SUCCESS;
    }
}

5. Redirect-Typen richtig einsetzen

Der Unterschied zwischen einem 301- und einem 302-Redirect ist bei URL-Rewrites keine Formalität, sondern hat direkten Einfluss auf SEO-Rankings. Ein 301, in Magento über die Konstante OptionProvider::PERMANENT abgebildet, signalisiert Suchmaschinen, dass die alte URL dauerhaft durch die neue ersetzt wurde, und überträgt den größten Teil des Linkjuice auf das neue Ziel. Ein 302, über OptionProvider::TEMPORARY abgebildet, signalisiert eine vorübergehende Umleitung, die Suchmaschine behält die alte URL im Index und crawlt sie weiterhin regelmäßig. Wer eine dauerhafte Domain- oder Kategorie-Migration fälschlich mit 302 abbildet, verschenkt SEO-Wert, weil das Ranking-Signal nicht vollständig übertragen wird.

Ein zweites, oft übersehenes Problem sind Redirect-Ketten: URL A leitet auf URL B weiter, die wiederum auf URL C weiterleitet. Jeder zusätzliche Hop kostet Ladezeit, verwirrt Crawler und erhöht das Risiko, dass eine Suchmaschine die Kette nach wenigen Hops abbricht und die Zielseite gar nicht mehr indexiert. Ketten entstehen typischerweise, wenn ein alter Redirect nach einer weiteren Migration nicht aktualisiert, sondern um einen neuen Redirect ergänzt wird. Die einzige nachhaltige Lösung ist, bei jeder neuen Migration bestehende URL-Rewrites, die auf denselben Pfad zeigen, direkt auf das finale Ziel umzubiegen, statt eine weitere Weiterleitung anzuhängen.

<?php

declare(strict_types=1);

namespace Mironsoft\SeoSuite\Service;

use Magento\UrlRewrite\Model\OptionProvider;
use Magento\UrlRewrite\Model\ResourceModel\UrlRewriteCollectionFactory;

/**
 * Detects redirect chains by following target_path recursively.
 */
class RedirectChainDetector
{
    private const MAX_HOPS = 10;

    /**
     * @param UrlRewriteCollectionFactory $collectionFactory Loads url_rewrite rows by request_path.
     */
    public function __construct(
        private readonly UrlRewriteCollectionFactory $collectionFactory,
    ) {
    }

    /**
     * Follows a request path through successive redirects and returns the hop count.
     *
     * @param string $requestPath Starting request path to trace.
     * @param int $storeId Store view to search within.
     * @return int Number of hops until a non redirect target is reached.
     */
    public function countHops(string $requestPath, int $storeId): int
    {
        $currentPath = $requestPath;
        $hops = 0;

        while ($hops < self::MAX_HOPS) {
            $collection = $this->collectionFactory->create();
            $collection->addFieldToFilter('request_path', ['eq' => $currentPath]);
            $collection->addFieldToFilter('store_id', ['eq' => $storeId]);

            /** @var \Magento\UrlRewrite\Model\UrlRewrite|null $rewrite */
            $rewrite = $collection->getFirstItem();
            $redirectType = (int) $rewrite->getRedirectType();

            if ($rewrite->getEntityId() === null
                || !in_array($redirectType, [OptionProvider::PERMANENT, OptionProvider::TEMPORARY], true)
            ) {
                break;
            }

            $currentPath = (string) $rewrite->getTargetPath();
            $hops++;
        }

        return $hops;
    }
}

// OptionProvider::PERMANENT = 301, OptionProvider::TEMPORARY = 302, 0 = direct rewrite

6. Konflikte bei Kategorie- und Attribut-Änderungen

Wird eine Kategorie umbenannt oder ein Produkt in eine andere Kategorie verschoben, generiert Magento nicht sofort neue URL-Rewrites, sondern markiert die betroffenen Entitäten als invalidiert für den catalog_url_rewrite-Indexer. Erst der nächste Reindex, sei es im Modus Full oder On Save, schreibt die neuen Einträge und setzt, falls in den Einstellungen aktiviert, automatisch einen Redirect vom alten auf den neuen Pfad. Wer nach Bulk-Änderungen an Kategorien nicht reindexiert, arbeitet mit veralteten URL-Rewrites, was zu Diskrepanzen zwischen dem, was im Frontend sichtbar ist, und dem, was tatsächlich in der Datenbank steht, führt.

Eine zentrale Konfigurationsoption in diesem Zusammenhang ist die Strategie unter Catalog > Search Engine Optimization, die steuert, ob bei Kategorie- und Produkt-Umbenennungen automatisch ein Redirect erzeugt wird oder ob der alte Pfad einfach mit no_selection verworfen wird. Bei no_selection verschwindet der alte Eintrag ersatzlos, was in Produktivumgebungen mit bestehendem organischen Traffic praktisch immer zu vermeidbaren 404-Fehlern führt. Die empfohlene Einstellung erzeugt stattdessen automatisch einen 301-Redirect vom alten auf den neuen Pfad, sodass externe Backlinks und Suchmaschinen-Rankings erhalten bleiben.

#!/usr/bin/env bash
# Reindex catalog_url_rewrite after bulk category or attribute changes
bin/magento indexer:reindex catalog_url_rewrite_product
bin/magento indexer:reindex catalog_url_rewrite_category

# Inspect current indexer mode and status for all url_rewrite related indexers
bin/magento indexer:status | grep -i url_rewrite
bin/magento indexer:show-mode catalog_url_rewrite_product catalog_url_rewrite_category

# Switch to "Update by Schedule" to avoid long running saves in the admin
bin/magento indexer:set-mode schedule catalog_url_rewrite_product catalog_url_rewrite_category

7. SEO-Slug-Strategie und Duplicate Content

Die Qualität von URL-Rewrites steht und fällt mit der URL-Key-Konvention, die einem Shop zugrunde liegt. Konsistent klein geschriebene, mit Bindestrichen statt Unterstrichen getrennte Slugs, ohne Stoppwörter und ohne redundante Kategorienamen im Produktpfad, sind die Grundlage für lesbare und crawlbare URLs. Ein häufiger Fehler ist, den vollständigen Kategoriepfad in jeden Produkt-URL-Key einzubetten, was bei Kategorie-Umbenennungen automatisch eine Kaskade neuer URL-Rewrites auslöst, obwohl sich am Produkt selbst nichts geändert hat.

Der Suffix, typischerweise .html, wird zentral über die Einstellung für Produkt- und Kategorie-URL-Suffixe gesteuert und sollte projektweit konsistent bleiben. Ein Wechsel des Suffix im laufenden Betrieb erzeugt für jede betroffene Entität eine neue Zeile in url_rewrite und erfordert zwingend automatische Redirects, da sonst jede zuvor indexierte URL ins Leere läuft. Duplicate Content entsteht in der Praxis meist dann, wenn ein Produkt über mehrere Kategoriepfade gleichzeitig erreichbar ist und Magento für jeden Pfad einen eigenen, technisch gültigen Rewrite anlegt.

Genau hier spielt das Canonical-Tag seine Rolle im Zusammenspiel mit URL-Rewrites: Es signalisiert Suchmaschinen, welche der mehreren erreichbaren URLs als die maßgebliche Version gilt, auch wenn die url_rewrite-Tabelle mehrere gültige Pfade zum selben Produkt enthält. Canonical-Tags ersetzen dabei keine sauberen Rewrites, sondern ergänzen sie, insbesondere wenn aus geschäftlichen Gründen mehrere Kategoriezuordnungen bestehen bleiben müssen und eine Konsolidierung der URLs nicht praktikabel ist.

8. Monitoring: 404-Reports und verwaiste Rewrites

Ohne aktives Monitoring bleiben Probleme mit URL-Rewrites lange unentdeckt, weil weder Kunden noch das Team von selbst melden, dass eine URL ins Leere läuft. Der 404-Report, den Magento über das eingebaute Logging der NoRouteHandler-Klasse oder über externe Tools wie die Google Search Console liefert, ist die erste und wichtigste Quelle. Wiederkehrende 404-Pfade mit nennenswertem Traffic sind ein starkes Indiz für fehlende oder fehlerhafte Redirects und sollten priorisiert in einen manuellen oder automatisierten Redirect überführt werden.

Verwaiste Rewrites sind das Gegenstück zum 404-Problem: Einträge in url_rewrite, deren referenzierte entity_id längst gelöscht wurde, etwa weil ein Produkt deaktiviert und gelöscht, aber der zugehörige Custom-Redirect nie entfernt wurde. Solche Leichen häufen sich über Jahre an, blähen die Tabelle unnötig auf und verlangsamen im Extremfall die URL-Auflösung, weil der zugrunde liegende Index größer wird als nötig. Ein periodisches Skript, das entity_id-Referenzen gegen die jeweiligen Katalog- und CMS-Tabellen abgleicht, deckt solche verwaisten URL-Rewrites zuverlässig auf.

Redirect-Ketten lassen sich, wie im Abschnitt zu den Redirect-Typen gezeigt, programmatisch per Skript erkennen, indem man jeden request_path rekursiv über target_path verfolgt, bis ein finales Ziel ohne weiteren Redirect erreicht ist. Ein solches Skript sollte fester Bestandteil jeder CI-Pipeline oder zumindest eines monatlichen Wartungslaufs sein, da Ketten sich mit jeder weiteren Migration von selbst vermehren, wenn niemand aktiv gegensteuert.

9. Rewrite-Verwaltungsansätze im Vergleich

Die folgende Übersicht stellt gängige Ansätze zur Pflege von URL-Rewrites ihren jeweiligen Risiken und den empfohlenen Alternativen gegenüber. Die Wahl des Ansatzes hat direkten Einfluss auf Datenkonsistenz, SEO-Stabilität und die Wartbarkeit des Shops über mehrere Jahre.

Die Tabelle zeigt ein wiederkehrendes Muster: Jede kurzfristig bequeme Abkürzung bei URL-Rewrites, sei es SQL statt Service Contract oder 302 statt 301, erzeugt langfristige Kosten, die deutlich höher liegen als der anfängliche Zeitgewinn. Wer die empfohlenen Patterns konsequent über alle Module und Migrationen hinweg anwendet, reduziert den Wartungsaufwand messbar.

10. Zusammenfassung

Die Pflege von URL-Rewrites in Magento 2 ist kein Einmalprojekt, sondern ein kontinuierlicher Prozess über den gesamten Shop-Lebenszyklus. Die url_rewrite-Tabelle mit ihren Spalten request_path, target_path, redirect_type, entity_type und store_id bildet die technische Grundlage, während UrlPersistInterface und UrlRewriteFactory den sicheren, programmatischen Zugriff darauf ermöglichen, ohne Magentos interne Validierung und Event-Mechanismen zu umgehen. Für Massenänderungen ist ein eigenes CSV-Import-Modul mit sauberer di.xml-Bindung der einzige Weg, der sowohl performant als auch nachvollziehbar bleibt.

Ebenso wichtig wie die technische Umsetzung ist die konsequente Anwendung der richtigen Redirect-Typen und ein aktives Monitoring. 301 statt 302 bei dauerhaften Migrationen, automatische Redirect-Generierung bei Kategorie-Umbenennungen und ein periodisches Skript zur Erkennung von Redirect-Ketten und verwaisten Einträgen verhindern, dass sich über Jahre technische Schulden in der url_rewrite-Tabelle ansammeln. Wer diese Bausteine kombiniert, behält auch bei großen Katalogen die volle Kontrolle über seine URL-Rewrites.

11. FAQ: URL-Rewrites in Magento 2 verwalten