Como alterar a URL do WordPress com segurança operacional (WP-CLI, SQL e wp-config)

Alterar URL no WordPress parece simples, mas em migração real pode quebrar login, mídia, links internos, callback de plugin e cache. Neste artigo, documento o método operacional que uso para trocar domínio sem improviso, incluindo validação, update de conteúdo e plano de rollback.

Conceitos que precisam estar claros

WordPress usa duas opções principais:

• home: URL pública do site;
• siteurl: URL base da aplicação/painel.

Na maioria dos cenários ambas são iguais. Em cenários avançados podem divergir, mas isso deve ser intencional.

Pré-check antes de alterar

1. backup do banco;
2. backup de wp-config.php;
3. inventário de plugins com callback de URL;
4. confirmar DNS/SSL do novo domínio.

cp wp-config.php wp-config.php.bak.$(date +%F-%H%M)

Export SQL (exemplo):

mysqldump -u DB_USER -p DB_NAME > /root/wp-url-change-$(date +%F-%H%M).sql

Método preferencial: WP-CLI

Validar URL atual:

wp option get siteurl
wp option get home

Alterar para novo domínio:

wp option update siteurl 'https://novodominio.com'
wp option update home 'https://novodominio.com'

Validar novamente:

wp option get siteurl
wp option get home

Atualização de referências internas

Após trocar home/siteurl, ainda restam referências hardcoded em conteúdo, metadados e opções serializadas. O método seguro é wp search-replace.

Dry-run primeiro:

wp search-replace 'https://antigodominio.com' 'https://novodominio.com' --all-tables --dry-run

Aplicação real:

wp search-replace 'https://antigodominio.com' 'https://novodominio.com' --all-tables

Se houver multisite ou tabela customizada, ajuste escopo explicitamente.

Método via SQL (quando WP-CLI não está disponível)

Descobrir DB no wp-config.php:

grep DB_ wp-config.php

Conectar:

mysql -u DB_USER -p
USE DB_NAME;

Ler valores atuais:

SELECT option_name, option_value
FROM wp_options
WHERE option_name IN ('siteurl','home');

Atualizar:

UPDATE wp_options SET option_value='https://novodominio.com' WHERE option_name='siteurl';
UPDATE wp_options SET option_value='https://novodominio.com' WHERE option_name='home';

Atualizar referências diretas (cuidado com serialização):

UPDATE wp_posts SET post_content = REPLACE(post_content, 'https://antigodominio.com', 'https://novodominio.com');
UPDATE wp_postmeta SET meta_value = REPLACE(meta_value, 'https://antigodominio.com', 'https://novodominio.com');

Para opções serializadas, prefira WP-CLI. SQL bruto pode corromper tamanho de strings serializadas.

Fallback emergencial via wp-config.php

Quando painel fica inacessível e você precisa recuperar rapidamente:

define('WP_HOME', 'https://novodominio.com');
define('WP_SITEURL', 'https://novodominio.com');

Essa abordagem força URL em runtime. É útil para incidente, mas deve ser tratada como temporária.

Validação pós-mudança

Checklist que executo após alterar:

1. abrir frontend (/);
2. abrir admin (/wp-admin);
3. testar login;
4. testar upload de mídia;
5. testar links de menu e permalink;
6. limpar cache (plugin/CDN/server);
7. revisar console do navegador por assets mistos HTTP/HTTPS.

Troubleshooting real de migração

Loop de login no wp-admin

Causa comum: cookie de sessão em domínio antigo + cache + HTTPS incorreto.

Ação: limpar cookies, limpar cache, validar siteurl/home e headers HTTPS.

CSS/JS quebrado

Causa comum: URLs absolutas antigas em plugin/tema.

Ação: wp search-replace com escopo completo e revisão de opções de tema.

Redirecionamento infinito

Causa comum: regra no .htaccess + plugin de redirect + proxy reverso sem header correto.

Rollback

Se houver impacto crítico:

1. restaurar dump SQL;
2. restaurar wp-config.php backup;
3. invalidar cache novamente;
4. reabrir janela com plano corrigido.

Conclusão

Trocar URL no WordPress em produção exige processo, não comando isolado. Quando aplico este fluxo (backup, alteração, search-replace, validação e rollback), a migração fica previsível e auditável, com risco operacional muito menor.

Este post está licenciado sob CC BY-NC.