Migrar do WordPress

Use o administrador do EmDash para analisar um site WordPress, preparar coleções compatíveis, importar conteúdo, copiar mídia e reescrever URLs. Mantenha o site WordPress disponível até que o site importado passe na verificação.

Antes de começar

Prepare os seguintes itens:

• Um backup do banco de dados do WordPress e de wp-content/uploads.
• Um site EmDash com o armazenamento configurado, se você planeja copiar mídia.
• Uma conta de administrador do EmDash. A importação do WordPress exige a permissão import:execute.
• Uma exportação completa do WordPress eXtended RSS (WXR) ou o plugin EmDash Exporter instalado no site WordPress.

Anote a estrutura atual de permalinks, a origem canônica, os redirecionamentos, os menus, os tipos de post ativos, as taxonomias e quaisquer campos pertencentes a plugins que o novo site precise preservar.

Escolher um método de importação

Informar a URL de um site sem o exporter apenas consulta a API REST pública do WordPress. A consulta consegue detectar o WordPress e contar posts, páginas e mídia públicos, mas não consegue fazer uma importação REST direta.

Exportar um arquivo WXR

No WordPress, abra Tools → Export, selecione All content e baixe o arquivo de exportação XML. Um arquivo WXR aponta para a mídia na origem do WordPress; ele não contém os bytes dos anexos.

Conectar o EmDash Exporter

Verifique a versão do exporter na tela Plugins do WordPress. Comentários, menus, o logotipo e o favicon exigem o exporter 1.2.0 ou posterior. Com uma versão anterior, a importação é concluída sem eles e não os informa como ausentes.

Com o exporter 1.2.0 ou posterior, abra Tools → EmDash Migration no WordPress e gere uma chave de migração. Cole a chave na página de importação do EmDash.

Com qualquer versão do exporter, você também pode informar a URL do site WordPress. Quando o exporter for detectado, autorize o EmDash pela tela de senhas de aplicativo do WordPress. Em sites de desenvolvimento locais com HTTP, informe manualmente o nome de usuário do WordPress e a senha de aplicativo, porque o callback de autorização exige HTTPS.

Importar pelo administrador

Comportamento da conversão

Status

O importador mapeia os status do WordPress da seguinte forma:

As datas agendadas e as regras de visibilidade do WordPress não são reconstruídas a partir desses status. Revise cada rascunho importado antes da publicação.

Rich text e blocos reutilizáveis

A marcação do Gutenberg é convertida em Portable Text. O HTML clássico é processado pelo mesmo conversor. Inspecione, no site EmDash renderizado, os blocos complexos, os embeds, os shortcodes, a marcação de page builders e os blocos definidos por plugins.

Os blocos que o WordPress renderiza no servidor, como Latest Posts ou blocos de plugins, não têm marcação salva. Eles são importados como blocos HTML que contêm o comentário de bloco original, por exemplo <!-- wp:latest-posts {"postsToShow":3} /-->. Esses blocos não mostram conteúdo no site. Abra a aba HTML do bloco no editor para ver o que ele era e depois reconstrua-o ou remova-o.

As entradas wp_block do WXR são importadas como seções. Elas não são importadas para uma coleção de conteúdo comum.

Coleções e campos

Os mapeamentos padrão de tipos de post incluem post para posts e page para pages. Tipos de post personalizados usam um slug de coleção higienizado. A etapa de preparação adiciona os campos padrão de título, conteúdo em Portable Text, resumo e imagem destacada que a análise exige.

Os campos existentes com tipos compatíveis são reutilizados. Uma incompatibilidade de tipo bloqueia o mapeamento dessa coleção; o importador não converte um campo existente para outro tipo.

Campos personalizados e dados de SEO

A análise do WXR relata as chaves de metadados de post que não são internas e sugere nomes e tipos de campo, mas a importação do WXR para o banco de dados grava os campos importados padrão, em vez de copiar todas as chaves de metadados arbitrárias. Trate a análise como uma lista de verificação dos campos que podem exigir uma conversão separada.

O caminho do EmDash Exporter pode copiar metadados personalizados e valores do Advanced Custom Fields (ACF) quando a coleção de destino tem campos correspondentes. Para um grupo de campos do ACF com uma regra de localização “Post Type is equal to”, a análise sugere um campo para cada campo do ACF no grupo: campos de texto, número e verdadeiro/falso recebem tipos correspondentes, e campos select, checkbox, repeater, group, relationship e outros que podem conter uma lista ou um objeto tornam-se campos JSON. Os campos de grupos atribuídos por outras regras de localização são sugeridos apenas a partir das chaves de meta que o exporter informa. Uma coleção cujos campos uma importação anterior criou a partir das chaves de meta os mantém, então seus repeaters chegam como um campo por linha e subcampo. Os valores JSON mantêm a forma do WordPress: campos relationship, post object, user e taxonomy apontam para posts, usuários e termos do WordPress pelos IDs do WordPress, e não para entradas do EmDash, e campos de imagem, arquivo e galeria apontam para os arquivos de mídia do WordPress, e não para mídia importada do EmDash. Subcampos de grupos do ACF armazenados em mais de um post também podem aparecer como campos separados ao lado do campo JSON do grupo; mantenha a cópia que seus templates usam. Revise esses valores antes de usá-los nos templates.

