Migration von WordPress

Verwenden Sie den EmDash-Admin, um eine WordPress-Website zu analysieren, kompatible Sammlungen vorzubereiten, Inhalte zu importieren, Medien zu kopieren und URLs umzuschreiben. Halten Sie die WordPress-Website verfügbar, bis die importierte Website die Überprüfung bestanden hat.

Bevor Sie beginnen

Bereiten Sie die folgenden Punkte vor:

• Ein Backup der WordPress-Datenbank und von wp-content/uploads.
• Eine EmDash-Website mit konfiguriertem Speicher, falls Sie Medien kopieren möchten.
• Ein EmDash-Administratorkonto. Der WordPress-Import erfordert die Berechtigung import:execute.
• Entweder einen vollständigen WordPress-eXtended-RSS-Export (WXR) oder das auf der WordPress-Website installierte Plugin EmDash Exporter.

Halten Sie die aktuelle Permalink-Struktur, den kanonischen Origin, Weiterleitungen, Menüs, aktive Beitragstypen, Taxonomien und alle Plugin-eigenen Felder fest, die die neue Website beibehalten muss.

Eine Importmethode wählen

Wenn Sie eine Website-URL ohne den Exporter eingeben, wird nur die öffentliche WordPress-REST-API abgefragt. Die Abfrage kann WordPress erkennen und öffentliche Beiträge, Seiten und Medien zählen, aber keinen direkten REST-Import durchführen.

Eine WXR-Datei exportieren

Öffnen Sie in WordPress Tools → Export, wählen Sie All content und laden Sie die XML-Exportdatei herunter. Eine WXR-Datei verweist auf Medien auf dem WordPress-Origin; sie enthält nicht die Bytes der Anhänge.

Den EmDash Exporter verbinden

Prüfen Sie die Exporter-Version im WordPress-Bildschirm Plugins. Kommentare, Menüs, das Logo und das Favicon erfordern Exporter 1.2.0 oder neuer. Bei einer früheren Version wird der Import ohne sie abgeschlossen und meldet sie nicht als fehlend.

Öffnen Sie mit Exporter 1.2.0 oder neuer in WordPress Tools → EmDash Migration und erzeugen Sie einen Migrationsschlüssel. Fügen Sie den Schlüssel auf der EmDash-Importseite ein.

Mit jeder Exporter-Version können Sie auch die URL der WordPress-Website eingeben. Wird der Exporter erkannt, autorisieren Sie EmDash über den WordPress-Bildschirm für Anwendungspasswörter. Auf lokalen HTTP-Entwicklungsseiten geben Sie den WordPress-Benutzernamen und das Anwendungspasswort manuell ein, da der Autorisierungs-Callback HTTPS erfordert.

Über den Admin importieren

Konvertierungsverhalten

Status

Der Importer ordnet WordPress-Status wie folgt zu:

Geplante Termine und die Sichtbarkeitsregeln von WordPress werden aus diesen Status nicht rekonstruiert. Prüfen Sie jeden importierten Entwurf, bevor Sie ihn veröffentlichen.

Rich Text und wiederverwendbare Blöcke

Gutenberg-Markup wird in Portable Text konvertiert. Klassisches HTML wird vom selben Konverter verarbeitet. Prüfen Sie komplexe Blöcke, Embeds, Shortcodes, Page-Builder-Markup und Plugin-definierte Blöcke in der gerenderten EmDash-Website.

Blöcke, die WordPress auf dem Server rendert, etwa Latest Posts oder Blöcke aus Plugins, haben kein gespeichertes Markup. Sie werden als HTML-Blöcke importiert, die den ursprünglichen Block-Kommentar enthalten, zum Beispiel <!-- wp:latest-posts {"postsToShow":3} /-->. Diese Blöcke zeigen auf der Website keinen Inhalt an. Öffnen Sie im Editor den HTML-Tab des Blocks, um zu sehen, was er war, und bauen Sie ihn dann neu auf oder entfernen Sie ihn.

WXR-Einträge vom Typ wp_block werden als Abschnitte importiert. Sie werden nicht in eine gewöhnliche Inhaltssammlung importiert.

Sammlungen und Felder

Zu den Standardzuordnungen der Beitragstypen gehören post zu posts und page zu pages. Benutzerdefinierte Beitragstypen verwenden einen bereinigten Sammlungs-Slug. Der Vorbereitungsschritt fügt die Standardfelder für Titel, Portable-Text-Inhalt, Auszug und Beitragsbild hinzu, die die Analyse benötigt.

