Como Migrar um Site com WP-CLI

Se você está gerenciando um site WordPress grande e precisa movê-lo para um novo servidor, o WP-CLI oferece um caminho mais rápido e scriptável.

Ele não causará timeouts de PHP em bancos de dados grandes. Além disso, você terá um processo que pode repetir ou automatizar em vários sites.

Neste tutorial, mostrarei como migrar um site WordPress usando WP-CLI. Ao final, seu site estará rodando no novo servidor, e você terá confirmado que ele está funcionando antes que um único visitante acesse o novo servidor.

Aqui estão os principais pontos:

• A migração com WP-CLI é mais rápida do que a migração baseada em plugins para sites grandes, mas requer acesso SSH em ambos os servidores e o WP-CLI instalado em cada um.
• O flag --precise em wp search-replace é o comando mais importante neste tutorial. Sem ele, dados serializados corrompem silenciosamente, e configurações de temas, widgets e opções de plugins são redefinidos sem nenhuma mensagem de erro.
• Copiar o wp-config.php do servidor antigo para o novo traz as credenciais de banco de dados erradas. Você deve atualizar DB_NAME, DB_USER, DB_PASSWORD e DB_HOST no novo servidor antes de importar.
• Nunca altere o DNS antes de verificar se a migração funcionou. A Etapa 7 cobre uma lista de verificação pré-DNS usando wp option get, wp core verify-checksums e uma pré-visualização do arquivo hosts.
• wp duplicator build cria um backup completo do site a partir do terminal antes de você começar. Se algo der errado no meio da migração, a URL de recuperação de desastres do Duplicator restaura o site original sem SSH no servidor antigo.
• Se você está migrando para um novo domínio, inclua --skip-columns=guid no seu comando search-replace. Substituir GUIDs quebra as assinaturas RSS.

Sumário

Quando Usar WP-CLI para Migrar um Site WordPress

WP-CLI não é a ferramenta certa para toda migração. Veja quando faz sentido seguir o caminho da linha de comando (e quando outra abordagem se encaixa melhor).

Use WP-CLI quando:

• Seu site é grande o suficiente para que ferramentas baseadas em navegador atinjam timeouts de PHP ou limites de memória no meio da transferência
• Seu servidor não oferece espaço em disco temporário suficiente para criar um backup completo pelo navegador
• Você está migrando vários sites e deseja um processo repetível e scriptável. wp duplicator build dentro de um script bash lida com backups em lote sem nenhum trabalho manual
• Você deseja controle total sobre cada etapa: o que transfere, o que é substituído e o que é verificado antes das alterações de DNS

Considere um plugin de migração em vez disso quando:

• Você não tem acesso SSH no servidor de origem ou de destino
• Você não se sente confortável com a linha de comando
• Você deseja um processo visual e guiado com indicadores de progresso e rollback integrados

Qual deles você usa depende da sua configuração e preferência.

O Que Você Precisa Antes de Começar

Tenha tudo isso pronto antes de executar um único comando. Esquecer algo no meio da migração (especialmente credenciais de banco de dados ou caminhos de arquivo) é o que leva a um banco de dados meio importado e um site fora do ar em ambos os servidores.