O caminho do exporter também pode criar e preencher os campos compatíveis de imagem destacada e de SEO do Yoast ou do Rank Math quando as respectivas opções de importação estão ativadas.

Autores e bylines

Um autor do WordPress associado torna-se o proprietário da entrada. Os créditos de autoria usam bylines. Se não houver associação de usuário, o EmDash cria ou reutiliza uma byline de convidado com base na identidade do autor no WordPress.

Taxonomias

Categorias e tags são importadas para as definições de taxonomia correspondentes do EmDash. O caminho do exporter pode criar definições para taxonomias personalizadas. Uma taxonomia personalizada do WXR sem uma definição correspondente no EmDash é relatada como ausente, e suas atribuições são ignoradas.

Mídia

A deduplicação de mídia compara um hash SHA-1 dos bytes baixados. Uma linha de mídia existente com o mesmo hash é reutilizada. Nomes de arquivo e IDs do WordPress não são a chave de deduplicação.

O site de origem precisa continuar acessível enquanto o EmDash baixa os anexos. Os redirecionamentos a partir da URL de um anexo são validados antes de serem seguidos.

Tentar novamente uma importação parcial

A importação pelo administrador foi projetada para ignorar entradas existentes, mas o limite de correspondência é importante:

• O conteúdo existente é correspondido por coleção, slug e localidade, não pelo ID do WordPress.
• Se um slug de origem mudou entre as tentativas, inspecione as duas entradas e resolva a duplicata manualmente.
• Executar a etapa de mídia novamente reutiliza os arquivos já armazenados e idênticos byte a byte, com base no hash do conteúdo.
• O fluxo do exporter envia blocos de tamanho limitado. Reiniciar o fluxo no navegador executa novamente as páginas de conteúdo e reconstrói os mapas de relacionamento a partir das entradas ignoradas.

O administrador não mantém um arquivo de retomada do WXR. A flag --resume de emdash import wordpress pertence a um fluxo de CLI separado, que grava arquivos JSON convertidos em disco; ela não retoma uma importação para o banco de dados feita pelo administrador.

Verificar antes da virada

Compare o site importado com a origem:

• Conte as entradas por tipo de post e status.
• Abra conteúdos representativos do Gutenberg, do Editor Clássico, de shortcodes e de page builders.
• Confirme que as imagens destacadas e a mídia embutida são resolvidas a partir de URLs do EmDash.
• Verifique autores, bylines, categorias, tags, taxonomias personalizadas e traduções.
• Teste menus, comentários, identidade do site e campos de SEO quando forem importados pelo exporter.
• Rastreie as URLs públicas antigas e prepare redirecionamentos para cada rota alterada.
• Verifique se os rascunhos continuam inacessíveis para visitantes sem login.

Mantenha o backup e a implantação do WordPress até que o novo site tenha funcionado com sucesso em produção e o rollback não seja mais necessário.

Solução de problemas

Não é possível analisar o arquivo XML

Exporte o arquivo novamente em Tools → Export e confirme que o download foi concluído. Não edite o XML com uma ferramenta que altere a codificação.

Uma coleção é marcada como incompatível

Um campo existente tem o mesmo slug, mas um tipo diferente. Altere a associação do tipo de post ou concilie o campo em Content Types antes de tentar novamente. A etapa de preparação adiciona os campos que faltam, mas não altera os tipos dos campos existentes.

A proteção contra bots bloqueia o exporter

A proteção contra bots da Cloudflare pode responder às solicitações do EmDash com uma página de desafio em vez da API do exporter. O EmDash informa então que a proteção contra bots bloqueou a conexão. Deixe as solicitações do exporter passarem durante a migração:

• Com o Super Bot Fight Mode ou outros recursos de WAF da Cloudflare, adicione uma regra personalizada com a ação Skip e posicione-a acima de qualquer regra que emita desafios. Selecione All Super Bot Fight Mode rules e, se a zona usa o modo I’m Under Attack, também Security Level. Esta expressão corresponde à API do exporter com e sem links permanentes amigáveis, inclusive em instalações do WordPress em um subdiretório, e aos arquivos de mídia que o EmDash baixa:

  (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/")

• O Bot Fight Mode no plano Free da Cloudflare não pode ser ignorado por regras. Desative-o durante a migração e ative-o novamente depois.

O download das URLs de mídia falha

Verifique se o anexo de origem está acessível sem uma sessão do WordPress. Mídia protegida por autenticação, arquivos removidos e redirecionamentos para endereços de rede privada falham individualmente e permanecem na lista de erros de mídia.

Adaptar o tema

Use getEmDashCollection() para as rotas de arquivo e getEmDashEntry() para uma rota com slug. entry.id é o identificador da rota e normalmente é o slug; entry.data.id é o ID de conteúdo armazenado que os helpers de relacionamento usam.

A rota a seguir renderiza um post importado:

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

Leia Portar um tema WordPress para o mapeamento de rotas e componentes. Leia Importação de Conteúdo para os contratos dos endpoints e os limites exatos das novas tentativas.