Magento 2 Domain Mapping pro Store: Base URLs, SSL und Server-Konfiguration

1. Warum Domain Mapping mehr als eine Backend-Einstellung ist

Für viele international tätige Shops ist eine eigene Domain pro Markt, etwa shop.de und shop.fr, geschäftlich naheliegender als ein gemeinsamer Store-Code im URL-Pfad. Das Magento 2 Domain Mapping pro Store lässt sich zwar im Backend mit wenigen Konfigurationswerten anlegen, doch die tatsächliche Funktionsfähigkeit hängt von einer ganzen Kette an Infrastrukturentscheidungen ab, die weit über die Base-URL-Einstellung hinausgehen.

Wer Domain Mapping pro Store nur im Backend konfiguriert, ohne die zugehörige Webserver-Konfiguration, SSL-Verwaltung und Cache-Strategie mitzudenken, produziert ein System, das in Testumgebungen funktioniert, aber im produktiven Betrieb an unerwarteten Stellen bricht, etwa wenn ein Zertifikat für eine neu hinzugefügte Domain fehlt oder der Full Page Cache Inhalte zwischen Domains vertauscht. Die folgenden Abschnitte behandeln jede Schicht dieser Infrastruktur einzeln.

2. Base URL pro Store view korrekt konfigurieren

Die Konfigurationswerte web/unsecure/base_url und web/secure/base_url definieren, unter welcher Domain ein Store view erreichbar ist, und müssen auf Store-View-Ebene individuell gesetzt werden, wenn Domain Mapping pro Store umgesetzt werden soll. Ein häufiger Anfängerfehler ist, diese Werte nur auf Website-Ebene zu setzen, was bei mehreren Store Views mit unterschiedlichen Domains innerhalb derselben Website nicht funktioniert, da alle Store Views dann dieselbe Basis-URL erben würden.

Zusätzlich zur Base URL muss web/secure/use_in_frontend und web/secure/use_in_adminhtml korrekt gesetzt sein, damit Magento konsistent HTTPS-URLs generiert. Ein subtiler Fehler entsteht, wenn eine der beiden Domains kein gültiges SSL-Zertifikat besitzt, aber die Secure-Base-URL dennoch auf https verweist: Der Kunde sieht dann Zertifikatswarnungen des Browsers, obwohl die Magento-Konfiguration selbst korrekt aussieht.

#!/usr/bin/env bash
set -euo pipefail

# Configure base URLs per store view for domain-based multi-store setup
bin/magento config:set --scope=stores --scope-code=de \
  web/unsecure/base_url "http://shop.de/"
bin/magento config:set --scope=stores --scope-code=de \
  web/secure/base_url "https://shop.de/"

bin/magento config:set --scope=stores --scope-code=fr \
  web/unsecure/base_url "http://shop.fr/"
bin/magento config:set --scope=stores --scope-code=fr \
  web/secure/base_url "https://shop.fr/"

bin/magento config:set --scope=stores --scope-code=at \
  web/unsecure/base_url "http://shop.at/"
bin/magento config:set --scope=stores --scope-code=at \
  web/secure/base_url "https://shop.at/"

# Force HTTPS everywhere in frontend and admin
bin/magento config:set web/secure/use_in_frontend 1
bin/magento config:set web/secure/use_in_adminhtml 1

# Optional: a shared cookie domain only makes sense for subdomains of one TLD
# bin/magento config:set --scope=stores --scope-code=de web/cookie/cookie_domain ".shop.com"

bin/magento cache:flush config full_page

# Verify store resolution locally before the DNS cutover, using the Host header
curl -sI -H "Host: shop.fr" http://127.0.0.1/ | grep -i location
curl -sI -H "Host: shop.de" http://127.0.0.1/ | grep -i location

# Add temporary local entries while DNS still points elsewhere
echo "127.0.0.1 shop.de shop.fr shop.at" | sudo tee -a /etc/hosts

Dieser lokale Testlauf über den Host-Header, noch bevor die eigentliche DNS-Umstellung erfolgt, deckt einen großen Teil der Fehler bei Domain Mapping pro Store bereits im Vorfeld auf. Stimmt die berechnete Redirect-Ziel-URL für eine Test-Domain nicht mit der erwarteten Store view überein, liegt der Fehler fast immer an einer falsch gesetzten oder fehlenden Base-URL-Konfiguration und lässt sich so korrigieren, ohne dass ein Kunde je eine fehlerhafte Weiterleitung zu Gesicht bekommt.

3. Vhost-Konfiguration für mehrere Domains