• Acesso SSH a ambos os servidores. Você precisará executar comandos no servidor antigo e no novo servidor em diferentes momentos deste processo.
• WP-CLI instalado em ambos os servidores. Se ainda não estiver instalado, siga o guia oficial de instalação. Você precisará dele no novo servidor para as etapas de verificação na Etapa 7, não apenas no servidor antigo.
• Duplicator Pro instalado e ativo no servidor antigo. Este plugin de backup/migração possui os comandos wp duplicator build, wp duplicator info e wp duplicator cleanup.
• Um novo banco de dados já criado no novo servidor com um usuário que tenha privilégios totais. wp db import não cria o banco de dados para você — se ele não existir, a importação falha.
• Credenciais do banco de dados do seu novo servidor prontas: DB_NAME, DB_USER, DB_PASSWORD e DB_HOST. Você precisará delas na Etapa 4.
• Os caminhos absolutos dos arquivos para ambas as instalações do WordPress. Execute pwd dentro de cada diretório raiz do WordPress e copie a saída para um local conveniente.
• Se você estiver mudando de domínio: seu URL antigo e novo URL prontos para copiar/colar exatamente como aparecem no banco de dados, incluindo o protocolo (https:// vs http://).

Como Migrar um Site WordPress com WP-CLI

Aqui está o que você fará. Cada etapa se baseia diretamente na anterior, então trabalhe nelas em ordem.

• Etapa 1: Execute uma verificação pré-voo e crie um backup completo com wp duplicator info e wp duplicator build
• Etapa 2: Exporte o banco de dados do servidor antigo usando wp db export
• Etapa 3: Transfira os arquivos do WordPress e o banco de dados para o novo servidor usando rsync e scp
• Etapa 4: Atualize o wp-config.php no novo servidor com suas novas credenciais de banco de dados
• Etapa 5: Redefina e importe o banco de dados no novo servidor usando wp db reset e wp db import
• Etapa 6: Execute a busca e substituição para atualizar URLs usando wp search-replace (apenas para mudanças de domínio)
• Etapa 7: Limpe o cache e verifique a migração antes de alterar o DNS
• Etapa 8: Atualize o DNS e publique
• Etapa 9: Limpe o servidor antigo com wp duplicator cleanup

Etapa 1: Fazer Backup do Site Original

Antes de exportar qualquer coisa, você precisa de um ponto de restauração limpo no servidor original. Se algo der errado no meio da migração, você vai querer poder voltar a um site funcionando sem se apressar.

Eu uso o Duplicator para proteção de backup do WordPress. É um plugin de backup e migração usado por mais de 1,5 milhão de profissionais de WordPress e possui comandos WP-CLI integrados.

Isso significa que você pode criar um backup completo do site sem sair do terminal. Para um fluxo de trabalho de linha de comando, isso importa.

Comece verificando se a configuração de backup do Duplicator está funcionando corretamente. Conecte-se via SSH ao servidor antigo, navegue até a raiz do seu WordPress e execute:

wp duplicator info

Quando isso retornar limpo, crie seu backup:

wp duplicator build

Isso cria um backup completo do seu site a partir do terminal.

Se você quiser salvar o backup em um local específico em vez do padrão, use:

wp duplicator build --dir=/path/to/backup/location

Execute wp duplicator build --help para ver todas as flags disponíveis, incluindo --template=<ID> para modelos de backup predefinidos e opções de motor de arquivamento como --phpsqldump, --phpzip e --duparchive.

Se esta migração quebrar algo, o URL de recuperação de desastres do Duplicator pode restaurar seu site mesmo que o WordPress esteja completamente bloqueado no servidor antigo. Essa é sua rede de segurança antes de tocar em qualquer outra coisa.

Etapa 2: Exportar o Banco de Dados do Servidor Antigo

Ainda no servidor antigo, navegue até a raiz do seu WordPress e exporte o banco de dados:

wp db export site-backup.sql

Quando terminar, você verá: Success: Exported to 'site-backup.sql'.

O arquivo é salvo no seu diretório atual. Anote onde ele está, pois você o transferirá na próxima etapa.

Uma coisa a fazer antes de prosseguir. Se o seu arquivo .sql acabar dentro de um diretório acessível pela web, como /public_html ou /htdocs, mova-o ou exclua-o imediatamente após a transferência.

Um arquivo .sql exposto é uma cópia completa do seu banco de dados, incluindo nomes de usuário, senhas com hash e todo o conteúdo do site. Não é um risco teórico.

Se você estiver migrando uma rede WordPress Multisite, anexe --all-tables para capturar dados de toda a rede:

wp db export site-backup.sql --all-tables

Etapa 3: Transferir Arquivos do WordPress e o Banco de Dados para o Novo Servidor

Duas coisas precisam ser movidas para o novo servidor: os arquivos do WordPress e a exportação .sql que você acabou de criar.

Para os arquivos, use rsync. Ele lida bem com transferências grandes, mostra o progresso e retoma de onde parou se a conexão cair:

rsync -avz --progress /path/to/old-wordpress/ user@newserver:/path/to/new-wordpress/

Com a barra, o rsync copia o conteúdo do diretório. Sem ela, o rsync copia o próprio diretório, o que coloca seus arquivos um nível mais profundo do que o esperado no novo servidor.

Execute uma simulação primeiro para verificar o que será transferido antes de confirmar:

rsync -avz --progress --dry-run /path/to/old-wordpress/ user@newserver:/path/to/new-wordpress/

Para o arquivo de banco de dados, use scp:

scp site-backup.sql user@newserver:/path/to/new-wordpress/

Se você preferir comprimir tudo em um único arquivo primeiro, isso também funciona:

tar -czf site_files.tar.gz .
scp site_backup.sql site_files.tar.gz user@newserver:/path/to/new-wordpress/

Em seguida, extraia no novo servidor:

tar -xzf site_files.tar.gz

Essa abordagem funciona bem para sites menores ou hospedagens que lidam com transferências de arquivo único de forma mais confiável do que conexões rsync.

Etapa 4: Atualizar wp-config.php no Novo Servidor

Esta é a etapa que a maioria dos tutoriais de migração WP-CLI pula, e é a razão mais comum pela qual uma migração falha imediatamente após a importação.

Quando você transferiu seus arquivos do WordPress na etapa anterior, o wp-config.php veio com eles. Esse é o arquivo correto, mas ele ainda tem as credenciais do banco de dados do seu servidor antigo. Se você executar a importação agora, o WP-CLI tentará se conectar a um banco de dados que não existe no novo servidor.

Conecte-se via SSH ao novo servidor, navegue até a raiz do seu WordPress e abra o wp-config.php:

nano /path/to/new-wordpress/wp-config.php

Atualize estes quatro valores com os detalhes do banco de dados do seu novo servidor:

• DB_NAME: o nome do banco de dados que você criou no novo servidor
• DB_USER: o nome de usuário do banco de dados
• DB_PASSWORD: a senha do banco de dados
• DB_HOST: geralmente localhost, mas confirme com seu provedor. Alguns provedores gerenciados usam um valor diferente aqui.

Salve e saia. No nano, é Ctrl+O para salvar e Ctrl+X para sair.

Não se esqueça desta etapa. Se as credenciais estiverem erradas, wp db import se conectará ao banco de dados errado ou falhará com “Erro ao estabelecer conexão com o banco de dados”, e nem sempre ficará óbvio que wp-config.php é a causa.

Etapa 5: Resetar e Importar o Banco de Dados no Novo Servidor

Conecte-se via SSH ao novo servidor e navegue até a raiz do seu WordPress. Se você tem uma instalação nova do WordPress no novo servidor, limpe as tabelas padrão antes de importar. Pular esta etapa pode causar conflitos entre as tabelas existentes e as do seu export.

wp db reset --yes

Você verá: Sucesso: Banco de dados redefinido.

O sinalizador --yes pula a solicitação de confirmação. Sem ele, o WP-CLI pedirá para você confirmar antes de descartar todas as tabelas.

Agora importe o banco de dados:

wp db import site-backup.sql

Assim que a importação for confirmada, exclua o arquivo SQL:

rm site-backup.sql

Em seguida, conecte-se via SSH de volta ao servidor antigo e exclua-o lá também.

Isso não é uma tarefa opcional de organização. Um arquivo .sql em um diretório acessível pela web é uma cópia completa do seu banco de dados. Exclua-o de ambos os servidores antes de fazer qualquer outra coisa.

Etapa 6: Executar Search-Replace para Atualizar URLs

Se você for manter o mesmo domínio e apenas mudar de provedor, pule esta etapa e vá direto para a Etapa 7. Seus URLs já estão corretos no banco de dados.

Se você for mudar de domínio, é aqui que a maioria das migrações falha silenciosamente. Não com um erro — mas com configurações de tema que parecem erradas, widgets que desapareceram e opções de plugins que voltaram aos padrões. A causa é quase sempre a mesma: um busca-substitui que não lidou corretamente com dados serializados.

Antes de executar qualquer coisa, faça um teste simulado:

wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables --precise --dry-run

Isso executa a operação completa e mostra uma tabela de quantas substituições seriam feitas por tabela de banco de dados, sem salvar nenhuma alteração. Revise-a.

Procure por tabelas onde você esperaria substituições (wp_options, wp_posts, wp_postmeta) e certifique-se de que as contagens pareçam razoáveis. Zeros inesperados nessas tabelas valem a pena investigar antes de confirmar.

Quando estiver satisfeito, execute sem –dry-run:

wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables --precise

Por que --precise importa: O WordPress armazena alguns dados como PHP serializado. Configurações do personalizador de temas, configurações de widgets, opções de plugins — estes não são armazenados como texto puro. Eles são armazenados como strings PHP estruturadas que incluem contagens de caracteres.

Uma busca-substituição padrão baseada em SQL troca a string do URL, mas não recalcula essas contagens de caracteres. O PHP lê a contagem, encontra uma incompatibilidade e descarta silenciosamente os dados.

Seu tema é redefinido. Seus widgets desaparecem. Nada gera um erro — o site simplesmente parece errado.

A flag --precise força o WP-CLI a usar PHP em vez de SQL. Ele desserializa cada valor, faz a substituição, recalcula a contagem de caracteres e serializa o resultado novamente corretamente. É mais lento em bancos de dados grandes. Use-o mesmo assim.

Uma coisa que o wp search-replace ignora corretamente por padrão: a coluna guid em wp_posts. Não tente forçá-lo a substituir GUIDs.

A documentação do WordPress afirma explicitamente que os GUIDs devem permanecer constantes. Eles identificam posts para leitores de feed, e alterá-los quebra as assinaturas RSS.

Se você estiver migrando uma rede Multisite, adicione a flag –network:

wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables --precise --network

A documentação oficial do WordPress descreve uma ordem diferente: atualize seus URLs em Configurações » Geral no servidor antigo antes de migrar, depois exporte o banco de dados já atualizado e pule a etapa de busca e substituição no novo servidor completamente. Funciona. A abordagem deste tutorial (migrar primeiro, buscar e substituir depois) é mais fácil de verificar porque você pode executar uma simulação antes de confirmar quaisquer alterações de URL.

Etapa 7: Limpar Cache e Verificar Antes de Alterar o DNS

Uma vez que a busca e substituição forem feitas, é tentador ir direto para o DNS. Não faça isso.

Alterar o DNS antes de confirmar que o site está funcionando significa que quaisquer problemas que você encontrar serão problemas ao vivo, visíveis para visitantes reais. Dedique dez minutos aqui e verifique tudo no novo servidor primeiro.

Comece limpando o cache de objetos:

wp cache flush

Em seguida, limpe as regras de reescrita:

wp rewrite flush

Agora verifique se os URLs no banco de dados estão corretos. Execute ambos:

wp option get siteurl
wp option get home

Ambos devem retornar seu domínio correto. Se algum retornar o domínio antigo, você pode atualizá-los manualmente:

wp option update siteurl 'https://newdomain.com'

wp option update home 'https://newdomain.com'

Em seguida, verifique se seus arquivos principais do WordPress foram transferidos sem corrupção:

wp core verify-checksums

Se retornar erros, anote quais arquivos foram sinalizados. Um punhado de arquivos modificados em wp-content é esperado e não é um problema — esses são seus arquivos de tema e plugin, que não fazem parte da comparação de checksum. Erros em arquivos principais em wp-admin ou wp-includes valem a pena investigar.

Visualize o site antes de atualizar o DNS. Adicione uma linha temporária ao arquivo hosts da sua máquina local apontando seu domínio para o endereço IP do novo servidor. No Mac ou Linux, abra /etc/hosts em um editor de texto e adicione:

123.456.789.0 yourdomain.com

Substitua 123.456.789.0 pelo IP do seu novo servidor. Salve o arquivo e abra seu domínio em um navegador. Você agora está vendo o novo servidor enquanto todos os outros ainda acessam o antigo.

Verifique cada um destes antes de prosseguir:

• Página inicial carrega corretamente
• Login de administrador funciona em /wp-admin
• Imagens são exibidas em posts e páginas
• Menus de navegação estão intactos
• Widgets aparecem corretamente na barra lateral ou rodapé
• A aparência do tema corresponde ao original

Quando tudo estiver verificado, remova a linha que você adicionou ao seu arquivo hosts. Então, você estará pronto para uma atualização de DNS.

Etapa 8: Atualizar o DNS e Lançar

Aponte o registro A do seu domínio para o endereço IP do seu novo servidor. Onde você faz isso depende de para onde os nameservers do seu domínio estão apontados: seja o seu registrador de domínio ou o gerenciador de DNS do seu provedor de hospedagem.

Faça login, encontre o registro A para o seu domínio e atualize o IP.

A propagação do DNS leva de alguns minutos a 48 horas, dependendo do seu registrador e da configuração de TTL (tempo de vida) do seu domínio. Durante esse período, alguns visitantes acessarão o servidor antigo e outros acessarão o novo. Isso é normal. Não é um sinal de que algo quebrou.

Mantenha o servidor antigo em funcionamento por pelo menos 24-48 horas após a atualização do DNS. Desligá-lo durante a propagação significa que alguns visitantes não encontrarão nada.

Assim que tiver certeza de que a propagação foi concluída, execute uma limpeza final do cache no novo servidor:

wp cache flush

Etapa 9: Limpar com wp duplicator cleanup

Com o novo servidor confirmado como ativo e estável, volte ao servidor antigo e execute:

wp duplicator cleanup

Isso remove os arquivos de backup e quaisquer dados temporários que o Duplicator criou durante o processo de construção na Etapa 1. Mantém o servidor antigo organizado e limpa quaisquer artefatos de migração antes de desativá-lo.

Execute isso somente depois de ter certeza de que a migração foi concluída. Assim que os arquivos de backup forem removidos, a opção de recuperação de desastres da Etapa 1 também será perdida.

Se você quiser manter o backup como um arquivo de longo prazo, mova-o para armazenamento remoto antes de executar a limpeza.

Solução de Problemas de Erros Comuns de Migração do WP-CLI

Mesmo uma migração cuidadosa pode encontrar obstáculos. Aqui estão os pontos de falha mais comuns, como eles se parecem e como corrigi-los.

“Erro ao Estabelecer Conexão com o Banco de Dados” Após a Importação

O que você vê: O WordPress exibe uma tela branca ou a mensagem “Erro ao estabelecer conexão com o banco de dados” no novo servidor imediatamente após a importação.

Por que acontece: O wp-config.php ainda contém as credenciais do banco de dados do servidor antigo. Este é o erro mais comum em uma migração WP-CLI e é fácil de perder se você transferiu os arquivos antes de atualizar a configuração.

Como corrigir: Abra o wp-config.php no novo servidor e atualize DB_NAME, DB_USER, DB_PASSWORD e DB_HOST para corresponder ao banco de dados do seu novo servidor. Salve o arquivo e recarregue o site.

Configurações de Tema, Widgets ou Opções de Plugin Resetadas Após a Migração

O que você vê: O site carrega, mas o tema parece errado, os widgets estão faltando ou as configurações do plugin voltaram aos padrões. Nenhuma mensagem de erro em lugar nenhum.

Por que acontece: Você executou o wp search-replace sem o sinalizador --precise. A substituição de URL corrompeu os dados serializados no banco de dados, e o WordPress descartou silenciosamente os valores corrompidos.

Como corrigir: Reexecute o search-replace com --precise e --all-tables:

wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables --precise

Se os dados já estiverem gravemente corrompidos e reexecutar o search-replace não restaurar as configurações, restaure o backup do Duplicator que você criou na Etapa 1 e refaça a migração.

“wp: command not found” no Novo Servidor

O que você vê: Qualquer comando WP-CLI no novo servidor retorna wp: command not found ou command not found: wp.

Por que acontece: O WP-CLI não está instalado no novo servidor, ou está instalado, mas não está no seu PATH.

Como corrigir: Instale o WP-CLI no novo servidor. Se você não tiver permissão para tornar o arquivo executável em seu host, pode executar comandos usando php wp-cli.phar em vez de wp.

rsync Sai com "Permissão negada"

O que você vê: O rsync é executado, mas sai mais cedo com um ou mais erros de "Permissão negada" em arquivos ou diretórios específicos.

Por que acontece: Ou sua chave SSH não está configurada corretamente para o servidor de destino, ou há uma incompatibilidade de propriedade de arquivo entre os dois servidores.

Como corrigir: Verifique primeiro o acesso à chave SSH com ssh user@newserver. Se isso falhar, resolva a autenticação da chave antes de tentar o rsync novamente. Se a conexão funcionar, mas arquivos específicos forem negados, você pode precisar usar chown nos arquivos transferidos no novo servidor para corresponder ao usuário da web que seu host usa — comumente www-data no Ubuntu ou o nome de usuário da conta em hosts cPanel.

Site Carrega, mas Imagens Estão Quebradas

O que você vê: As páginas carregam corretamente, mas as imagens mostram ícones de imagem quebrada em todo o site.

Por que acontece: Ou a pasta wp-content/uploads não foi transferida completamente, ou os URLs de imagem codificados no conteúdo do post não foram capturados pelo search-replace.

Como corrigir: Execute o rsync novamente, visando apenas a pasta uploads para capturar quaisquer arquivos que não foram transferidos:

rsync -avz --progress /path/to/old-wordpress/wp-content/uploads/ user@newserver:/path/to/new-wordpress/wp-content/uploads/

Em seguida, execute o search-replace novamente com --dry-run para verificar se algum URL de imagem ainda faz referência ao domínio antigo.

Nada Está Funcionando: Restaure e Comece de Novo

Se o site estiver completamente quebrado e você não conseguir identificar uma causa clara, não gaste horas depurando um estado de migração incompleto. Restaure o backup do Duplicator Pro que você criou na Etapa 1.

A URL de recuperação de desastres do Duplicator pode trazer o site antigo de volta, mesmo que o WordPress esteja bloqueado.

Assim que você voltar a um estado limpo e funcionando, refaça as etapas lentamente. Use –dry-run no rsync e wp search-replace antes de confirmar qualquer coisa, e verifique novamente as credenciais do wp-config.php antes de executar a importação.

Perguntas Frequentes (FAQs)

Seu Site Está no Novo Servidor. Veja o Que Observar a Seguir.

Você exportou o banco de dados, transferiu os arquivos, atualizou o wp-config.php, importou, executou uma busca e substituição, verificou tudo no novo servidor e alterou o DNS. Essa é a migração completa.

As primeiras 48 horas valem a pena prestar atenção. A propagação do DNS significa que alguns visitantes ainda acessarão o servidor antigo durante esse período, então não o desative ainda.

Observe quaisquer camadas de cache que possam estar servindo conteúdo desatualizado. Um flush completo do cache no novo servidor, após a confirmação da propagação, leva dez segundos e elimina muitos problemas de exibição.

Se algo ainda parecer errado após a conclusão da propagação, use wp search-replace --dry-run como uma ferramenta de diagnóstico antes de mexer em qualquer coisa:

wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables --precise --dry-run

Isso mostra quais tabelas ainda contêm o domínio antigo sem fazer nenhuma alteração. É a maneira mais rápida de confirmar se um URL persistente é um erro de busca e substituição ou algo codificado diretamente em um arquivo de tema.

URLs codificados diretamente em arquivos de tema personalizados não serão detectados pela busca e substituição. Você precisará encontrá-los e atualizá-los manualmente no código do tema.

Migre com Confiança Usando Duplicator Pro

Uma migração sem backup é um risco. Servidores se comportam inesperadamente, importações são interrompidas e dados serializados nem sempre sobrevivem a uma busca e substituição de forma limpa.

Ter um ponto de restauração antes de começar significa que qualquer uma dessas situações é um pequeno contratempo em vez de um problema sério.

Duplicator Pro torna o backup um único comando do terminal: wp duplicator build. E se algo der errado, a URL de recuperação de desastres traz seu site original de volta, mesmo que o WordPress esteja completamente bloqueado.

Mais de 1,5 milhão de profissionais de WordPress usam o Duplicator Pro para fazer backup, migrar e clonar seus sites. Junte-se a eles!

Se este tutorial ajudou, estes guias também valem a pena ser marcados.

• Como Mover um Site WordPress para um Novo Hospedeiro
• Por Que Você Não Consegue Fazer Login no WordPress Após uma Migração
• Migração de DNS Feita Corretamente: Como Evitar os Erros Mais Comuns
• O Checklist Completo de Testes do WordPress Pós-Migração
• Como Auditar Conteúdo Antes de uma Migração de Site
• Como Migrar um Site WordPress GRATUITAMENTE