O WordPress guarda URLs absolutos em dezenas de tabelas da base de dados, pelo que uma mudança de domínio ou uma passagem para SSL deixa endereços antigos espalhados por publicações, opções e definições de plugins: uma pesquisa e substituição é a forma de os limpar em segurança. Este guia explica as duas formas suportadas de o fazer no KPanel, porque é que um terceiro método comum corrompe os dados e como verificar o resultado.
Quando precisa de uma
- Ao passar de
http://parahttps://depois de ativar o SSL. - Ao mudar de domínio, por exemplo de
old-brand.co.nzparanew-brand.co.nz. - Depois de enviar o staging para produção, quando o nome de anfitrião de staging ainda está gravado na base de dados.
- Ao desativar um antigo servidor de recursos e redirecionar todos os URLs de imagens de uma só vez.
- Para corrigir um erro repetido em muitas publicações, como um número de telefone antigo ou o nome de um produto descontinuado.
Uma pesquisa e substituição reescreve linhas em todas as tabelas ao mesmo tempo e não existe forma de anular linha a linha. Faça uma cópia de segurança antes de começar, sempre, mesmo para uma alteração que pareça trivial. O KPanel cria uma automaticamente quando usa as ferramentas integradas descritas abaixo, mas se executar o comando por si próprio, a responsabilidade é sua. Consulte Fazer uma cópia de segurança.
Porque não pode simplesmente executar um REPLACE de SQL
Este é o erro mais prejudicial no trabalho com bases de dados WordPress, por isso vale a pena compreendê-lo antes de escolher um método.
O WordPress guarda as definições de plugins, as opções de temas e os dados de widgets como strings serializadas de PHP. Uma string serializada regista o comprimento de cada valor que contém, desta forma:
a:1:{s:3:"url";s:26:"http://old-domain.co.nz/x";}
Esse s:26 diz que o URL tem 26 caracteres. Substitua http:// por https:// com um REPLACE() simples de SQL e o texto passa a ter 27 caracteres, enquanto o comprimento guardado continua a indicar 26. O PHP recusa-se então a desserializar a opção inteira, e a definição volta silenciosamente a ficar vazia. As definições do personalizador do tema desaparecem, os sliders perdem os seus diapositivos, as licenças de plugins anulam o próprio registo.
O search-replace do WP-CLI que o KPanel executa desserializa cada valor, faz a substituição no seu interior e volta a serializá-lo com os comprimentos corrigidos. É por isso que é o único método documentado aqui.
Nunca execute UPDATE wp_options SET option_value = REPLACE(...) ou o equivalente no phpMyAdmin numa base de dados WordPress. Parece que funcionou, indica linhas afetadas e destrói discretamente todas as definições serializadas em que tocou. Não há forma de reparar isto a não ser restaurar uma cópia de segurança.
Método 1: O cartão Search & Replace
Esta é a escolha certa para quase toda a gente. Está disponível em todos os planos WordPress.
- Inicie sessão no KPanel e clique em Websites na barra lateral esquerda.
- Clique no site.
- Abra o separador WordPress e depois a secção Ações rápidas.
- Encontre o cartão Search & Replace e clique em Configurar.
- Introduza o texto existente em Procurar (valor antigo).
- Introduza o novo texto em Substituir por.
- Deixe Simulação (apenas pré-visualização, sem alterações) assinalado e clique em Pré-visualizar.
A simulação indica quantas substituições seriam feitas e divide a contagem por tabela e coluna, para que possa ver exatamente onde a alteração iria incidir antes de a confirmar.
Quando a pré-visualização estiver correta:
- Desmarque Simulação.
- Clique em Executar.
- Confirme a caixa de diálogo.
É feita automaticamente uma cópia de segurança completa antes de a substituição começar, e a execução abrange todas as tabelas, incluindo as criadas por plugins.
Pesquise a string mais específica possível. Substituir old-domain.co.nz também reescreve mail.old-domain.co.nz e staging.old-domain.co.nz, o que raramente é o que pretende. Incluir o esquema, como em https://old-domain.co.nz, mantém a correspondência precisa.
Método 2: WP-CLI a partir da consola
A consola dá-lhe o mesmo motor com mais controlo sobre as opções. É uma das secções que aparecem nos planos geridos; noutros planos, a barra de separadores mostra em vez disso uma ligação +8 on Managed.
Abra o site, depois WordPress, depois Consola. A linha de comandos já começa com wp, por isso escreva apenas o resto do comando.
Primeiro, pré-visualize:
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables --dry-run
Depois, execute-o a sério:
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables
A consola não faz uma cópia de segurança por si. A cópia de segurança automática antes da execução só acontece quando usa o cartão Search & Replace do Método 1. Se executar o comando aqui, faça primeiro uma cópia de segurança por si próprio a partir da página Cópias de segurança do site.
Opções úteis:
| Opção | O que faz |
|---|---|
--all-tables | Inclui tabelas personalizadas criadas por plugins, e não apenas as tabelas principais do WordPress |
--dry-run | Indica o que mudaria e não escreve nada |
--precise | Usa PHP em vez de SQL para a substituição. É mais lento, mas lida com estruturas serializadas complicadas |
--skip-columns=guid | Não altera os GUID das publicações (ver abaixo) |
--report-changed-only | Reduz o resultado às tabelas que realmente mudaram |
Uma nota sobre os GUID
Todas as publicações do WordPress têm uma coluna guid. Apesar de parecer um URL, é um identificador e não uma ligação, e os leitores de feeds usam-no para saber se já viram um item. Reescrevê-lo pode fazer com que todas as publicações do seu feed voltem a aparecer como novas.
Reescreva os GUID quando estiver a mudar de domínio de forma permanente e a começar do zero. Ignore-os com --skip-columns=guid quando estiver apenas a passar de HTTP para HTTPS no mesmo domínio.
Mudar de domínio: use antes o cartão Site URL
Se o objetivo é mudar o site para um novo domínio, não comece pela pesquisa e substituição. O cartão Change Site URL, na mesma secção Ações rápidas, atualiza as opções siteurl e home e executa a substituição em todas as tabelas numa única operação, pela ordem correta. Fazê-lo ao contrário pode deixar o WordPress incapaz de carregar a sua própria administração.
Depois da substituição
Percorra esta lista antes de dar o trabalho por concluído.
- Limpe a cache. Na secção Ações rápidas, execute Flush Cache. Se o site usar a cache de página completa, limpe-a em WordPress, depois Caching.
- Limpe as regras de reescrita. Execute Flush Rewrites na mesma secção, ou abra Definições, depois Ligações permanentes no wp-admin e clique em Guardar alterações sem mudar nada.
- Limpe a cache do CDN, se o site o usar, em Desempenho, depois Kapsule CDN. Consulte Limpar a cache do Kapsule CDN.
- Carregue o site numa janela privada, para que a cache do seu navegador não o induza em erro.
- Verifique o cadeado. Um cadeado em falta ou com aviso após uma passagem para SSL significa que ficaram URLs para trás: Resolver avisos de conteúdo misto.
- Percorra as páginas mais delicadas. Sliders da página inicial, o logótipo do cabeçalho, qualquer página criada com um construtor de páginas e o checkout numa loja. São estes que contêm os URLs guardados em opções serializadas.
- Limpe a cache de qualquer plugin de cache a partir do respetivo ecrã de definições.
Resolução de problemas
A simulação indica zero substituições. A string não está na base de dados exatamente nessa forma. Verifique se há uma barra final, um prefixo www. ou o esquema. Experimente pesquisar primeiro apenas o nome de anfitrião, para confirmar que existe de todo.
As imagens deixaram de aparecer após uma mudança de domínio. Os URLs de multimédia estão em wp_posts e wp_postmeta e são abrangidos por --all-tables, mas um CDN ou um plugin de otimização de imagens pode guardar em cache as suas próprias cópias reescritas. Limpe a cache do CDN e a do plugin e, em seguida, recarregue.
As definições desapareceram após a substituição. É o problema da serialização, e significa que a alteração foi feita com SQL direto em vez de através das ferramentas aqui descritas. Restaure a cópia de segurança feita antes da execução: Restaurar a partir de uma cópia de segurança.
Os URLs de staging continuam a voltar. Algo os está a repor, normalmente um envio agendado ou uma opção em cache. Verifique o fluxo de trabalho em Usar o staging: enviar e obter alterações e certifique-se de que Rewrite URLs está assinalado quando faz o envio.