Vorhandene Felder mit kompatiblen Typen werden wiederverwendet. Ein Typkonflikt blockiert die Zuordnung dieser Sammlung; der Importer wandelt ein vorhandenes Feld nicht in einen anderen Typ um.

Benutzerdefinierte Felder und SEO-Daten

Die WXR-Analyse meldet nicht interne Post-Meta-Schlüssel und schlägt Feldnamen und -typen vor, aber der WXR-Datenbankimport schreibt die standardmäßigen importierten Felder, anstatt jeden beliebigen Meta-Schlüssel zu kopieren. Betrachten Sie die Analyse als Checkliste für Felder, die möglicherweise eine separate Konvertierung benötigen.

Der Pfad über den EmDash Exporter kann benutzerdefinierte Metadaten und Werte von Advanced Custom Fields (ACF) kopieren, wenn die Zielsammlung passende Felder hat. Bei einer ACF-Feldgruppe mit der Standortregel „Post Type is equal to“ schlägt die Analyse für jedes ACF-Feld der Gruppe ein Feld vor: Text-, Zahlen- und Wahr/Falsch-Felder erhalten passende Typen, und Select-, Checkbox-, Repeater-, Gruppen-, Beziehungs- und andere Felder, die eine Liste oder ein Objekt enthalten können, werden zu JSON-Feldern. Felder von Gruppen, die über andere Standortregeln zugewiesen sind, werden nur anhand der Meta-Schlüssel vorgeschlagen, die der Exporter meldet. Eine Sammlung, deren Felder ein früherer Import aus den Meta-Schlüsseln angelegt hat, behält sie, sodass ihre Repeater als ein Feld pro Zeile und Unterfeld ankommen. JSON-Werte behalten ihre WordPress-Form: Beziehungs-, Beitragsobjekt-, Benutzer- und Taxonomiefelder verweisen über ihre WordPress-IDs auf WordPress-Beiträge, -Benutzer und -Begriffe statt auf EmDash-Einträge, und Bild-, Datei- und Galeriefelder verweisen auf die WordPress-Mediendateien statt auf importierte EmDash-Medien. ACF-Gruppen-Unterfelder, die auf mehr als einem Beitrag gespeichert sind, können außerdem als separate Felder neben dem JSON-Feld der Gruppe erscheinen; behalten Sie die Kopie, die Ihre Templates verwenden. Prüfen Sie diese Werte, bevor Sie sie in Templates verwenden.

Der Exporter-Pfad kann außerdem die unterstützten Felder für Beitragsbild sowie für Yoast- oder Rank-Math-SEO anlegen und befüllen, wenn die zugehörigen Import-Schalter aktiviert sind.

Autoren und Bylines

Ein zugeordneter WordPress-Autor wird zum Eigentümer des Eintrags. Die Namensnennung erfolgt über Bylines. Gibt es keine Benutzerzuordnung, erstellt EmDash anhand der WordPress-Autorenidentität eine Gast-Byline oder verwendet eine vorhandene wieder.

Taxonomien

Kategorien und Schlagwörter werden in die passenden EmDash-Taxonomiedefinitionen importiert. Der Exporter-Pfad kann Definitionen für benutzerdefinierte Taxonomien anlegen. Eine benutzerdefinierte WXR-Taxonomie ohne passende EmDash-Definition wird als fehlend gemeldet, und ihre Zuweisungen werden übersprungen.

Medien

Die Medien-Deduplizierung vergleicht einen SHA-1-Hash der heruntergeladenen Bytes. Eine vorhandene Medienzeile mit demselben Hash wird wiederverwendet. Dateinamen und WordPress-IDs sind nicht der Deduplizierungsschlüssel.

Die Quellwebsite muss erreichbar bleiben, während EmDash Anhänge herunterlädt. Weiterleitungen einer Anhang-URL werden validiert, bevor ihnen gefolgt wird.

Einen teilweisen Import wiederholen

Der Admin-Import ist darauf ausgelegt, vorhandene Einträge zu überspringen, aber die Grenze seiner Zuordnung ist wichtig:

• Vorhandene Inhalte werden anhand von Sammlung, Slug und Locale zugeordnet, nicht anhand der WordPress-ID.
• Wenn sich ein Quell-Slug zwischen zwei Versuchen geändert hat, prüfen Sie beide Einträge und lösen Sie das Duplikat manuell auf.
• Wird der Medienschritt erneut ausgeführt, werden bereits gespeicherte, byteidentische Dateien anhand ihres Inhalts-Hashs wiederverwendet.
• Der Exporter-Ablauf sendet begrenzte Blöcke. Ein Neustart des Browser-Ablaufs führt die Inhaltsseiten erneut aus und baut die Beziehungszuordnungen aus übersprungenen Einträgen neu auf.

