Visita o teu site WordPress para verificar o painel de administração, mas em vez disso vês um ecrã branco com um erro: «Your PHP installation appears to be missing the MySQL extension which is required by WordPress». Reiniciar não resolve, o fornecedor de alojamento permanece em silêncio, o site fica parado como um peso morto.

Este erro não é uma sentença de morte para o teu servidor nem motivo para pânico. Na maioria das vezes, aparece após uma atualização do PHP, a migração do site para outro VPS ou a mudança do sistema operativo. O WordPress perde a ponte entre o PHP e o MySQL, e podes restaurá-la em 10 minutos.

Segue-se um guia passo a passo: do diagnóstico ao recarregamento final da configuração. Todos os comandos são válidos para PHP 8.0-8.4, servidores em Ubuntu, distribuições compatíveis com RedHat e alojamento com cPanel.

💡 Visão geral rápida:

• Verifica a versão atual do PHP e as extensões ativas através da Saúde do Site do WordPress
• Instala os módulos em falta: sudo apt install php-mysql para Ubuntu ou sudo dnf install php-mysqlnd para RHEL
• Verifica a diretiva extension_dir no php.ini; durante a migração do servidor, o caminho fica frequentemente corrompido
• Ativa o mysqli e o pdo_mysql através do painel de alojamento (cPanel, Plesk) em dois cliques
• Certifica-te de que as versões do WordPress e do PHP são compatíveis: ambas devem estar atualizadas

1. Verificar a versão do PHP e as extensões ativas

O método de diagnóstico mais rápido é a ferramenta integrada de Saúde do Site do WordPress. Vai ao painel de administração: Ferramentas, Saúde do Site, separador Informação. Expande a secção Servidor; aqui encontras a versão do PHP. Se for inferior a 7.4, está na hora de atualizar: de acordo com os requisitos do WordPress, a versão mínima do PHP para o WP 6.x é a 7.4, e a recomendada é a 8.0+.

Agora expande a secção Base de Dados. Se as linhas mysqli e pdo_mysql estiverem vazias ou em falta, encontraste a causa do erro. O WordPress está a tentar usar uma extensão que não existe na compilação do PHP.

Já que aí estás, verifica a secção Sistema de Ficheiros: problemas de permissões podem afetar indiretamente o carregamento de módulos do PHP.

Se o painel de administração estiver inacessível (ecrã completamente branco), cria um ficheiro info.php na raiz do site com o código <?php phpinfo(); e abre-o no teu navegador. A primeira linha mostrará a versão exata do PHP, e procurar por mysqli mostrará se a extensão existe.

2. Instalar as extensões mysqli e PDO MySQL através da consola

Liga-te ao servidor via SSH e verifica o que está instalado:

1
php -v
2
php -m | grep -E 'mysqli|pdo_mysql'

Se mysqli e pdo_mysql estiverem em falta no resultado, instala-as. Os comandos diferem consoante a distribuição.

Ubuntu / Debian:

1
sudo apt update
2
sudo apt install php-mysql

O pacote php-mysql inclui o mysqli, o pdo_mysql e o driver mysqlnd, tudo o que o WordPress precisa. Se tiveres várias versões do PHP, especifica uma em particular: php8.2-mysql, php8.3-mysql. Os detalhes da instalação estão descritos no manual PHP mysqli.

RHEL / CentOS / AlmaLinux:

1
sudo dnf update
2
sudo dnf install php-mysqlnd

Após a instalação, reinicia o servidor web:

1
sudo systemctl restart apache2
2
sudo systemctl restart php8.3-fpm
3
sudo systemctl restart nginx

Na maioria dos casos, o erro desaparece imediatamente após reiniciar.

3. Verifique a diretiva extension_dir no php.ini

Os pacotes estão instalados, mas o WordPress continua a queixar-se? Isto acontece durante a migração do site: a configuração do PHP «mudou-se» com caminhos antigos para o novo servidor.

Abra o info.php no seu navegador e localize o parâmetro Loaded Configuration File, este é o caminho para o php.ini ativo.

Agora localize extension_dir, o diretório a partir do qual o PHP carrega os módulos. Se o valor estiver vazio ou apontar para uma pasta inexistente, o mysqli.so não será carregado e o WordPress não verá o MySQL.

Abra o php.ini (já sabe o caminho) e localize a linha extension_dir. Atualize-a para o valor atual. No Ubuntu 22.04/24.04 com PHP 8.3, normalmente é:

1
extension_dir = "/usr/lib/php/20230831"

Em servidores com cPanel, o caminho é diferente, verifique o valor exato no info.php.

Após fazer as alterações, guarde o php.ini, reinicie o servidor web e não se esqueça de eliminar o info.php, um phpinfo() público expõe as versões dos módulos e os caminhos absolutos do servidor.

4. Ativar extensões através do painel de controlo do alojamento

Está a trabalhar através de um painel em vez da consola? A maioria dos painéis de alojamento gere as extensões com o rato:

• cPanel: Select PHP Version, caixas de seleção ao lado de mysqli e pdo_mysql, guardar. Aproveite para mudar a versão do PHP para uma moderna.
• Plesk: Domains, o seu domínio, PHP Settings, localize mysqli e pdo_mysql na lista de extensões.
• DirectAdmin: Extra Features, Select PHP Version, marque as extensões necessárias.
• **SiteGround, Cloudways, **Kinsta e outros alojamentos geridos: secção PHP Extensions no painel do site.

