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 quanto segue:

• Un backup del database di WordPress e di wp-content/uploads.
• Un sito EmDash con lo storage configurato, 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 ed eventuali campi gestiti da plugin che il nuovo sito deve mantenere.

Scegliere un metodo di importazione

Inserire l’URL di un sito senza l’exporter si limita a interrogare la REST API pubblica di WordPress. La verifica può rilevare WordPress e contare articoli, pagine e 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

Controlla la versione dell’exporter nella schermata Plugins di WordPress. Commenti, menu, logo e favicon richiedono exporter 1.2.0 o successivo. Con una versione precedente, l’importazione si completa senza di essi e non li segnala come mancanti.

Con exporter 1.2.0 o successivo, apri Tools → EmDash Migration in WordPress e genera una chiave di migrazione. Incolla la chiave nella pagina di importazione di EmDash.

Con qualsiasi versione dell’exporter 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 per le applicazioni, perché il callback di autorizzazione richiede HTTPS.

Importare tramite l’amministrazione

Comportamento della conversione

Stati

L’importatore associa gli stati di WordPress nel modo seguente:

Le date pianificate e le regole di visibilità di WordPress non vengono ricostruite a partire da questi stati. Controlla 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. Controlla nel sito EmDash renderizzato i blocchi complessi, gli embed, gli shortcode, il markup dei page builder e i blocchi definiti dai plugin.

I blocchi che WordPress renderizza sul server, come Latest Posts o i blocchi dei plugin, non hanno markup salvato. Vengono importati come blocchi HTML che contengono il commento di blocco originale, ad esempio <!-- wp:latest-posts {"postsToShow":3} /-->. Questi blocchi non mostrano alcun contenuto sul sito. Apri la scheda HTML del blocco nell’editor per vedere cos’era, poi ricostruiscilo o rimuovilo.

Le voci WXR wp_block vengono importate come sezioni. 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 ripulito. Il passaggio di preparazione aggiunge i campi standard per titolo, contenuto Portable Text, estratto e immagine in evidenza richiesti dall’analisi.

I campi esistenti con tipi compatibili vengono riutilizzati. Una discrepanza di tipo blocca l’associazione di quella collezione; l’importatore non converte un campo esistente in un altro tipo.

Campi personalizzati e dati SEO

L’analisi WXR segnala le chiavi di metadati degli articoli non interne e suggerisce nomi e tipi di campo, ma l’importazione WXR nel database scrive i campi importati standard anziché copiare ogni chiave di metadati arbitraria. Considera l’analisi come una checklist 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. Per un gruppo di campi ACF con una regola di posizione «Post Type is equal to», l’analisi suggerisce un campo per ogni campo ACF del gruppo: i campi testo, numero e vero/falso ottengono tipi corrispondenti, mentre i campi select, checkbox, repeater, group, relationship e altri che possono contenere un elenco o un oggetto diventano campi JSON. I campi dei gruppi assegnati con altre regole di posizione vengono suggeriti solo a partire dalle chiavi meta segnalate dall’exporter. Una collezione i cui campi sono stati creati da un’importazione precedente a partire dalle chiavi meta li mantiene, quindi i suoi repeater arrivano come un campo per riga e sottocampo. I valori JSON mantengono la forma di WordPress: i campi relationship, post object, user e taxonomy puntano a post, utenti e termini di WordPress tramite i loro ID WordPress anziché a voci di EmDash, e i campi immagine, file e galleria puntano ai file multimediali di WordPress anziché ai media EmDash importati. I sottocampi di gruppi ACF salvati su più di un post possono inoltre comparire come campi separati accanto al campo JSON del gruppo; mantieni la copia usata dai tuoi template. Controlla questi valori prima di usarli nei template.

Il percorso dell’exporter può anche creare e popolare i campi supportati per l’immagine in evidenza e per la SEO di Yoast o Rank Math quando i relativi interruttori di importazione sono attivi.

Autori e byline

Un autore WordPress associato diventa il proprietario della voce. I crediti di presentazione usano le byline. Se non esiste alcuna associazione a un utente, EmDash crea o riutilizza una byline ospite basata sull’identità dell’autore 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 rimanere 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 è pensata per saltare le voci esistenti, ma è importante conoscere il suo criterio di corrispondenza:

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

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

Verificare prima del passaggio definitivo

Confronta il sito importato con quello di origine:

• 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 incorporati 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.
• Esegui la scansione dei vecchi URL pubblici e prepara i reindirizzamenti per ogni route modificata.
• Verifica che le bozze restino inaccessibili ai visitatori non autenticati.

Conserva il backup e il deployment di WordPress finché il nuovo sito non ha funzionato correttamente 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.

La protezione dai bot blocca l’exporter

La protezione dai bot di Cloudflare può rispondere alle richieste di EmDash con una pagina di verifica anziché con l’API dell’exporter. EmDash segnala allora che la protezione dai bot ha bloccato la connessione. Lascia passare le richieste dell’exporter per tutta la durata della migrazione:

• Con Super Bot Fight Mode o altre funzionalità WAF di Cloudflare, aggiungi una regola personalizzata con l’azione Skip e posizionala sopra qualsiasi regola che emette verifiche. Seleziona All Super Bot Fight Mode rules e, se la zona usa la modalità I’m Under Attack, anche Security Level. Questa espressione corrisponde all’API dell’exporter con e senza permalink leggibili, comprese le installazioni WordPress in una sottodirectory, e ai file multimediali scaricati da EmDash:

  (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 sul piano Free di Cloudflare non può essere saltato con le regole. Disattivalo durante la migrazione e riattivalo dopo.

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 e di norma è lo slug; entry.data.id è l’ID del 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.