Auf Webserver-Ebene benötigt jede Domain, die für Domain Mapping pro Store genutzt wird, einen eigenen virtuellen Host, entweder als separater Nginx-Server-Block oder als Apache-VirtualHost. Alle Domains zeigen dabei auf dasselbe Document Root, denn die Store-Zuordnung erfolgt nicht auf Dateisystemebene, sondern innerhalb von Magento anhand der angeforderten Domain. Der Webserver muss lediglich den korrekten Host-Header an PHP-FPM durchreichen, damit Magentos Store-Resolver ihn auswerten kann.

Ein wichtiges Detail bei Nginx-Konfigurationen ist, dass alle Domains denselben server_name-Eintrag oder mehrere durch Leerzeichen getrennte Einträge im selben Server-Block verwenden können, solange keine domain-spezifischen Pfad-Regeln benötigt werden. Werden hingegen unterschiedliche Rewrite-Regeln pro Domain gebraucht, etwa für Redirects von einer alten Domain, empfiehlt sich ein separater Server-Block pro Domain mit einem gemeinsamen Include für die eigentliche Magento-Konfiguration.

# /etc/nginx/sites-available/magento-multi-domain.conf
# Single server block handling multiple store domains, same document root

server {
    listen 443 ssl http2;
    server_name shop.de shop.fr shop.at;

    root /var/www/magento/pub;

    ssl_certificate     /etc/ssl/multi-domain/fullchain.pem;
    ssl_certificate_key /etc/ssl/multi-domain/privkey.pem;

    include /etc/nginx/snippets/magento-fastcgi.conf;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
}

server {
    listen 80;
    server_name shop.de shop.fr shop.at;
    return 301 https://$host$request_uri;
}

# /etc/nginx/snippets/magento-fastcgi.conf
# Shared FastCGI settings included by every store domain's server block
location ~ ^/(index|get|static|errors/report|errors/404|errors/503|health_check)\.php$ {
    fastcgi_pass unix:/run/php/php8.4-fpm-magento.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param HTTP_HOST $host;
    include fastcgi_params;
}

# Alternative: dedicated server block per domain when redirects from a
# legacy domain (old.shop.de -> shop.de) require domain-specific rewrite rules
server {
    listen 443 ssl http2;
    server_name old.shop.de;
    ssl_certificate     /etc/ssl/old-shop-de/fullchain.pem;
    ssl_certificate_key /etc/ssl/old-shop-de/privkey.pem;
    return 301 https://shop.de$request_uri;
}

4. Store-Resolution: Wie Magento die Domain einem Store view zuordnet

Sobald ein Request bei Magento ankommt, übernimmt Magento\Store\App\Request\PathInfoProcessor in Zusammenspiel mit dem Store-Resolver die Zuordnung des Host-Headers zum passenden Store view. Magento vergleicht den Host-Header gegen die konfigurierten Base URLs aller Store Views und wählt den ersten übereinstimmenden Store view aus. Für Domain Mapping pro Store ist wichtig, dass diese Base URLs exakt dem tatsächlich verwendeten Host entsprechen müssen, inklusive oder exklusive www-Präfix, da schon ein kleiner Unterschied zur Nichterkennung des Stores führt.

Für komplexere Anforderungen, etwa wenn eine einzelne Domain je nach URL-Pfad-Segment auf unterschiedliche Store Views verweisen soll, reicht die native Base-URL-Zuordnung nicht aus. Hier ist ein eigener Plugin auf dem Store-Resolver oder ein Custom-Modul nötig, das den Host-Header zusätzlich mit dem Pfad kombiniert auswertet, etwa um shop.com/de/ und shop.com/fr/ auf unterschiedliche Store Views zu leiten, während gleichzeitig shop.us als eigene Domain für einen weiteren Store view dient.

Für die Fehlersuche im laufenden Betrieb hilft ein einfacher Test mit curl und einem manuell gesetzten Host-Header direkt gegen die Server-IP, ohne den Umweg über DNS. Weicht das Ergebnis von der Erwartung ab, lässt sich so schnell unterscheiden, ob der Fehler im Webserver, im Store-Resolver oder in der DNS-Auflösung selbst liegt, was die Diagnosezeit bei Domain Mapping pro Store-Problemen erheblich verkürzt.

<?php

declare(strict_types=1);

namespace Mironsoft\DomainMapping\Plugin;

use Magento\Store\Model\StoreResolver;
use Magento\Framework\App\RequestInterface;

/**
 * Combines host header and first path segment to resolve a store view,
 * enabling shop.com/de/ and shop.com/fr/ to resolve differently while
 * shop.us stays a fully independent domain for another store view.
 */
