Migration von WordPress

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

Bevor Sie beginnen

Bereiten Sie Folgendes vor:

• Ein Backup der WordPress-Datenbank und von wp-content/uploads.
• Eine EmDash-Site mit konfiguriertem Speicher, wenn 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-Site installierte Plugin EmDash Exporter.

Notieren Sie die aktuelle Permalink-Struktur, den kanonischen Origin, Weiterleitungen, Menüs, aktive Beitragstypen, Taxonomien und alle plugin-eigenen Felder, die die neue Site beibehalten muss.

Eine Importmethode wählen

Die Eingabe einer Site-URL ohne den Exporter prüft nur die öffentliche WordPress-REST-API. Die Prüfung 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

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

Sie können auch die URL der WordPress-Site eingeben. Sobald der Exporter erkannt wird, autorisieren Sie EmDash über den WordPress-Bildschirm für Anwendungspasswörter. Auf lokalen HTTP-Entwicklungssites 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 WordPress-Sichtbarkeitsregeln werden aus diesen Status nicht rekonstruiert. Prüfen Sie jeden importierten Entwurf vor der Veröffentlichung.

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, Einbettungen, Shortcodes, Page-Builder-Markup und von Plugins definierte Blöcke auf der gerenderten EmDash-Site.

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

Sammlungen und Felder

Zu den Standardzuordnungen für 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 Importfelder, statt jeden beliebigen Meta-Schlüssel zu kopieren. Betrachten Sie die Analyse als Checkliste für Felder, die möglicherweise separat konvertiert werden müssen.

Der Pfad über den EmDash Exporter kann benutzerdefinierte Metadaten und Werte von Advanced Custom Fields (ACF) kopieren, wenn die Zielsammlung passende Felder hat. Er kann auch die unterstützten Felder für Beitragsbild sowie für Yoast- oder Rank-Math-SEO erstellen und befüllen, wenn die zugehörigen Importschalter aktiviert sind. Prüfen Sie serialisierte PHP-Werte, Repeater, Flexible Content und plugin-spezifische Strukturen, statt anzunehmen, dass ihre WordPress-Darstellung zu einem EmDash-Feldtyp passt.

Autoren und Bylines

Ein zugeordneter WordPress-Autor wird zum Eigentümer des Eintrags. Für die Nennung in der Darstellung werden Bylines verwendet. Gibt es keine Benutzerzuordnung, erstellt EmDash auf Grundlage der WordPress-Autorenidentität eine Gast-Byline oder verwendet eine vorhandene wieder.

Taxonomien

Kategorien und Tags werden in die passenden EmDash-Taxonomiedefinitionen importiert. Der Exporter-Pfad kann Definitionen für benutzerdefinierte Taxonomien erstellen. 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 Quell-Site muss erreichbar bleiben, während EmDash Anhänge herunterlädt. Weiterleitungen von einer Anhang-URL werden validiert, bevor ihnen gefolgt wird.

Einen teilweisen Import wiederholen

Der Admin-Import ist darauf ausgelegt, vorhandene Einträge zu überspringen, doch die Grenze seines Abgleichs ist wichtig:

• Vorhandene Inhalte werden nach Sammlung, Slug und Locale abgeglichen, nicht nach WordPress-ID.
• Hat sich ein Quell-Slug zwischen den Versuchen geändert, prüfen Sie beide Einträge und lösen Sie das Duplikat manuell auf.
• Beim erneuten Ausführen des Medienschritts werden bereits gespeicherte, byte-identische Dateien anhand des Inhalts-Hashes 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

Prüfen Sie die importierte Site gegen die Quelle:

• Zählen Sie Einträge nach Beitragstyp und Status.
• Öffnen Sie repräsentative Inhalte aus Gutenberg, Classic Editor, Shortcodes und Page Buildern.
• Bestätigen Sie, dass Beitragsbilder und Inline-Medien über EmDash-URLs aufgelöst werden.
• Prüfen Sie Autoren, Bylines, Kategorien, Tags, benutzerdefinierte Taxonomien und Übersetzungen.
• Testen Sie Menüs, Kommentare, Site-Identität und SEO-Felder, wenn sie über den Exporter importiert wurden.
• Crawlen Sie alte öffentliche URLs und bereiten Sie Weiterleitungen für jede geänderte Route vor.
• Verifizieren Sie, dass Entwürfe für ausgeloggte Besucher unzugänglich bleiben.

Behalten Sie das Backup und die WordPress-Bereitstellung, bis die neue Site in der Produktion erfolgreich gelaufen ist und kein Rollback mehr erforderlich 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.

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 verbleiben in der Medienfehlerliste.

Das Theme anpassen

Verwenden Sie getEmDashCollection() für Archivrouten und getEmDashEntry() für eine Slug-Route. entry.id ist der Routenbezeichner und normalerweise der Slug; entry.data.id ist die gespeicherte Inhalts-ID, die von den Beziehungs-Helpern 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.