Migrar desde WordPress

Usa el administrador de EmDash para analizar un sitio de WordPress, preparar colecciones compatibles, importar contenido, copiar medios y reescribir URL. Mantén disponible el sitio de WordPress hasta que el sitio importado haya superado la verificación.

Antes de comenzar

Prepara lo siguiente:

• Una copia de seguridad de la base de datos de WordPress y de wp-content/uploads.
• Un sitio de EmDash con el almacenamiento configurado si planeas copiar medios.
• Una cuenta de administrador de EmDash. La importación de WordPress requiere el permiso import:execute.
• Una exportación completa de WordPress eXtended RSS (WXR) o el plugin EmDash Exporter instalado en el sitio de WordPress.

Anota la estructura actual de enlaces permanentes, el origen canónico, las redirecciones, los menús, los tipos de contenido activos, las taxonomías y cualquier campo propiedad de un plugin que el nuevo sitio deba conservar.

Elegir un método de importación

Si introduces la URL de un sitio sin el exportador, solo se sondea la API REST pública de WordPress. El sondeo puede detectar WordPress y contar las entradas, páginas y medios públicos, pero no puede realizar una importación directa por REST.

Exportar un archivo WXR

En WordPress, abre Tools → Export, selecciona All content y descarga el archivo de exportación XML. Un archivo WXR apunta a los medios del origen de WordPress; no contiene los bytes de los adjuntos.

Conectar el EmDash Exporter

Comprueba la versión del exportador en la pantalla Plugins de WordPress. Los comentarios, los menús, el logotipo y el favicon requieren el exportador 1.2.0 o posterior. Con una versión anterior, la importación se completa sin ellos y no los notifica como ausentes.

Con el exportador 1.2.0 o posterior, abre Tools → EmDash Migration en WordPress y genera una clave de migración. Pega la clave en la página de importación de EmDash.

Con cualquier versión del exportador, también puedes introducir la URL del sitio de WordPress. Cuando se detecta el exportador, autoriza EmDash mediante la pantalla de contraseñas de aplicación de WordPress. En sitios de desarrollo locales con HTTP, introduce manualmente el nombre de usuario de WordPress y la contraseña de aplicación, porque el callback de autorización requiere HTTPS.

Importar a través del administrador

Comportamiento de la conversión

Estados

El importador asigna los estados de WordPress de la siguiente manera:

Las fechas programadas y las reglas de visibilidad de WordPress no se reconstruyen a partir de estos estados. Revisa cada borrador importado antes de publicarlo.

Texto enriquecido y bloques reutilizables

El marcado de Gutenberg se convierte a Portable Text. El HTML clásico lo procesa el mismo conversor. Inspecciona en el sitio de EmDash renderizado los bloques complejos, los embeds, los shortcodes, el marcado de constructores de páginas y los bloques definidos por plugins.

Los bloques que WordPress renderiza en el servidor, como Latest Posts o los bloques de plugins, no tienen marcado guardado. Se importan como bloques HTML que contienen el comentario de bloque original, por ejemplo <!-- wp:latest-posts {"postsToShow":3} /-->. Estos bloques no muestran contenido en el sitio. Abre la pestaña HTML del bloque en el editor para ver qué era y luego reconstrúyelo o elimínalo.

Las entradas wp_block de WXR se importan como secciones. No se importan a una colección de contenido normal.

Colecciones y campos

Las asignaciones predeterminadas de tipos de contenido incluyen post a posts y page a pages. Los tipos de contenido personalizados usan un slug de colección saneado. El paso de preparación añade los campos estándar de título, contenido en Portable Text, extracto e imagen destacada que requiere el análisis.

Los campos existentes con tipos compatibles se reutilizan. Una discrepancia de tipo bloquea la asignación de esa colección; el importador no convierte un campo existente a otro tipo.

Campos personalizados y datos SEO

El análisis de WXR informa de las claves de metadatos de entrada que no son internas y sugiere nombres y tipos de campo, pero la importación de WXR a la base de datos escribe los campos importados estándar en lugar de copiar cada clave de metadatos arbitraria. Trata el análisis como una lista de comprobación de los campos que pueden necesitar una conversión aparte.

La ruta del EmDash Exporter puede copiar metadatos personalizados y valores de Advanced Custom Fields (ACF) cuando la colección de destino tiene campos equivalentes. Para un grupo de campos de ACF con una regla de ubicación «Post Type is equal to», el análisis sugiere un campo por cada campo de ACF del grupo: los campos de texto, número y verdadero/falso reciben tipos equivalentes, y los campos select, checkbox, repeater, group, relationship y otros que pueden contener una lista o un objeto pasan a ser campos JSON. Los campos de los grupos asignados mediante otras reglas de ubicación se sugieren solo a partir de las claves meta que informa el exportador. Una colección cuyos campos creó una importación anterior a partir de las claves meta los conserva, de modo que sus repeaters llegan como un campo por fila y subcampo. Los valores JSON conservan su forma de WordPress: los campos relationship, post object, user y taxonomy apuntan a entradas, usuarios y términos de WordPress por sus ID de WordPress, y no a entradas de EmDash, y los campos de imagen, archivo y galería apuntan a los archivos de medios de WordPress, y no a medios de EmDash importados. Los subcampos de un grupo de ACF almacenados en más de una entrada también pueden aparecer como campos independientes junto al campo JSON del grupo; conserva la copia que usen tus plantillas. Revisa estos valores antes de usarlos en plantillas.