final class HostAndPathStoreResolver
{
    /**
     * @param RequestInterface $request Current HTTP request
     */
    public function __construct(
        private readonly RequestInterface $request
    ) {
    }

    /**
     * @param StoreResolver $subject Native store resolver
     * @param string $result Native resolved store code
     * @return string Adjusted store code based on host + path segment
     */
    public function afterGetRequestValue(StoreResolver $subject, string $result): string
    {
        $host = (string) $this->request->getServer('HTTP_HOST');

        if ($host !== 'shop.com') {
            return $result;
        }

        $firstSegment = trim((string) $this->request->getPathInfo(), '/');
        $langCode = explode('/', $firstSegment)[0] ?? '';

        return match ($langCode) {
            'fr' => 'fr_store',
            'de' => 'de_store',
            default => $result,
        };
    }
}

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Store\Model\StoreResolver">
        <plugin name="mironsoft_hostAndPathStoreResolver"
                type="Mironsoft\DomainMapping\Plugin\HostAndPathStoreResolver"
                sortOrder="10" />
    </type>
</config>

5. SSL-Zertifikate pro Domain verwalten

Für Domain Mapping pro Store mit mehreren echten Domains, im Gegensatz zu Subdomains derselben Hauptdomain, wird für jede Domain ein gültiges SSL-Zertifikat benötigt. Ein Multi-Domain-Zertifikat, auch SAN-Zertifikat genannt, das alle Store-Domains in einem einzigen Zertifikat mit mehreren Subject Alternative Names abdeckt, ist der wartungsärmste Ansatz, insbesondere in Kombination mit automatischer Erneuerung über Let's Encrypt und dessen DNS- oder HTTP-01-Challenge-Mechanismen.

Ein häufiger Fallstrick ist, dass ein neu hinzugefügter Store view mit neuer Domain im Backend konfiguriert wird, während das zugehörige SSL-Zertifikat noch nicht erweitert wurde. Der Store view ist dann in Magento vollständig konfiguriert, aber für Kunden nicht erreichbar, weil der Webserver für diese Domain kein gültiges Zertifikat anbieten kann. Ein Deployment-Checklisten-Eintrag, der SSL-Zertifikat-Erweiterung vor Store-view-Aktivierung verlangt, verhindert dieses immer wiederkehrende Problem zuverlässig.

Für Domains mit derselben Hauptdomain, etwa de.shop.com und fr.shop.com, ist ein Wildcard-Zertifikat mit DNS-01-Challenge oft die praktischere Wahl, da neue Subdomains automatisch vom bestehenden Zertifikat abgedeckt werden, ohne dass ein erneuter Ausstellungsvorgang nötig ist. Für vollständig unabhängige Domains wie shop.de und shop.fr ist dagegen ein SAN-Zertifikat mit HTTP-01-Challenge pro Domain der übliche Weg, da hier keine gemeinsame Wildcard-Basis existiert.

#!/usr/bin/env bash
set -euo pipefail

# Issue a single SAN certificate covering all store domains
certbot certonly --nginx \
  -d shop.de -d shop.fr -d shop.at \
  --cert-name multi-domain \
  --non-interactive --agree-tos -m ops@mironsoft.de

# Renewal is handled by certbot's own systemd timer, verify with:
certbot renew --dry-run

# Alternative for subdomains of one TLD: a single wildcard certificate
# covers every future subdomain automatically via DNS-01 challenge
certbot certonly --manual --preferred-challenges dns \
  -d "*.shop.com" -d "shop.com"

6. Cookie-Domain und Session-Grenzen zwischen Stores

Der Konfigurationswert web/cookie/cookie_domain bestimmt, für welche Domain Magento-Cookies wie die Session-ID oder der Warenkorb-Status gültig sind. Bei echtem Domain Mapping pro Store mit unterschiedlichen Top-Level-Domains, etwa shop.de und shop.fr, teilen sich die Stores keine gemeinsame Cookie-Domain, jeder Store view führt zwangsläufig eine eigene, isolierte Session. Das ist in den meisten Fällen auch gewünscht, da Warenkörbe zwischen unterschiedlichen Ländern und Währungen ohnehin nicht sinnvoll geteilt werden können.

Anders verhält es sich bei Subdomain-basiertem Domain Mapping, etwa de.shop.com und fr.shop.com. Hier kann eine gemeinsame Cookie-Domain wie .shop.com konfiguriert werden, wodurch ein eingeloggter Kunde beim Wechsel zwischen Subdomains eingeloggt bleibt, sofern auch die Kundendaten zwischen den Stores geteilt werden. Diese Entscheidung sollte bewusst getroffen werden, da eine geteilte Cookie-Domain ohne geteilte Kundendatenbank zu widersprüchlichem Verhalten führt.

