Como fazer downgrade ao WordPress (plugin, FTP, WP-CLI)

Este guia cobre três caminhos de downgrade (painel com WP Rollback, WP-CLI e FTP/SFTP) e o caso em que nenhum deles chega: migrações de esquema. A documentação oficial de atualizações está em Updating WordPress. As versões antigas do núcleo estão em Releases.

Antes de qualquer passo: exporte a base de dados e copie wp-content para um sítio seguro. Um rollback sem backup é trocar um incidente por outro.

#Como saber o que partiu o site WordPress

Não assuma que foi o núcleo. Em sites portugueses e lojas WooCommerce o padrão mais comum é:

1. Plugin atualizado (formulário, SEO, page builder, gateway Multibanco/MB Way).
2. Tema ou child theme incompatível com a nova API do core.
3. Núcleo WordPress (menos frequente sozinho, mais frequente em combinação com PHP antigo no alojamento).
4. Base de dados já migrada por um upgrade de WooCommerce ou de um membership plugin.

Se o admin ainda abre: Desativar plugins um a um (ou renomear pastas por SFTP) isola o culpado em minutos. Se o admin não abre: renomeie wp-content/plugins para plugins.off, crie pasta plugins vazia, e veja se o site volta. Depois reative pastas uma a uma.

Ative temporariamente WP_DEBUG_LOG no wp-config.php (nunca WP_DEBUG_DISPLAY em produção) e leia wp-content/debug.log - o stack trace diz o ficheiro e a linha, não a intuição.

#O que verificar antes de fazer downgrade ao WordPress

Um rollback apaga pistas. Antes de substituir um único ficheiro, registe o que o site está a correr neste momento. Assim consegue avançar de novo quando o erro for corrigido e consegue comparar os dois estados se o rollback não resolver.

Com WP-CLI demora menos de um minuto:

wp core version --extra
wp plugin list --fields=name,status,version,update_version --format=csv > plugins-antes.csv
wp theme list --fields=name,status,version --format=csv > temas-antes.csv
wp db export backup-antes-rollback.sql

wp core version --extra mostra a versão do núcleo juntamente com a revisão da base de dados que o código em execução espera. Compare-a com wp option get db_version, a revisão realmente guardada na base de dados. Se o número guardado for superior ao que a versão de destino espera, a base de dados já migrou para a frente e uma simples troca de ficheiros deixa de lhe corresponder. Os dois ficheiros CSV dão-lhe as versões exatas para onde voltar mais tarde, em vez de as tentar recordar à meia-noite.

Dois cabeçalhos de plugin decidem se um downgrade do núcleo é sequer possível. Um plugin pode declarar Requires at least e Requires PHP no ficheiro principal e, quando esses cabeçalhos existem, o WordPress bloqueia a ativação se a versão do núcleo ou do PHP não os cumprir. Se um plugin exige WordPress 6.6 e desce o núcleo para 6.4, não o consegue reativar depois do downgrade, e o código pode chamar funções do núcleo que a versão antiga não tem. Leia os cabeçalhos antes de escolher a versão de destino:

grep -RE "Requires (at least|PHP)" wp-content/plugins/*/*.php

Por fim, ponha o site em modo de manutenção para que visitantes e crawlers recebam um 503 em vez de uma instalação substituída a meio: wp maintenance-mode activate, e wp maintenance-mode deactivate quando o trabalho terminar.

#Como reverter plugins e temas com WP Rollback

Se entra no wp-admin, o caminho mais simples para plugins e temas do repositório é o plugin WP Rollback.

1. Instale e ative WP Rollback em Plugins > Adicionar plugin.
2. Em Plugins instalados (ou Temas), aparece a ligação Rollback junto de cada item suportado.
3. Escolha a versão anterior conhecida como estável no seu site.
4. Confirme e teste a página crítica (checkout, formulário de contacto, área de membros).

Limitações reais:

• Não substitui um backup da base.
• A versão gratuita trabalha, segundo a página do plugin, com plugins e temas do wordpress.org. Os plugins premium exigem a versão paga Pro.
• Para o próprio núcleo existe um plugin à parte, Core Rollback, de Andy Fragen, que fica no menu Ferramentas.
• Reverter um page builder sem reverter templates gravados na base pode deixar layouts partidos.

Depois do rollback, anote a versão má e bloqueie atualizações automáticas desse plugin até testar em staging.

#Downgrade do WordPress com WP-CLI

Com SSH e WP-CLI instalado no alojamento, o rollback é rápido e repetível. Referência: wp core update.

Reverter o núcleo para uma versão concreta:

wp core update --version=7.0.7 --force

Reverter um plugin:

wp plugin install woocommerce --version=8.5.0 --force

Reverter um tema:

wp theme install twentytwentyfour --version=1.0 --force

A opção --force pertence a wp plugin install e wp theme install: segundo a documentação, substitui qualquer versão instalada sem pedir confirmação. O wp plugin update não tem esta opção, embora também aceite --version. No núcleo, --force em wp core update faz a atualização mesmo quando a versão instalada é superior à pedida.

Boas práticas no servidor:

• Corra os comandos a partir da raiz do WordPress (wp core is-installed deve responder positivamente).
• Faça wp db export backup-antes-rollback.sql imediatamente antes.
• Confirme a versão com wp core version / wp plugin list depois do comando.
• Limpe object cache se existir (wp cache flush) - OPcache e Redis gostam de servir código antigo durante uns minutos.

#Para que versão do WordPress fazer rollback

Nem todas as versões antigas são um destino seguro. O WordPress.org publica o estado de segurança de cada versão do núcleo na API stable-check. A mesma lista alimenta o plugin Core Rollback, que segundo a sua descrição só oferece a versão mais recente e versões antigas, mas seguras. A 14 de outubro de 2026 a API marca 7.1.3 como latest, a última versão de manutenção de cada ramo antigo (7.0.7, 6.9.10, 6.8.11 e assim por diante) como outdated e todas as versões de manutenção anteriores desses ramos como insecure. A versão 6.4.3, que este guia usava como exemplo até esta atualização, está na lista das inseguras.

A regra é então: volte à última versão de manutenção do ramo que funcionava, não ao número exato que corria antes. Se foi o 7.1.x que partiu o site, o destino é 7.0.7, não 7.0.2. Verifique o estado antes de executar o comando:

curl -s https://api.wordpress.org/core/stable-check/1.0/ | grep '"7.0.7"'

A segunda verificação é o PHP. A tabela de compatibilidade da equipa do núcleo indica com que versões de PHP cada versão foi testada. Um rollback pode tirá-lo dessa tabela:

Se o alojamento já passou o servidor para PHP 8.5, um rollback para 6.8 cai numa combinação que a equipa do núcleo nunca listou como suportada. O limite também funciona ao contrário: o WordPress 7.0 deixou de suportar PHP 7.2 e 7.3, por isso num servidor assim a versão mais recente que pode correr é a 6.9. Escolha o destino que passa as duas verificações: seguro segundo o stable-check e listado para a versão de PHP do seu servidor. A versão que o WordPress realmente vê aparece com wp eval 'echo PHP_VERSION;'.

#WP-CLI em alojamento partilhado

Se o alojamento partilhado não der SSH, muitos painéis (cPanel Terminal, RunCloud, GridPane, Plesk) expõem WP-CLI na mesma; vale a pena perguntar ao suporte antes de ir para FTP às cegas.

#Downgrade do WordPress por FTP

Quando o painel está morto e não há WP-CLI, sobem-se ficheiros do núcleo a partir do pacote oficial.

1. Descarregue a versão desejada em wordpress.org/download/releases. Se tiver WP-CLI no seu computador, wp core download --version=7.0.7 --skip-content --path=wp-7.0.7 faz o mesmo sem os temas e plugins predefinidos, segundo a documentação.
2. Descompacte no computador.
3. Apague do pacote a pasta wp-content e o ficheiro wp-config-sample.php. Nunca envie um wp-content limpo por cima do site real - perde uploads, plugins e temas.
4. Ligue por SFTP e envie wp-admin, wp-includes e os ficheiros da raiz (wp-login.php, wp-settings.php, etc.) com overwrite.
5. Não sobrescreva wp-config.php nem .htaccess personalizado.

Se, ao abrir /wp-admin depois disso, aparecer a mensagem É necessária uma actualização da base de dados, confirme com Actualizar a base de dados do WordPress.

Para um único plugin: descarregue o ZIP da versão antiga (na página do plugin, em Advanced, campo Previous versions), apague a pasta do plugin em wp-content/plugins/slug e envie a pasta da versão antiga. Ou renomeie a pasta atual para slug.broken e suba a antiga ao lado.

#Como restaurar o WordPress a partir do backup do alojamento

Antes de tocar num único ficheiro, verifique se o alojamento consegue desfazer a atualização por si. Em alojamento WordPress gerido é muitas vezes o caminho mais rápido e não exige linha de comandos.

A maioria dos alojamentos geridos guarda pontos de restauro diários automáticos e oferece restauro com um clique no painel, normalmente num separador chamado algo como “Backups” ou “Restaurar”. Escolhe uma cópia de antes da atualização e confirma. O alojamento repõe ficheiros e base de dados em conjunto nesse momento. Como as duas camadas recuam em sincronia, este caminho evita a armadilha do esquema descrita na secção seguinte.

Duas coisas a verificar primeiro. Alguns alojamentos restauram ficheiros e base de dados em separado, por isso leia as etiquetas e escolha a cópia completa, não só os ficheiros. E um restauro substitui tudo o que veio depois da cópia: encomendas, comentários ou artigos criados a partir desse ponto perdem-se. Numa loja com vendas a decorrer, pese isso contra um rollback dirigido a um só plugin. Num site institucional em que nada mudou durante a noite, o restauro com um clique costuma ser a opção mais limpa.

#Como confirmar que o rollback do WordPress funcionou

“A página inicial carrega” não é verificação. Um rollback pode deixar uma árvore de ficheiros copiada a meio, uma cache de bytecode desatualizada ou um caminho do admin partido enquanto a página inicial continua a sair da cache.

Comece por confirmar a versão que está realmente instalada, não a que pretendia instalar:

wp core version
wp plugin get woocommerce --field=version
wp core verify-checksums
wp plugin verify-checksums --all

verify-checksums compara cada ficheiro em disco com as somas de verificação que o wordpress.org publica para aquela versão exata. É a forma mais rápida de apanhar a falha clássica do FTP: uma transferência que saltou ou truncou alguns ficheiros sem dar erro. Uma execução limpa significa que a árvore de ficheiros corresponde à versão pretendida. A variante para plugins só cobre plugins alojados no wordpress.org, por isso os plugins premium continuam a precisar de comparação manual.

Depois limpe todas as caches que possam continuar a servir o código que acabou de retirar:

• Cache de objetos: wp cache flush (Redis ou Memcached guardam objetos serializados criados pelo código mais recente).
• Cache de páginas e CDN: limpe a cache inteira, não um só URL, porque um erro fatal pode ter ficado em cache como resposta 500.
• PHP OPcache: a que quase todos esquecem. Em servidores com opcache.validate_timestamps=0, o bytecode compilado dos ficheiros mais recentes fica em memória até a pool PHP-FPM ser recarregada. Os ficheiros antigos estão no disco, mas continua a executar-se o código mais recente. Recarregue o PHP no painel do alojamento ou corra um script que chame opcache_reset().

Teste depois mais do que a página inicial. Os erros fatais após uma atualização costumam estar no admin-ajax, na REST API ou no checkout, e não numa página inicial em cache:

curl -o /dev/null -s -w "%{http_code}\n" https://o-seu-dominio.pt/
curl -o /dev/null -s -w "%{http_code}\n" https://o-seu-dominio.pt/wp-json/

Inicie sessão, abra o ecrã de definições do plugin revertido e faça uma operação de escrita: guardar um artigo, enviar o formulário de contacto, fazer uma encomenda de teste. As operações de leitura passam em muitas instalações partidas.

Esvazie wp-content/debug.log antes desse teste e leia-o outra vez no fim. Um registo que fica vazio é um sinal mais forte do que uma página que apenas parece correta, porque exclui também os avisos e notas de funções obsoletas que se tornam erros fatais na versão seguinte. Termine em Ferramentas > Diagnóstico do site, cujos testes assinalam uma versão do núcleo atrasada em atualizações de segurança e uma versão de PHP que o WordPress já não considera suportada.

#Restaurar backup da base de dados após atualização

Algumas atualizações correm migradores SQL. Exemplos típicos:

• WooCommerce major (novas tabelas HPOS / encomendas)
• Plugins de membership ou LMS que alteram meta e custom tables
• Certos builders que reescrevem post meta em massa

Aí o código antigo não sabe ler o esquema novo. Sintomas: erros SQL no log, produtos em falta, checkout a falhar, ecrã branco só em URLs de loja.

Procedimento:

1. Ponha o site em manutenção ou desligue o tráfego pago.
2. Restaure o dump SQL de antes da atualização (phpMyAdmin, wp db import, painel do alojamento).
3. Restaure os ficheiros (núcleo + plugins) para o mesmo ponto no tempo - idealmente o mesmo backup.
4. Só depois investigue em staging porque a atualização partiu e prepare um upgrade limpo.

Se o backup da base for de há três semanas e já houver encomendas novas, precisa de estratégia de merge (encomendas exportadas, restauro parcial) - isso já é trabalho de recuperação, não um rollback de cinco minutos. Em lojas PT com Multibanco, anote também webhooks e referências de pagamento pendentes antes de tocar na base.

#Como impedir que um plugin revertido volte a atualizar

Nada num downgrade diz ao WordPress para ficar na versão antiga. As atualizações automáticas correm a partir dos eventos cron wp_version_check, wp_update_plugins, wp_update_themes e wp_maybe_auto_update, por isso um plugin revertido de manhã pode estar de volta à versão com erro no mesmo dia. É a explicação habitual quando um site “volta a partir sozinho” horas depois de um rollback bem-sucedido.

Fixe primeiro o plugin em causa:

wp plugin auto-updates disable woocommerce
wp plugin auto-updates status

Essa definição fica guardada na opção auto_update_plugins como lista de caminhos de ficheiros de plugins. Isto importa por um motivo: se mais tarde restaurar uma cópia da base de dados feita antes de fixar o plugin, a fixação desaparece com ela. Volte a defini-la depois de cada restauro da base de dados.

Para o núcleo, use o wp-config.php:

define( 'WP_AUTO_UPDATE_CORE', 'minor' );

WP_AUTO_UPDATE_CORE aceita true, false ou 'minor'. Com 'minor' as versões de segurança continuam a entrar, enquanto a versão principal que partiu o site fica bloqueada. É a definição para depois da emergência. AUTOMATIC_UPDATER_DISABLED e o filtro automatic_updater_disabled desligam todo o mecanismo de atualização, incluindo traduções, por isso use-os apenas nas horas de diagnóstico.

Confirme com wp cron event list que nada ficou em fila e verifique também o painel: os alojamentos geridos correm o seu próprio agendador de atualizações fora do WordPress, que ignora as constantes do wp-config.php. Se o site é construído com Composer, fixe lá a versão exata ("wpackagist-plugin/woocommerce": "8.5.0"), para que seja o próprio deploy a impor a fixação e não uma definição que alguém pode limpar no painel.

Trate cada fixação como temporária. Anote a versão que está a evitar e o motivo, acompanhe o changelog do plugin e retire a fixação assim que sair uma versão corrigida. Um plugin fixado para sempre torna-se a falha de segurança que a atualização devia fechar.

#Que método de rollback do WordPress escolher

O método certo depende do acesso que tem e do que partiu:

Se servirem duas linhas, prefira a de cima: um rollback dirigido a um plugin mexe sempre menos do que um restauro completo, e o restauro completo é a rede de segurança para os casos em que o rollback dirigido não pode funcionar.

#Como baixar a versão de PHP no painel do alojamento

Nem todas as falhas depois de uma atualização são culpa do WordPress. Os alojamentos sobem periodicamente a versão de PHP do servidor, por vezes de forma automática, e um plugin ou tema nunca testado no PHP mais recente pode partir no momento da mudança. O sintoma é um erro fatal que menciona uma função obsoleta ou removida, mesmo sem ter atualizado nada dentro do WordPress.

A correção não é um downgrade do WordPress, mas uma troca da versão de PHP no painel do alojamento. A maioria dos painéis (cPanel, Plesk e os painéis dos alojamentos geridos) tem uma ferramenta para escolher a versão de PHP. Volte à versão em que o site corria antes, recarregue e confirme que o erro desaparece.

Trate isso como tempo de folga, não como solução. Uma versão de PHP sem suporte de segurança deixa falhas abertas. Aproveite para atualizar o plugin ou tema para uma versão que suporte o PHP mais recente, teste em staging e volte a avançar o site em produção.

#Downgrade de plugins premium em alojamento partilhado

Muitos sites em Portugal misturam plugins do wordpress.org com licenças Elegant Themes, WPML, Gravity Forms ou gateways locais. O WP Rollback não lista releases privados. Para esses:

1. Guarde o ZIP da versão em produção num repositório interno ou no disco do projeto (versionado fora do webroot).
2. Antes de atualizar no painel, descarregue o ZIP novo mas mantenha o antigo comprimido com o número da versão no nome (gravityforms-2.8.0.zip).
3. Se o upgrade falhar, apague a pasta nova em wp-content/plugins/ e extraia o ZIP antigo.

No alojamento partilhado PT (cPanel clássico, planos “WordPress gerido” de ISPs nacionais), confirme se tem:

• acesso SFTP com chave (não só palavra-passe no FileZilla do portátil)
• phpMyAdmin ou wp db export para dumps
• versão PHP alinhada com os requisitos do núcleo que vai restaurar

Verifique também a combinação com o PHP antes de escolher o número. O WordPress 7.0 e versões seguintes exigem PHP 7.4, e as versões antigas do núcleo não estão listadas como suportadas nas versões de PHP mais recentes. A tabela na secção sobre para que versão fazer rollback mostra os limites, segundo a lista da equipa do núcleo.

#Como evitar o ecrã branco após atualizar WordPress

O downgrade é plano B. O plano A:

• Cópia staging com os mesmos plugins e a mesma versão de PHP do alojamento de produção (em PT muitos hosts ainda misturam 8.0/8.1/8.2 entre planos).
• Atualize primeiro no staging, teste checkout e formulários, só depois produção.
• Backups automáticos diários testados (restauro de verdade uma vez por trimestre, não só o ficheiro .sql a ocupar disco).
• Atualizações automáticas só para minor/patch do núcleo, se confia no host; majors e WooCommerce ficam manuais.

Se usa Git e CI, o rollback de código é um revert de commit - mas a base continua a precisar do mesmo cuidado descrito acima.

#O que fazer quando uma atualização parte o WordPress

1. Backup fresco (ficheiros + DB), mesmo que o site já esteja em baixo.
2. Isolar plugin/tema (renomear pastas).
3. Rollback do culpado (WP Rollback ou WP-CLI ou ZIP antigo).
4. Se falhar: restauro completo do backup pré-atualização.
5. Abrir staging, reproduzir o upgrade, corrigir conflito, planear janela de manutenção.

#Resumo

Downgrade no WordPress é rotina de sobrevivência, não vergonha. Painel com WP Rollback para plugins, WP-CLI quando tem SSH, FTP só no núcleo sem tocar em wp-content, e backup completo quando a base já migrou. O objetivo não é viver eternamente numa versão velha - é recuperar o site e voltar a atualizar com staging e backups que já provou restaurar.

Se precisa de alguém para montar esse fluxo de staging e restauro antes da próxima atualização partir a loja, contacte-nos - trabalhamos em WordPress e WooCommerce com este tipo de recuperação no dia a dia.

Do lado da entrega mantemos este tema sob auditoria de segurança WordPress.