Após ativar as extensões, o painel reiniciará o PHP automaticamente e o site funcionará dentro de um minuto.

5. Certifique-se de que as versões do WordPress e do PHP são compatíveis

O WordPress 6.x (versão atual em 2026) requer um mínimo de PHP 7.4 e recomenda 8.0+. Se estiver no PHP 7.0 ou 7.1, mesmo as extensões instaladas não ajudarão: o núcleo do WP espera módulos para uma versão moderna do PHP.

Verifique a compatibilidade: painel de administração, Tools, Site Health, Info, Server. Se o PHP for inferior a 7.4, atualize:

• Alojamento partilhado: painel de controlo (cPanel/Plesk), mude o PHP para 8.2 ou 8.3.
• VPS: atualize através do gestor de pacotes:

1
sudo apt update
2
sudo apt install php8.3 php8.3-mysql php8.3-xml php8.3-curl php8.3-mbstring

Após atualizar o PHP, atualize também o WordPress: Dashboard, Updates, Update Now. As versões antigas do WP referenciam a extensão mysql, que foi removida do PHP em 2015, daí o erro.

A propósito de um problema relacionado: se o WordPress se queixar de falta de memória durante a migração, temos uma análise sobre como aumentar o limite de memória PHP no WordPress.

O que mais pode correr mal

Se já tentou os 5 métodos e o erro persiste, aqui estão dois casos extremos.

Linhas desatualizadas no php.ini. Após atualizar o PHP da versão 5.x para a 8.x, o php.ini pode ter linhas residuais extension=mysql.so. No PHP 8, este ficheiro não existe: o módulo foi removido do núcleo. Abra o php.ini e comente ou elimine mysql.so, mysql.dll e libmysql. A lista de extensões removidas está no guia de migração do PHP.

Múltiplas versões do PHP no servidor. Em VPS, o PHP 7.4 e o PHP 8.3 coexistem frequentemente. O comando php -m mostra os módulos para a versão CLI, mas o site pode estar a usar uma diferente, a que está configurada no Apache/FPM. Verifique o info.php: a primeira linha mostra a versão exata do PHP para a web. Instale os pacotes para essa versão.

Um vídeo da equipa da Hostinger mostra a instalação da extensão através do cPanel e da consola, 4 minutos e a imagem fica completamente clara.

⁉️🤔 Perguntas frequentes

Porque é que o erro menciona a extensão MySQL quando é necessário o mysqli?

A mensagem de erro não mudou desde a era do PHP 5.x. Na altura, a extensão chamava-se mysql e o WordPress verificava-a especificamente. No PHP 8.x, a extensão mysql foi completamente removida, o WordPress usa mysqli ou PDO_MySQL. O texto do erro manteve-se o mesmo por razões históricas. Instale o pacote php-mysql: contém o mysqli, pdo_mysql e mysqlnd, tudo o que o WordPress precisa.

É possível corrigir o erro sem acesso ao servidor?

Sim, se o site estiver em alojamento partilhado. Aceda ao painel de controlo (cPanel, Plesk, DirectAdmin), procure «Select PHP Version» ou «PHP Settings», ative o mysqli e o pdo_mysql com as caixas de seleção. O painel reiniciará o PHP automaticamente, não é necessário acesso à consola. Em alojamentos como Hostinger ou Bluehost, estas extensões estão ativas por defeito; se o erro apareceu após mudar de plano, o suporte ativará os módulos em poucos minutos.

O que fazer se o site não funcionar depois de todas as correções?

Verifique três coisas. Primeiro: abra o info.php e confirme que o mysqli aparece com uma versão Client API. A ausência da secção significa que o módulo não carregou, verifique novamente o extension_dir. Segundo: reinicie o servidor web por completo, sudo systemctl restart apache2 (ou nginx mais php-fpm). Terceiro: verifique DB_HOST, DB_NAME, DB_USER e DB_PASSWORD no wp-config.php, por vezes o erro mascara credenciais de base de dados incorretas.

É necessário mudar para MariaDB se o erro se repetir?

Não, substituir o servidor de base de dados não resolve o problema. O erro está exclusivamente relacionado com as extensões PHP. O MariaDB é um fork do MySQL e o WordPress funciona com ele através do mesmo mysqli ou PDO. A maioria dos fornecedores de alojamento já mudou para MariaDB por defeito, os sites WordPress funcionam perfeitamente com ele.

É obrigatório instalar especificamente o PHP 8.3?

Não, qualquer versão PHP 8.x (8.0-8.4) funcionará. O principal é não ser inferior à 7.4. Recomendamos a 8.2 ou 8.3: são ramos estáveis com suporte de segurança ativo em 2026, de acordo com o calendário oficial do PHP. O PHP 8.0 e 8.1 já estão em estado de apenas correções de segurança, e o PHP 7.4 não recebe patches desde novembro de 2022.

Deve entrar em pânico com este erro

O erro «missing MySQL extension» parece assustador, mas essencialmente é um sinal: o servidor não está totalmente configurado. O PHP sem um módulo para trabalhar com bases de dados é como um carro sem chaves de ignição. Os métodos descritos cobrem a esmagadora maioria dos casos, não é necessário um administrador de sistemas.

Depois de corrigir, faça alguma manutenção: elimine o info.php, atualize o WordPress e os plugins para as versões mais recentes, configure cópias de segurança automáticas através do UpdraftPlus ou do painel de alojamento. Assim, a próxima migração ou atualização do PHP decorrerá sem surpresas.