WordPress-Domainwechsel mit WP-CLI: URLs sicher ersetzen

Für einen WordPress-Domainwechsel genügt es, unter „Einstellungen > Allgemein“ zwei URLs anzupassen. Diese verbreitete Annahme ist falsch: Die beiden Felder ändern zentrale Optionen, erfassen aber keine alten Adressen in Beiträgen, Medienangaben, Widgets oder Plugin-Einstellungen.

Ein pauschales Suchen und Ersetzen im SQL-Dump ist ebenfalls riskant. WordPress und viele Plugins speichern strukturierte Einstellungen als serialisierte PHP-Daten. Darin ist die Länge einzelner Zeichenfolgen vermerkt. Eine unbedachte Textersetzung kann diese Längenangaben ungültig machen und damit ganze Optionen beschädigen.

WP-CLI löst genau dieses Problem: Der Befehl search-replace erkennt serialisierte Daten und kann vor der eigentlichen Änderung einen Testlauf ausführen. Entscheidend ist allerdings, den Suchbereich sauber zu definieren und das Ergebnis nicht allein an einer funktionierenden Startseite zu messen.

Lege die zu ersetzende Adresse exakt fest

Verwende als Suchwert möglichst die vollständige bisherige Adresse einschließlich Protokoll. Für einen Wechsel von einer Staging-Domain auf die öffentliche Domain wäre das beispielsweise:

https://staging.example.com
https://www.example.com

Die vollständige Adresse ist sicherer als eine Suche nur nach staging.example.com. Eine reine Hostnamen-Ersetzung könnte auch E-Mail-Adressen, technische Kennungen oder Zeichenfolgen verändern, die gar keine Website-URL darstellen.

Prüfe außerdem, ob mehrere Varianten vorkommen. Wurde die Website zeitweise ohne TLS betrieben, können sowohl http:// als auch https:// gespeichert sein. Auch Varianten mit und ohne www müssen getrennt betrachtet werden. Für jede tatsächlich vorhandene Quelladresse führst du einen eigenen Testlauf aus.

Die aktuell in der Datenbank gespeicherten Hauptadressen kannst du mit WP-CLI abfragen:

wp option get home
wp option get siteurl

Wenn die Konstanten WP_HOME oder WP_SITEURL in der wp-config.php gesetzt sind, reicht eine Datenbankänderung für diese Werte nicht aus. Dann musst du die Konfiguration passend zur Zielumgebung ändern.

Sichere die Datenbank und stoppe parallele Änderungen

Vor der Ersetzung brauchst du einen wiederherstellbaren Datenbankexport. Lege ihn außerhalb des öffentlich erreichbaren Webverzeichnisses ab. Ein SQL-Backup im Webroot ist zwar bequem, unter Umständen aber auch bequem herunterladbar.

wp db export /sicherer/pfad/vor-domainwechsel.sql

Prüfe anschließend, ob die Datei vorhanden und plausibel groß ist. Ein erfolgreich beendeter Befehl ersetzt keine Kontrolle, dass der Export tatsächlich am erwarteten Ort liegt.

Während des Wechsels sollten Redakteure keine Inhalte bearbeiten und Bestellungen, Formulare oder andere Schreibvorgänge nicht parallel in die zu migrierende Datenbank laufen. Bei einer öffentlich genutzten Website lohnt es sich deshalb, ein kurzes WordPress-Wartungsfenster passend zum Geschäft zu planen. Sonst ist der Datenbestand bereits veraltet, bevor der Domainwechsel abgeschlossen ist.

Lass WP-CLI die Änderungen zuerst simulieren

Der Parameter –dry-run führt keine Ersetzung durch. Er zeigt dir, in welchen Tabellen und Spalten Treffer vorkommen und wie viele Werte betroffen wären:

wp search-replace \
  'https://staging.example.com' \
  'https://www.example.com' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --report-changed-only \
  --dry-run

–all-tables-with-prefix bezieht auch eigene Tabellen von Plugins ein, sofern sie denselben Tabellenpräfix verwenden. Das ist bei Shop-, Formular- oder Mehrsprachen-Plugins relevant. –all-tables wäre breiter und kann Tabellen anderer Installationen in derselben Datenbank erfassen. Verwende diesen Parameter nur, wenn du den Datenbankaufbau genau geprüft hast.

Mit –report-changed-only blendest du Tabellen ohne Treffer aus. Das macht den Bericht lesbarer, ändert aber nichts am Suchbereich.

Ein unerwartetes Ergebnis ist ein Grund zum Anhalten:

• Keine Treffer: Möglicherweise verwendest du die falsche Datenbank, einen unpassenden Tabellenpräfix oder eine andere Schreibweise der alten Adresse.
• Treffer nur in wenigen Optionen: Vielleicht wurden Inhalte bereits umgestellt oder die Website nutzt überwiegend relative URLs.
• Sehr viele Treffer in unbekannten Tabellen: Prüfe zuerst, zu welchem Plugin oder alten Datenbestand diese Tabellen gehören.
• Treffer in Protokoll- oder Archivtabellen: Entscheide bewusst, ob historische Daten überhaupt geändert werden sollen.

Die vollständige Befehlsreferenz mit weiteren Parametern findest du in der Dokumentation zu wp search-replace.

Lass die GUID-Spalte normalerweise unverändert

Die Spalte guid in der Beitragstabelle enthält häufig eine URL, ist aber keine gewöhnliche Inhaltsadresse. Sie dient als global eindeutige Kennung eines Beitrags oder Anhangs. Deshalb schließt der Beispielbefehl sie mit –skip-columns=guid aus.

Ein Domainwechsel allein ist kein Anlass, diese Kennungen umzuschreiben. Wenn dein konkreter Importprozess andere Anforderungen hat, solltest du diese Ausnahme separat begründen und testen. Die Tatsache, dass eine Zeichenfolge wie eine URL aussieht, macht sie noch nicht zu einem Link, der aktualisiert werden muss.

Führe die Ersetzung mit denselben Parametern aus

Ist der Testlauf plausibel, entfernst du lediglich –dry-run. Suchwert, Zielwert, Tabellenumfang und ausgeschlossene Spalten bleiben unverändert:

wp search-replace \
  'https://staging.example.com' \
  'https://www.example.com' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --report-changed-only

WP-CLI verarbeitet dabei auch serialisierte PHP-Werte. Das ist der wesentliche Vorteil gegenüber einer blinden Ersetzung im SQL-Dump. Du solltest trotzdem keine Tabelle als unkritisch ansehen, nur weil das Werkzeug die Daten technisch korrekt schreiben kann. Protokolle, externe Referenzen oder historische Bestelldaten können fachlich unverändert bleiben sollen.

Wenn mehrere alte URL-Varianten existieren, wiederholst du den Ablauf für jede Variante: zuerst Testlauf, dann Ausführung. Beginne mit der spezifischsten Adresse. Eine breite Hostnamen-Ersetzung am Ende ist höchstens ein Diagnosewerkzeug und sollte nicht ungeprüft ausgeführt werden.

Nutze für Deployments alternativ einen transformierten Export

Bei einem geregelten Staging-zu-Produktion-Deployment möchtest du die Staging-Datenbank möglicherweise gar nicht verändern. WP-CLI kann die Ersetzung stattdessen während des Exports anwenden:

wp search-replace \
  'https://staging.example.com' \
  'https://www.example.com' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --export=/sicherer/pfad/produktion.sql

Die Quelldatenbank bleibt dabei auf der Staging-Domain, während die exportierte SQL-Datei bereits die Zieladresse enthält. Das ist hilfreich, wenn Staging nach dem Deployment weiterverwendet werden soll. Vor dem Import in Produktion brauchst du trotzdem ein Backup der dortigen Datenbank und einen klaren Plan für Inhalte, die seit dem letzten Abzug entstanden sind.

Prüfe nach der Ersetzung Datenbank, Browser und Funktionen

Führe den ursprünglichen Testlauf nach der Änderung erneut aus. Für die exakt gesuchte Quelladresse sollte er keine Treffer mehr melden:

wp search-replace \
  'https://staging.example.com' \
  'https://www.example.com' \
  --all-tables-with-prefix \
  --skip-columns=guid \
  --report-changed-only \
  --dry-run

Danach folgt die funktionale Prüfung im Browser. Öffne nicht nur die Startseite, sondern mindestens eine typische Inhaltsseite mit Bildern, eingebetteten Dateien oder Block-Einstellungen. Kontrolliere außerdem Anmeldung, interne Weiterleitungen und alle Formulare, die für den Geschäftsbetrieb relevant sind.

Die Entwicklerwerkzeuge des Browsers helfen bei Restfunden. Im Netzwerk-Tab erkennst du Anfragen an die alte Domain, etwa für Bilder, Schriften, Skripte oder API-Endpunkte. Solche Verweise können aus der Datenbank stammen, aber ebenso aus Theme-Dateien, eigener Plugin-Logik oder einer externen Konfiguration.

