Die Probleme bei der WordPress-zu-Astro-Migration, vor denen dich niemand warnt

Der offizielle Astro-Leitfaden zum Umzug weg von WordPress ist etwa 400 Wörter lang. Er schlägt zwei Optionen vor, zeigt auf ein Export-Werkzeug und endet mit einem Satz, der einräumt, dass "du jetzt viele deiner bestehenden Funktionen selbst bauen musst".

Das ist der ganze Leitfaden. Kein Abschnitt zu Weiterleitungen. Nichts zu Kommentaren. Nichts zu Formularen. Nichts zu Custom Fields.

Ich habe drei Kundenseiten von WordPress nach Astro migriert. Die Beiträge und Seiten waren nie der harte Teil. Der harte Teil war alles, was die Plugins still im Hintergrund gemacht haben, und die mehreren hundert URLs, die auf der alten Seite existierten und von denen niemand eine Liste hatte.

Ich habe die optimistische Version dieser Geschichte schon geschrieben, in der Claude einen Haufen Builder-Markup zu sauberen Komponenten plattgemacht hat und fast nichts kaputtging. Dieser Beitrag stimmt. Der hier ist die andere Hälfte: die Liste der WordPress-zu-Astro-Migrationsprobleme, die die Leitfäden überspringen, und was ich mit jedem davon tatsächlich mache.

Das setzt voraus, dass du dich schon zum Gehen entschieden hast. Wenn du noch abwägst, habe ich über ob WordPress 2026 noch die richtige Wahl ist und über wie die Performance- und Kostenzahlen tatsächlich aussehen geschrieben. Keines von beidem ist dieser Beitrag.

Das Export-Werkzeug gibt dir Blogbeiträge, keine Website

wordpress-export-to-markdown ist das Werkzeug, das die Astro-Doku empfiehlt, und es ist wirklich gut in dem, was es tut. Füttere es mit deinem WordPress-XML-Export, und es schreibt eine Markdown-Datei pro Beitrag mit Frontmatter, lädt die angehängten Bilder herunter, schreibt die Bildverweise um und behandelt Entwürfe, Seiten und Custom Post Types als separate Dateien.

Der Umfang ist allerdings dieser: Es liest das Feld post_content. Das ist das Feld, in das Gutenberg und der klassische Editor schreiben. Alles, was nicht in diesem Feld steht, existiert für den Export nicht.

Was nicht in diesem Feld steht: jeder Custom-Field-Wert, jede ACF-Gruppe, jeder Taxonomie-Begriff, der keine Kategorie und kein Tag ist, deine Menüstruktur, deine Widget-Bereiche, deine Formulardefinitionen, deine Kommentarstränge, deine Permalink-Einstellungen und jeder Inhalt, den ein Plugin in seiner eigenen Datenbanktabelle ablegt. Das ist kein Fehler im Werkzeug. Es ist eine Beschränkung des WordPress-XML-Exports, die das Werkzeug erbt.

Führ den Export also unbedingt zuerst aus. Und behandle das Ergebnis dann als eine Eingabe unter mehreren, nicht als "die Migration".

Page-Builder-Seiten muss man rendern, nicht exportieren

Öffne eine Divi- oder WPBakery-Seite in der Datenbank, und du siehst post_content voller Shortcodes: [vc_row][vc_column][vc_column_text]. Jag das durch einen Markdown-Konverter, und du bekommst die Shortcodes als wörtlichen Text. Elementor ist auf andere Weise schlimmer. Es legt sein Layout überhaupt nicht in post_content ab. Es speichert die ganze Seite als JSON in postmeta und lässt post_content fast leer, was heißt, dass ein sauberer XML-Export einer Elementor-Seite leer herauskommen kann.

Es gibt hier keinen zuverlässigen automatischen Konverter, und ich wäre misstrauisch gegenüber jedem, der dir einen verkauft. Was funktioniert, ist der langweilige Weg: Seite im Browser rendern, das gerenderte HTML nehmen und das konvertieren. Eine Überschrift ist im DOM ein h2, auch wenn sie in der Datenbank ein Shortcode ist.

