Migrare da WordPress

Usa l’amministrazione di EmDash per analizzare un sito WordPress, preparare collezioni compatibili, importare i contenuti, copiare i media e riscrivere gli URL. Mantieni disponibile il sito WordPress finché il sito importato non ha superato la verifica.

Prima di iniziare

Prepara i seguenti elementi:

• Un backup del database di WordPress e di wp-content/uploads.
• Un sito EmDash con l’archiviazione configurata, se prevedi di copiare i media.
• Un account amministratore di EmDash. L’importazione da WordPress richiede il permesso import:execute.
• Un’esportazione completa di WordPress eXtended RSS (WXR) oppure il plugin EmDash Exporter installato sul sito WordPress.

Annota la struttura attuale dei permalink, l’origine canonica, i reindirizzamenti, i menu, i tipi di contenuto attivi, le tassonomie e tutti i campi di proprietà dei plugin che il nuovo sito deve conservare.

Scegliere un metodo di importazione

Inserire l’URL di un sito senza l’exporter si limita a sondare l’API REST pubblica di WordPress. Il sondaggio può rilevare WordPress e contare gli articoli, le pagine e i media pubblici, ma non può eseguire un’importazione REST diretta.

Esportare un file WXR

In WordPress apri Tools → Export, seleziona All content e scarica il file di esportazione XML. Un file WXR punta ai media presenti sull’origine WordPress; non contiene i byte degli allegati.

Collegare EmDash Exporter

In WordPress apri Tools → EmDash Migration e genera una chiave di migrazione. Incolla la chiave nella pagina di importazione di EmDash.

Puoi anche inserire l’URL del sito WordPress. Quando l’exporter viene rilevato, autorizza EmDash tramite la schermata delle password per le applicazioni di WordPress. Sui siti di sviluppo locali in HTTP, inserisci manualmente il nome utente WordPress e la password dell’applicazione, perché il callback di autorizzazione richiede HTTPS.

Importare tramite l’amministrazione

Comportamento della conversione

Stati

L’importatore associa gli stati di WordPress come segue:

Le date pianificate e le regole di visibilità di WordPress non vengono ricostruite a partire da questi stati. Esamina ogni bozza importata prima della pubblicazione.

Rich text e blocchi riutilizzabili

Il markup di Gutenberg viene convertito in Portable Text. L’HTML classico viene elaborato dallo stesso convertitore. Ispeziona nel sito EmDash renderizzato i blocchi complessi, gli incorporamenti, gli shortcode, il markup dei page builder e i blocchi definiti dai plugin.

Le voci WXR wp_block vengono importate come sections. Non vengono importate in una normale collezione di contenuti.

Collezioni e campi

Le associazioni predefinite dei tipi di contenuto includono post verso posts e page verso pages. I tipi di contenuto personalizzati usano uno slug di collezione normalizzato. Il passaggio di preparazione aggiunge i campi standard di titolo, contenuto Portable Text, estratto e immagine in evidenza richiesti dall’analisi.

I campi esistenti con tipi compatibili vengono riutilizzati. Una mancata corrispondenza di tipo blocca l’associazione di quella collezione; l’importatore non forza la conversione di un campo esistente in un altro tipo.

Campi personalizzati e dati SEO

L’analisi WXR segnala le chiavi post-meta non interne e suggerisce nomi e tipi di campo, ma l’importazione WXR nel database scrive i campi standard importati anziché copiare ogni chiave meta arbitraria. Considera l’analisi come una lista di controllo dei campi che potrebbero richiedere una conversione separata.

Il percorso di EmDash Exporter può copiare i metadati personalizzati e i valori di Advanced Custom Fields (ACF) quando la collezione di destinazione ha campi corrispondenti. Può anche creare e popolare i campi supportati di immagine in evidenza e di SEO di Yoast o Rank Math quando i relativi interruttori di importazione sono attivi. Esamina i valori PHP serializzati, i repeater, i contenuti flessibili e le strutture specifiche dei plugin anziché presumere che la loro rappresentazione in WordPress corrisponda a un tipo di campo di EmDash.

Autori e byline