7. Varnish und Full Page Cache pro Domain

Beim Einsatz von Varnish als Full Page Cache muss die VCL-Konfiguration den Host-Header als Teil des Cache-Keys berücksichtigen, sonst können bei Domain Mapping pro Store Cache-Einträge zwischen Domains vertauscht werden, mit gravierenden Folgen: Ein Kunde auf shop.fr könnte plötzlich für shop.de gecachte, englische oder deutsche Inhalte sehen. Magentos Standard-VCL-Template berücksichtigt den Host bereits korrekt, eigene Anpassungen an der VCL sollten diesen Mechanismus jedoch nicht versehentlich überschreiben.

Für die Cache-Invalidierung ist zusätzlich zu beachten, dass ein Produkt-Update, das mehrere Store Views betrifft, auch mehrere Purge-Requests an Varnish auslösen muss, jeweils mit dem korrekten Host-Header für die betroffene Domain. Magentos native Cache-Invalidierung berücksichtigt dies bereits, bei eigenen Erweiterungen des Cache-Invalidierungs-Mechanismus, etwa für externe Systeme, die per API Preisänderungen einspielen, muss diese Domain-Awareness explizit nachgebaut werden.

8. Duplicate Content zwischen Domains vermeiden

Ein Risiko bei Domain Mapping pro Store, das leicht übersehen wird, ist Duplicate Content, wenn versehentlich identische Produktinhalte über mehrere Domains erreichbar sind, etwa weil eine Domain fälschlich noch auf den globalen Produktkatalog statt auf den store-spezifischen Katalog verweist. Suchmaschinen werten dies als Duplizierung und können die Sichtbarkeit beider Versionen in den Suchergebnissen abwerten, unabhängig davon, dass es sich technisch um unterschiedliche Store Views handelt.

Die Lösung liegt in einer konsequenten Canonical-URL- und hreflang-Strategie, die auf denselben Domain-Zuordnungen basiert wie die Store-Resolution selbst. Jede Seite sollte ein Canonical-Tag auf ihre eigene Domain setzen, während hreflang-Tags auf die jeweils passenden Sprachversionen auf den anderen Domains verweisen. Diese beiden Mechanismen zusammen signalisieren Suchmaschinen eindeutig, dass es sich um bewusst getrennte, marktspezifische Inhalte handelt, statt um zufällige Duplizierung.

Zusätzlich sollte jede Domain eine eigene robots.txt und, sofern genutzt, einen eigenen x-default-hreflang-Eintrag für sprachneutrale Einstiegsseiten führen. Wird versehentlich eine einzige globale robots.txt über alle Domains hinweg ausgeliefert, etwa weil sie aus einem gemeinsamen Static-Asset-Verzeichnis stammt, können Crawling-Regeln entstehen, die für eine Domain sinnvoll sind, für eine andere aber versehentlich ganze Bereiche blockieren.

9. Domain-Strategien im Vergleich

Die folgende Tabelle vergleicht die drei gängigsten Ansätze für Domain Mapping pro Store.

Für Marken mit starkem lokalem Marktauftritt sind eigene länderspezifische TLDs meist die überzeugendste Wahl, trotz des höheren SSL- und Infrastrukturaufwands, da sie Vertrauen beim lokalen Publikum aufbauen und Suchmaschinen die klarsten Signale zur Marktausrichtung liefern.

10. Zusammenfassung

Erfolgreiches Magento 2 Domain Mapping pro Store beginnt bei der Base-URL-Konfiguration auf Store-View-Ebene, endet aber nicht dort: Vhost-Konfiguration, SSL-Zertifikate, Cookie-Domain-Entscheidungen und eine domain-bewusste Varnish-Strategie müssen konsistent zusammenspielen. Ein SAN-Zertifikat mit automatischer Erneuerung reduziert den Wartungsaufwand für mehrere echte Domains erheblich, während die Wahl zwischen Subdomains und eigenen TLDs eine strategische Entscheidung zwischen SEO-Klarheit und Infrastrukturkomplexität bleibt.

Wer zusätzlich Canonical-Tags und hreflang-Verweise konsequent auf dieselbe Domain-Struktur ausrichtet wie die technische Store-Resolution, vermeidet das Risiko von Duplicate-Content-Abwertungen. Die größte Fehlerquelle im Live-Betrieb bleibt ein neuer Store view, dessen Domain im Backend konfiguriert, aber dessen SSL-Zertifikat noch nicht erweitert wurde, weshalb dieser Schritt fest in jede Deployment-Checkliste gehört.

11. FAQ: Magento 2 Domain Mapping pro Store