Mein tatsächlicher Ablauf: Ich crawle die Live-Seite und speichere das gerenderte HTML jeder URL, bevor ich irgendetwas anfasse. Dann arbeite ich damit. Für Blogbeiträge konvertiere ich den gerenderten Artikelkörper zu Markdown. Für builder-gebaute Landingpages konvertiere ich gar nicht, sondern baue sie als Astro-Komponenten neu, mit dem gerenderten HTML als Referenz. Nach drei Seiten habe ich aufgehört, die Landingpages automatisieren zu wollen. Fünf oder zehn von Hand neu gebaute Marketingseiten sind ein Arbeitstag. Sich mit einem Elementor-JSON-Parser zu prügeln, ist eine Woche, und das Ergebnis ist schlechter.

ACF ist Schema, nicht Inhalt

Das ist der Punkt, der Leute erwischt, die überwiegend Blogs migrieren. Ein Blog ist eine flache Liste von Beiträgen, er bildet sich also fast eins zu eins auf Astro Content Collections ab. Eine Seite mit Advanced Custom Fields ist nicht flach.

Repeater und Flexible-Content-Layouts sind die schwierigen. Ein Flexible-Content-Feld ist im Kern eine seitenweise Liste beliebiger Blöcke mit beliebigen Formen, in postmeta abgelegt als Schlüsselsatz wie sections_0_hero_title und sections_1_gallery_images_0_image. Das aus einem XML-Export zu rekonstruieren ist möglich, aber elend.

Ich mache das nicht mehr aus dem Export. Stattdessen ziehe ich die strukturierten Daten über die WordPress-REST-API, mit ACF via show_in_rest freigegeben, und schreibe sie als JSON oder YAML in eine Content Collection mit Zod-Schema. Auf der Astro-Seite bekommst du typisierte Daten, was ein echtes Upgrade ist, und Astro lässt deinen Build laut scheitern, wenn ein Feld fehlt, statt ein leeres div zu rendern.

Custom Post Types und Custom Taxonomies brauchen jeweils eine Entscheidung, keine Konvertierung. Ein team_member-CPT mit sechs Einträgen wird eine Datensammlung. Ein case_study-CPT mit 80 Einträgen und eigenem Archiv wird eine echte Content Collection mit eigenen Routen, und jetzt gehört dir auch die Archiv-Paginierung. Die Custom Taxonomies sind die heimtückischen, denn jeder Begriff hat auf der alten Seite eine indexierte Archiv-URL erzeugt, und diese URLs sind gleich 404.

Von allen WordPress-zu-Astro-Migrationsproblemen auf dieser Liste ist das dasjenige, das deine Schätzung am ehesten verdoppelt. Zähl deine CPTs und Taxonomien, bevor du den Auftrag zuschneidest. Auf einer der drei Seiten stellte sich die "einfache Broschürenseite" als eine mit vier Custom Post Types heraus, die niemand erwähnt hatte.

Die Weiterleitungskarte ist der größte Teil der Arbeit

Wenn du nur eine Sache aus diesem Beitrag mitnimmst: Die Weiterleitungskarte ist die Migration. Alles andere ist Rendern.

WordPress erzeugt weit mehr indexierte URLs, als die Seitenzahl vermuten lässt. Die Liste, die ich jedes Mal durchgehe:

• Permalink-Struktur. Wenn die alte Seite /2019/03/beitragstitel/ benutzt hat und deine Astro-Seite /beitragstitel/, ändert sich jede einzelne Beitrags-URL.
• URLs im Stil /?p=123. Jeder Beitrag ist für immer über seine ID-basierte URL erreichbar, und die werden geteilt, gebookmarkt und verlinkt.
• Anhangseiten. WordPress erzeugt für jede hochgeladene Mediendatei eine Seite. Die werden indexiert, sie ranken für Bildanfragen, und es können Tausende sein. WordPress 6.4 hat eine Option ergänzt, sie auf die Datei selbst weiterzuleiten, was dir zeigt, wie sehr sie ein Problem waren.
• Kategorie-, Tag- und Custom-Taxonomie-Archive, dazu Autorenarchive und Datumsarchive.
• Paginierte Archive: /blog/page/2/, /category/news/page/3/, immer weiter.
• Feeds: /feed/, /comments/feed/, Feeds pro Kategorie. Auf denen leben echte Abonnenten.
• sitemap_index.xml und alle Kind-Sitemaps, die dein SEO-Plugin erzeugt hat.
• Abschließende Schrägstriche. WordPress beendet URLs standardmäßig mit einem Schrägstrich. Astros trailingSlash-Einstellung und das Verhalten deines Hosters haben beide ein Stimmrecht, und sie sind sich nicht immer einig.

Hol dir die echte Liste aus drei Quellen und führ sie zusammen: ein Crawl der Live-Seite, der Seiten-Bericht der Search Console für alles, was je eine Impression hatte, und deine Server-Zugriffsprotokolle der letzten 90 Tage. Der Crawl übersieht verwaiste URLs. Die Search Console übersieht Dinge mit null Impressionen, die trotzdem Direktzugriffe bekommen. Die Logs fangen beides.

Dann gibt es ein technisches Detail, das mich überrascht hat. Astros eingebaute redirects-Konfiguration liefert bei einem vollständig statischen Build ohne Adapter keine 301 aus. Sie schreibt eine HTML-Seite mit einem <meta http-equiv="refresh">-Tag, und die Doku sagt klar, dass sie "keine Statuscodes unterstützt". Google folgt einem Meta-Refresh meistens, aber es ist keine permanente Weiterleitung, und es ist nicht das, was du für ein paar hundert URLs mit Rankings willst.