Un autore WordPress associato diventa il proprietario della voce. I crediti mostrati usano le byline. Se non esiste alcuna associazione utente, EmDash crea o riutilizza una byline ospite basata sull’identità dell’autore in WordPress.

Tassonomie

Le categorie e i tag vengono importati nelle definizioni di tassonomia EmDash corrispondenti. Il percorso dell’exporter può creare definizioni per le tassonomie personalizzate. Una tassonomia personalizzata WXR senza una definizione EmDash corrispondente viene segnalata come mancante e le sue assegnazioni vengono saltate.

Media

La deduplicazione dei media confronta un hash SHA-1 dei byte scaricati. Una riga di media esistente con lo stesso hash viene riutilizzata. I nomi dei file e gli ID di WordPress non sono la chiave di deduplicazione.

Il sito di origine deve restare raggiungibile mentre EmDash scarica gli allegati. I reindirizzamenti dall’URL di un allegato vengono convalidati prima di essere seguiti.

Ritentare un’importazione parziale

L’importazione dall’amministrazione è progettata per saltare le voci esistenti, ma il confine del suo criterio di corrispondenza è importante:

• I contenuti esistenti vengono abbinati per collezione, slug e impostazioni locali, non per ID di WordPress.
• Se uno slug di origine è cambiato tra un tentativo e l’altro, ispeziona entrambe le voci e risolvi manualmente il duplicato.
• Rieseguire il passaggio dei media riutilizza, tramite l’hash del contenuto, i file già memorizzati e identici byte per byte.
• Il flusso dell’exporter invia blocchi di dimensione limitata. Riavviare il flusso nel browser riesegue le pagine di contenuto e ricostruisce le mappe delle relazioni a partire dalle voci saltate.

L’amministrazione non conserva un file di ripresa WXR. Il flag --resume di emdash import wordpress appartiene a un flusso CLI separato che scrive su disco file JSON convertiti; non riprende un’importazione nel database dall’amministrazione.

Verificare prima del passaggio definitivo

Controlla il sito importato rispetto all’originale:

• Conta le voci per tipo di contenuto e stato.
• Apri contenuti rappresentativi di Gutenberg, dell’editor classico, degli shortcode e dei page builder.
• Conferma che le immagini in evidenza e i media inline vengano risolti da URL di EmDash.
• Controlla autori, byline, categorie, tag, tassonomie personalizzate e traduzioni.
• Testa menu, commenti, identità del sito e campi SEO quando sono stati importati tramite l’exporter.
• Scansiona i vecchi URL pubblici e prepara reindirizzamenti per ogni route modificata.
• Verifica che le bozze restino inaccessibili ai visitatori non autenticati.

Conserva il backup e la distribuzione di WordPress finché il nuovo sito non ha funzionato con successo in produzione e il rollback non è più necessario.

Risoluzione dei problemi

Impossibile analizzare il file XML

Esporta di nuovo il file da Tools → Export e conferma che il download sia stato completato. Non modificare l’XML con uno strumento che cambia la codifica.

Una collezione è contrassegnata come incompatibile

Un campo esistente ha lo stesso slug ma un tipo diverso. Cambia l’associazione del tipo di contenuto oppure riconcilia il campo in Content Types prima di riprovare. Il passaggio di preparazione aggiunge i campi mancanti ma non cambia i tipi dei campi esistenti.

Il download degli URL dei media non riesce

Verifica che l’allegato di origine sia raggiungibile senza una sessione WordPress. I media protetti da autenticazione, i file rimossi e i reindirizzamenti verso indirizzi di rete privata falliscono singolarmente e restano nell’elenco degli errori dei media.

Adattare il tema

Usa getEmDashCollection() per le route di archivio e getEmDashEntry() per una route con slug. entry.id è l’identificatore della route ed è normalmente lo slug; entry.data.id è l’ID di contenuto memorizzato usato dagli helper delle relazioni.

La route seguente renderizza un articolo importato:

---
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>

Leggi Portare un tema WordPress per la mappatura di route e componenti. Leggi Importazione di contenuti per i contratti degli endpoint e i confini esatti dei nuovi tentativi.