Usa el administrador de EmDash para analizar un sitio de WordPress, preparar colecciones compatibles, importar contenido, copiar medios y reescribir URL. Mantén el sitio de WordPress disponible hasta que el sitio importado haya superado la verificación.
Antes de comenzar
Prepara los siguientes elementos:
- Una copia de seguridad de la base de datos de WordPress y de
wp-content/uploads. - Un sitio EmDash con el almacenamiento configurado si piensas 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
| Método | Úsalo cuando | Datos incluidos |
|---|---|---|
| Carga de WXR | Puedes exportar desde Tools → Export | Los datos representados en la exportación, incluidos entradas, páginas, tipos de contenido personalizados, términos de taxonomía, bloques reutilizables, autores y URL de adjuntos |
| EmDash Exporter | Controlas el sitio de WordPress y puedes instalar el exporter | Contenido autenticado, además de comentarios, menús, ajustes del sitio, campos SEO, taxonomías y metadatos de medios compatibles |
Introducir la URL de un sitio sin el exporter solo 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 REST directa.
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
En WordPress, abre Tools → EmDash Migration y genera una clave de migración. Pega la clave en la página de importación de EmDash.
También puedes introducir la URL del sitio de WordPress. Cuando se detecte el exporter, autoriza a EmDash mediante la pantalla de contraseñas de aplicación de WordPress. En los sitios de desarrollo locales con HTTP, introduce manualmente el nombre de usuario de WordPress y la contraseña de aplicación, porque la devolución de llamada de autorización requiere HTTPS.
Importar a través del administrador
-
Abre Import WordPress en la barra lateral de EmDash, o visita
/_emdash/admin/import/wordpress. -
Sube el archivo WXR, pega la clave de migración del exporter o introduce la URL de WordPress.
-
Revisa el análisis. Para cada tipo de contenido de WordPress, confirma la colección de destino, los campos obligatorios y la compatibilidad con los campos existentes.
-
Asigna los autores de WordPress a usuarios de EmDash. Un autor de origen sin asignar puede representarse con un byline de invitado, de modo que el crédito mostrado no depende de conceder un inicio de sesión de EmDash.
-
En una importación con exporter, elige si importar menús, título y eslogan del sitio, logotipo y favicon, y los valores SEO compatibles. Estos interruptores no forman parte de la ruta WXR.
-
Inicia la importación. EmDash crea las colecciones y los campos compatibles que falten antes de crear las entradas.
-
Si se encontraron adjuntos, ejecuta el paso de medios. EmDash descarga los bytes de origen, los almacena mediante el adaptador de almacenamiento configurado y reescribe las URL de contenido coincidentes.
Comportamiento de la conversión
Estados
El importador asigna los estados de WordPress de la siguiente manera:
| WordPress | EmDash |
|---|---|
publish | published |
draft | draft |
pending | draft |
private | draft |
future, trash o un estado desconocido | draft |
Las fechas programadas y las reglas de visibilidad de WordPress no se reconstruyen a partir de estos estados. Revisa todos los borradores importados antes de publicarlos.
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 EmDash renderizado los bloques complejos, las incrustaciones, los shortcodes, el marcado de constructores de páginas y los bloques definidos por plugins.
Las entradas wp_block de WXR se importan como sections. No se importan a una colección de contenido ordinaria.
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 necesita 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 a la fuerza un campo existente a otro tipo.
Campos personalizados y datos SEO
El análisis de WXR informa de las claves de post-meta no internas y sugiere nombres y tipos de campo, pero la importación a la base de datos desde WXR escribe los campos estándar importados en lugar de copiar cada clave meta arbitraria. Trata el análisis como una lista de comprobación de campos que pueden necesitar una conversión aparte.
La ruta del EmDash Exporter puede copiar los metadatos personalizados y los valores de Advanced Custom Fields (ACF) cuando la colección de destino tiene campos coincidentes. También puede crear y rellenar los campos compatibles de imagen destacada y de SEO de Yoast o Rank Math cuando sus interruptores de importación están activados. Revisa los valores PHP serializados, los repetidores, el contenido flexible y las estructuras específicas de plugins en lugar de suponer que su representación en WordPress coincide con un tipo de campo de EmDash.
Autores y bylines
Un autor de WordPress asignado pasa a ser el propietario de la entrada. Los créditos mostrados usan bylines. Si no existe una asignación de usuario, EmDash crea o reutiliza un byline de invitado basado en la identidad del autor en WordPress.
Taxonomías
Las categorías y las etiquetas se importan a las definiciones de taxonomía de EmDash correspondientes. La ruta del exporter puede crear definiciones para taxonomías personalizadas. Una taxonomía personalizada de WXR sin una definición coincidente en EmDash se informa como ausente y sus asignaciones se omiten.
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 del administrador está diseñada para omitir las entradas existentes, pero el límite de su coincidencia es importante:
- El contenido existente se empareja por colección, slug y configuración regional, no por ID de WordPress.
- Si un slug de origen cambió entre intentos, inspecciona ambas entradas y resuelve el duplicado manualmente.
- Volver a ejecutar el paso de medios reutiliza por su hash de contenido los archivos ya almacenados e idénticos byte a byte.
- El flujo del exporter 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 trabajo 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 original:
- 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 en línea 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 exporter.
- 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 sin sesión iniciada.
Conserva la copia de seguridad y el despliegue de WordPress hasta que el nuevo sitio haya funcionado correctamente en producción y ya no sea necesaria una reversión.
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.
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 red privadas fallan individualmente y permanecen en la lista de errores de medios.
Adaptar el tema
Usa getEmDashCollection() para las rutas de archivo y getEmDashEntry() para una ruta de 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.