Wenn ein Kontaktformular nach dem Umzug nicht mehr zuverlässig zustellt, liegt das nicht zwingend an der URL-Ersetzung. Dann kannst du den E-Mail-Versand des WordPress-Kontaktformulars getrennt eingrenzen.

Ordne verbliebene alte URLs nach ihrer Quelle

Ein fehlerfreier Datenbanklauf garantiert nicht, dass die alte Domain vollständig verschwunden ist. WP-CLI bearbeitet in diesem Ablauf ausschließlich Datenbankwerte. Folgende Quellen benötigen eine eigene Prüfung:

• Konfigurationsdateien: Dazu gehören wp-config.php, Umgebungsvariablen und Deployment-Konfigurationen.
• Theme- und Plugin-Code: Fest eingetragene URLs in PHP-, JavaScript- oder CSS-Dateien werden nicht verändert.
• Webserver-Regeln: Weiterleitungen und Hostnamen in der Serverkonfiguration liegen außerhalb von WordPress.
• Externe Dienste: Webhooks, OAuth-Rücksprungadressen, Zahlungsanbieter und E-Mail-Dienste können die alte Domain weiterhin gespeichert haben.
• Caches: Seiten-, Objekt-, Browser- oder CDN-Caches können alte Inhalte ausliefern, obwohl die Datenbank bereits korrekt ist.

Ein Aufruf von wp cache flush leert den WordPress-Objektcache, aber nicht automatisch jeden Seiten- oder CDN-Cache. Wenn besonders Bilder nach dem Austausch weiterhin unter der alten Adresse erscheinen, hilft die getrennte Fehleranalyse für ein altes WordPress-Bild aus dem Cache.

Behandle Multisite als eigenen Migrationsfall

Bei WordPress Multisite können Domains in Netzwerk- und Site-Tabellen, in einzelnen Blogtabellen sowie in der Serverkonfiguration vorkommen. Ein einzelner Suchlauf ist dort keine ausreichende Migrationsstrategie. Prüfe zuerst, ob nur eine Unterseite oder das gesamte Netzwerk umzieht, und führe die Befehle im richtigen Netzwerkkontext aus.

Besonders bei Domain-Mapping, unterschiedlichen Tabellenpräfixen oder getrennten Produktionsdomains brauchst du eine Zuordnung von alter zu neuer Adresse. Eine allgemeine Ersetzung des Hostnamens kann sonst mehrere Websites verändern, die absichtlich verschiedene Domains verwenden.

Fazit: Erst den Suchraum klären, dann ersetzen

WP-CLI macht einen WordPress-Domainwechsel kontrollierbar, weil du Änderungen vorab simulieren und serialisierte Daten korrekt verarbeiten kannst. Sicherheit entsteht jedoch aus dem Ablauf: vollständige Quelladresse festlegen, Datenbank sichern, Tabellenumfang prüfen, GUID ausschließen, Testlauf auswerten und anschließend gezielt verifizieren.

Bleiben danach alte URLs übrig, ist eine weitere pauschale Ersetzung selten die beste Reaktion. Ordne den Fund zuerst seiner Quelle zu. Datenbank, Konfiguration, Code, externe Dienste und Caches brauchen jeweils ein anderes Werkzeug. So wird aus dem Domainwechsel ein nachvollziehbarer Eingriff statt einer SQL-Lotterie.

Häufige Fragen

Kurz beantwortet, damit du schneller einschätzen kannst, was für dein Projekt wichtig ist.

Kann WP-CLI serialisierte WordPress-Daten sicher ersetzen?

Ja. Der Befehl wp search-replace berücksichtigt serialisierte PHP-Daten und passt die gespeicherten Längenangaben an. Ein Backup und ein Testlauf bleiben trotzdem erforderlich.

Sollte ich beim Domainwechsel die WordPress-GUID ersetzen?

In der Regel nicht. Die GUID dient als dauerhafte Kennung eines Beitrags oder Anhangs und ist keine normale Inhalts-URL. Schließe die Spalte deshalb mit –skip-columns=guid aus.

Warum erscheint nach der Ersetzung noch die alte Domain?

Die Adresse kann außerhalb der geprüften Datenbanktabellen liegen, etwa in der wp-config.php, im Theme-Code, bei einem externen Dienst oder in einem Cache. Ordne den Fund zuerst seiner Quelle zu.

Kann ich die Ersetzung ohne SSH-Zugang durchführen?

Ein dafür geeignetes Migrations-Plugin kann die Aufgabe übernehmen, wenn kein Kommandozeilenzugang verfügbar ist. Es sollte serialisierte Daten unterstützen, einen Testlauf anbieten und vor der Änderung ein Datenbank-Backup ermöglichen.