La ruta del exportador también puede crear y rellenar los campos compatibles de imagen destacada y de SEO de Yoast o Rank Math cuando están activados sus interruptores de importación.

Autores y bylines

Un autor de WordPress asignado se convierte en el propietario de la entrada. Los créditos de presentación usan bylines. Si no existe una asignación de usuario, EmDash crea o reutiliza una byline de invitado basada en la identidad del autor de WordPress.

Taxonomías

Las categorías y las etiquetas se importan a las definiciones de taxonomía de EmDash que coincidan. La ruta del exportador puede crear definiciones para taxonomías personalizadas. Una taxonomía personalizada de WXR sin una definición equivalente en EmDash se notifica como ausente y se omiten sus asignaciones.

Medios

La deduplicación de medios compara un hash SHA-1 de los bytes descargados. Se reutiliza una fila de medios existente con el mismo hash. Los nombres de archivo y los ID de WordPress no son la clave de deduplicación.

El sitio de origen debe seguir siendo accesible mientras EmDash descarga los adjuntos. Las redirecciones desde la URL de un adjunto se validan antes de seguirlas.

Reintentar una importación parcial

La importación desde el administrador está diseñada para omitir las entradas existentes, pero importa saber cómo las empareja:

• El contenido existente se empareja por colección, slug y configuración regional, no por el ID de WordPress.
• Si un slug de origen cambió entre intentos, inspecciona ambas entradas y resuelve el duplicado manualmente.
• Al volver a ejecutar el paso de medios se reutilizan los archivos ya almacenados e idénticos byte a byte, según el hash de su contenido.
• El flujo del exportador envía fragmentos acotados. Reiniciar el flujo del navegador vuelve a ejecutar las páginas de contenido y reconstruye los mapas de relaciones a partir de las entradas omitidas.

El administrador no conserva un archivo de reanudación de WXR. La opción --resume de emdash import wordpress pertenece a un flujo de CLI independiente que escribe en disco archivos JSON convertidos; no reanuda una importación a la base de datos desde el administrador.

Verificar antes del cambio definitivo

Comprueba el sitio importado frente al de origen:

• Cuenta las entradas por tipo de contenido y estado.
• Abre contenido representativo de Gutenberg, del Editor clásico, de shortcodes y de constructores de páginas.
• Confirma que las imágenes destacadas y los medios incrustados se resuelven desde URL de EmDash.
• Revisa autores, bylines, categorías, etiquetas, taxonomías personalizadas y traducciones.
• Prueba los menús, los comentarios, la identidad del sitio y los campos SEO cuando se importaron con el exportador.
• Rastrea las URL públicas antiguas y prepara redirecciones para cada ruta que haya cambiado.
• Verifica que los borradores sigan siendo inaccesibles para los visitantes que no han iniciado sesión.

Conserva la copia de seguridad y el despliegue de WordPress hasta que el nuevo sitio haya funcionado correctamente en producción y ya no se necesite revertir.

Solución de problemas

No se puede analizar el archivo XML

Vuelve a exportar el archivo desde Tools → Export y confirma que la descarga se completó. No edites el XML con una herramienta que cambie su codificación.

Una colección aparece marcada como incompatible

Un campo existente tiene el mismo slug pero un tipo distinto. Cambia la asignación del tipo de contenido o concilia el campo en Content Types antes de reintentar. El paso de preparación añade los campos que faltan, pero no cambia los tipos de los campos existentes.

La protección contra bots bloquea el exportador

La protección contra bots de Cloudflare puede responder a las solicitudes de EmDash con una página de desafío en lugar de la API del exportador. EmDash informa entonces de que la protección contra bots bloqueó la conexión. Deja pasar las solicitudes del exportador mientras dure la migración:

• Con Super Bot Fight Mode u otras funciones de WAF de Cloudflare, añade una regla personalizada con la acción Skip y colócala por encima de cualquier regla que emita desafíos. Selecciona All Super Bot Fight Mode rules y, si la zona usa el modo I’m Under Attack, también Security Level. Esta expresión coincide con la API del exportador con y sin enlaces permanentes amigables, incluidas las instalaciones de WordPress en un subdirectorio, y con los archivos de medios que descarga 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 en el plan Free de Cloudflare no se puede omitir con reglas. Desactívalo durante la migración y vuelve a activarlo después.

Falla la descarga de las URL de medios

Comprueba que el adjunto de origen sea accesible sin una sesión de WordPress. Los medios protegidos por autenticación, los archivos eliminados y las redirecciones a direcciones de redes privadas fallan de forma individual y permanecen en la lista de errores de medios.

Adaptar el tema

Usa getEmDashCollection() para las rutas de archivo y getEmDashEntry() para una ruta con slug. entry.id es el identificador de la ruta y normalmente es el slug; entry.data.id es el ID de contenido almacenado que usan los helpers de relaciones.

La siguiente ruta renderiza una entrada importada:

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

Lee Portar un tema de WordPress para ver la correspondencia de rutas y componentes. Lee Importación de contenido para conocer los contratos de los endpoints y los límites exactos de los reintentos.