Der Admin speichert keine WXR-Fortsetzungsdatei. Das Flag --resume bei emdash import wordpress gehört zu einem separaten CLI-Workflow, der konvertierte JSON-Dateien auf die Festplatte schreibt; es setzt keinen Admin-Datenbankimport fort.

Vor der Umstellung überprüfen

Vergleichen Sie die importierte Website mit der Quelle:

• Zählen Sie die Einträge nach Beitragstyp und Status.
• Öffnen Sie repräsentative Inhalte aus Gutenberg, dem Classic Editor, Shortcodes und Page Buildern.
• Vergewissern Sie sich, dass Beitragsbilder und eingebettete Medien über EmDash-URLs aufgelöst werden.
• Prüfen Sie Autoren, Bylines, Kategorien, Schlagwörter, benutzerdefinierte Taxonomien und Übersetzungen.
• Testen Sie Menüs, Kommentare, Website-Identität und SEO-Felder, wenn sie über den Exporter importiert wurden.
• Durchsuchen Sie die alten öffentlichen URLs per Crawl und bereiten Sie Weiterleitungen für jede geänderte Route vor.
• Verifizieren Sie, dass Entwürfe für nicht angemeldete Besucher unzugänglich bleiben.

Behalten Sie das Backup und die WordPress-Bereitstellung, bis die neue Website erfolgreich in Produktion gelaufen ist und kein Rollback mehr nötig ist.

Fehlerbehebung

Die XML-Datei kann nicht geparst werden

Exportieren Sie die Datei erneut über Tools → Export und vergewissern Sie sich, dass der Download abgeschlossen wurde. Bearbeiten Sie das XML nicht mit einem Werkzeug, das die Kodierung ändert.

Eine Sammlung wird als inkompatibel markiert

Ein vorhandenes Feld hat denselben Slug, aber einen anderen Typ. Ändern Sie die Beitragstyp-Zuordnung oder gleichen Sie das Feld unter Content Types ab, bevor Sie es erneut versuchen. Der Vorbereitungsschritt fügt fehlende Felder hinzu, ändert aber keine vorhandenen Feldtypen.

Bot-Schutz blockiert den Exporter

Der Bot-Schutz von Cloudflare kann Anfragen von EmDash mit einer Challenge-Seite statt mit der Exporter-API beantworten. EmDash meldet dann, dass der Bot-Schutz die Verbindung blockiert hat. Lassen Sie die Exporter-Anfragen für die Dauer der Migration durch:

• Fügen Sie bei Super Bot Fight Mode oder anderen Cloudflare-WAF-Funktionen eine benutzerdefinierte Regel mit der Aktion Skip hinzu und platzieren Sie sie über jeder Regel, die Challenges ausgibt. Wählen Sie All Super Bot Fight Mode rules und, wenn die Zone den Modus I’m Under Attack verwendet, auch Security Level. Dieser Ausdruck trifft auf die Exporter-API mit und ohne schöne Permalinks zu, auch bei WordPress-Installationen in einem Unterverzeichnis, sowie auf die Mediendateien, die EmDash herunterlädt:

  (http.request.uri.path contains "/wp-json/emdash/v1/")
  or (http.request.uri.query contains "rest_route=%2Femdash%2Fv1%2F")
  or (http.request.uri.path contains "/wp-content/uploads/")

• Bot Fight Mode im Cloudflare-Free-Tarif lässt sich nicht per Regel überspringen. Schalten Sie ihn während der Migration aus und danach wieder ein.

Medien-URLs lassen sich nicht herunterladen

Prüfen Sie, ob der Quellanhang ohne WordPress-Sitzung erreichbar ist. Medien hinter einer Authentifizierung, entfernte Dateien und Weiterleitungen auf private Netzwerkadressen schlagen einzeln fehl und bleiben in der Medienfehlerliste.

Das Theme anpassen

Verwenden Sie getEmDashCollection() für Archivrouten und getEmDashEntry() für eine Slug-Route. entry.id ist die Routenkennung und normalerweise der Slug; entry.data.id ist die gespeicherte Inhalts-ID, die von den Beziehungs-Helfern verwendet wird.

Die folgende Route rendert einen importierten Beitrag:

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

Lesen Sie Ein WordPress-Theme portieren für die Zuordnung von Routen und Komponenten. Lesen Sie Inhaltsimport für die Endpunktverträge und die genauen Grenzen beim Wiederholen.