Mach Weiterleitungen also am Edge, nicht im Framework. Auf Cloudflare Pages ist das eine _redirects-Datei, und achte auf die Decke: 2.000 statische Weiterleitungen und 100 dynamische, zusammen 2.100, alles darüber braucht Bulk Redirects. Zweitausend klingt gewaltig, bis du 1.400 Anhangseiten hast. Genau da verdienen Wildcard-Regeln ihr Geld: eine dynamische Regel für /wp-content/uploads/* schlägt 1.400 statische Zeilen.

Ich halte das Ganze als CSV im Repo, erzeuge die _redirects-Datei beim Build daraus und teste sie nach dem Deploy gegen die Crawl-Liste. Dieselbe Disziplin gehe ich in meiner website migration SEO checklist durch, die die Suchseite davon ausführlicher behandelt als ich hier.

Formulare: Frag, wo die Einsendungen hingehen, dann frag, wo die alten sind

Zwei getrennte Probleme, und meistens denken Leute nur an das erste.

Die neue Seite braucht einen Ort, an dem Formular-Posts landen, denn ein statischer Build hat kein PHP, das sie annimmt. Je nach Hoster ist das ein Formular-Endpunkt-Dienst, eine Serverless Function oder die Formularverarbeitung deines Hosters. Gut, das ist eine bekannte Aufgabe.

Was vergessen wird, ist das Archiv. Gravity Forms speichert jeden Eintrag in der WordPress-Datenbank, es können also Jahre an Leads unter Formulare > Import/Export liegen, die seit 2021 niemand angeschaut hat. Exportier sie als CSV, bevor die Datenbank verschwindet. WPForms ist dieselbe Geschichte.

Contact Form 7 ist die umgekehrte Falle: Es speichert standardmäßig nichts. Wenn niemand Flamingo oder ein CFDB-Add-on installiert hat, existiert jede Einsendung, die diese Seite je bekommen hat, nur in dem Postfach, das die Benachrichtigungsmail bekommen hat. Wenn der Kunde nach seinen alten Anfragen fragt, nachdem du den Server abgeschaltet hast, gibt es nichts zu geben. Prüf, in welchem Fall du bist, solange die Seite noch läuft.

Ebenfalls prüfenswert: woran das Formular hing. Empfänger von Benachrichtigungen, Mailchimp- oder CRM-Integrationen, bedingte Logik, versteckte Felder mit UTM-Daten, Spamschutz. Das sichtbare Formular hat fünf Felder. Die Installation dahinter ist meistens mehr.

Kommentare: Entscheide vor dem Export

Zieh zuerst die Kommentarzahl, dann entscheide. Ich hatte auf drei Seiten alle drei Antworten.

Wenn sie nahe null ist, wirf sie weg. Niemand wird es merken, und du sparst dir eine Integration.

Wenn es ein echtes Archiv gibt und es Wert hat, ist der Umzug zu Giscus der Weg, den ich heute nehmen würde. Es liegt auf GitHub Discussions, und die Community-Migrationsskripte folgen alle demselben Muster: pro Beitrag eine Diskussion mit der Beitrags-URL als Titel anlegen, dann jeden alten Kommentar dort hineinposten, mit dem ursprünglichen Autor und dem ursprünglichen Datum in einer Kopfzeile. Die Kommentare sind für ihre Autoren nicht mehr bearbeitbar und werden alle vom Konto deines Tokens gepostet, was ein echter Rückschritt ist. Es ist immer noch besser als löschen.

Im Zweifel exportier die Kommentare als JSON und archivier das, auch wenn du sie nie anzeigst. Sie anzuzeigen ist eine Entscheidung, die du später treffen kannst. Die Datenbank zu löschen nicht.

Eine Sache in jedem Fall: Kommentar-Paginierung und #comment-1234-Anker waren auch URLs.

Suche, verwandte Beiträge und die anderen stillen Plugins

WordPress hatte ein Suchfeld. Es funktionierte, weil eine Datenbank und PHP dahinter standen. Auf einem statischen Build ist das weg.

Pagefind ist die Standardantwort und sie ist gut: Es indexiert dein gebautes HTML nach dem Build, liefert den Index mit der Seite aus und führt die Anfrage im Browser aus, wobei es nur die nötigen Chunks lädt statt des ganzen Index. Es gibt eine Astro-Integration dafür. Rechne mit einer Stunde, nicht mit einem Tag.

Verwandte Beiträge sind der Punkt, der Leute erwischt. In WordPress war das ein Plugin, das zur Laufzeit eine Taxonomie-Abfrage gemacht hat. In Astro schreibst du die Logik selbst, meistens Abgleich über gemeinsame Tags zur Build-Zeit. Nicht schwer, aber niemand schreibt es ins Leistungsverzeichnis, weil sich niemand daran erinnert, dass es ein Plugin war.

Die vollständige Liste der Dinge, die ich vor einem Angebot inzwischen prüfe, weil jedes davon ein Plugin war, das still eine Aufgabe erledigt hat:

• Suche
• Verwandte Beiträge
• Breadcrumbs
• Schema-Markup, das das SEO-Plugin erzeugt hat
• Die XML-Sitemap
• Weiterleitungen, die bereits im Redirect Manager eines SEO-Plugins liegen und in die neue Karte übernommen werden müssen, nicht verloren gehen
• Canonical-Tags und Metadaten aus dem SEO-Plugin
• Cookie-Einwilligung
• Analytics-Einbindung
• Social-Share-Buttons
• Alles, was auf einem Cron-Zeitplan läuft

Den Punkt mit dem Redirect Manager sage ich lieber zweimal. Wenn es die Seite schon eine Weile gibt, liegt in Yoast oder Rank Math vermutlich ein Stapel alter Weiterleitungen aus früheren URL-Änderungen. Die tragen weiterhin Linkkraft. Exportier sie und falte sie in deine neue Karte.

Medien-URLs und die Assets, die du nicht kontrollierst

WordPress schreibt Uploads nach /wp-content/uploads/JJJJ/MM/dateiname.jpg und erzeugt von jedem mehrere skalierte Kopien: thumbnail, medium, medium_large, large, plus alle Größen, die dein Theme registriert hat. Diese skalierten Dateien haben eigene URLs, sie tauchen in srcset-Attributen auf und sie werden indexiert.

Wenn deine Astro-Seite Bilder an einen sinnvollen Ort wie /images/ legt, bricht jede dieser alten URLs. Das zählt mehr, als es klingt, denn andere Seiten verlinken direkt darauf, Google Images hat sie im Index und alte Newsletter zeigen darauf.

Was ich inzwischen mache: Ich behalte die Pfadstruktur /wp-content/uploads/ für bestehende Medien auf der neuen Seite. In einem Repo ohne WordPress darin sieht das albern aus. Es heißt aber auch, dass ein ganzes Verzeichnis von URLs, auf die Leute schon verlinken, weiter auflöst, ohne eine einzige Weiterleitungsregel zu verbrauchen. Neue Bilder kommen in die neue Struktur. Die alten bleiben, wo sie sind.

Dann crawl in die andere Richtung nach direkt verlinkten Assets: PDFs, die aus Kunden-E-Mails verlinkt sind, Bilder, die in fremden Artikeln eingebettet sind, Dateien, auf die nie eine Seite verwiesen hat und die trotzdem täglich heruntergeladen werden. Die Zugriffsprotokolle sagen es dir. Sonst nichts.

Die Checkliste

Bevor du anfängst:

1. Crawle die Live-Seite und speichere das gerenderte HTML jeder URL.
2. Exportiere URL-Listen aus dem Crawl, der Search Console und 90 Tagen Zugriffsprotokollen. Führ sie zusammen.
3. Zähl Custom Post Types, Custom Taxonomies und ACF-Feldgruppen.
4. Exportiere Formulareinträge aus jedem Formular-Plugin als CSV.
5. Exportiere Kommentare als JSON, egal was du damit vorhast.
6. Exportiere alle Weiterleitungen, die schon im SEO-Plugin liegen.
7. Liste jedes Plugin auf und schreib auf, was es fürs Frontend tut.

Währenddessen:

8. Konvertiere Beiträge aus dem Export-Werkzeug, Landingpages aus gerendertem HTML.
9. Zieh ACF und eigene Daten über die REST-API in typisierte Content Collections.
10. Bau die Weiterleitungskarte als CSV im Repo und erzeuge daraus die Weiterleitungsdatei des Hosters.
11. Lass /wp-content/uploads/ für bestehende Medien intakt.
12. Ersetze Suche, verwandte Beiträge, Sitemap und Schema ausdrücklich.
13. Entscheide einmal über abschließende Schrägstriche und prüf, ob dein Hoster zustimmt.

Danach:

14. Teste jede URL aus der zusammengeführten Liste gegen die neue Live-Seite. Jede, keine Stichprobe.
15. Beobachte den Abdeckungsbericht der Search Console vier Wochen lang.
16. Schalte den alten Server mindestens 30 Tage lang nicht ab.

Lieber zum Ausdrucken? Lade die komplette Checkliste als PDF — 9 Seiten, über 70 Punkte, ohne Login.

Was ich weiterhin falsch mache

Die meisten WordPress-zu-Astro-Migrationsprobleme oben haben eine bekannte Lösung. Was ich immer wieder unterschätze, ist nicht technisch. Es ist die Bestandsaufnahme. Auf jeder Seite, die ich migriert habe, war etwas, das niemand erwähnt hatte: ein Custom Post Type, eine Landingpage aus einer alten Kampagne, die immer noch Traffic bekommt, ein PDF, das aus einer gedruckten Broschüre verlinkt ist. Das Werkzeug für die Konvertierung ist inzwischen in Ordnung. Das Werkzeug, um herauszufinden, was tatsächlich existiert, ist ein Crawl, ein paar Logs und ein langsamer Nachmittag.

Der ehrliche Rat lautet also: Verbring den ersten Tag mit Inventur und schreib keinen Code. Es fühlt sich nach Trödeln an. Ist es nicht. Wenn du einen Realitätscheck willst, wie tief eine bestimmte Migration geht, bevor du dich festlegst, melde dich, und ich sage dir, was ich zuerst anschauen würde.