Como Corrigir o Erro max_execution_time no WordPress

O erro max_execution_time no WordPress ocorre quando um script PHP excede a duração máxima de execução configurada ao nível do servidor. O PHP termina o script e retorna um erro fatal, que o WordPress apresenta como um ecrã branco, um aviso de timeout, ou uma mensagem explícita de "Maximum execution time exceeded".

Por padrão, a maioria dos ambientes de alojamento partilhado impõe um limite de 30 segundos. Operações como importar um CSV de produtos WooCommerce, executar uma cópia de segurança completa do site, ou instalar um pacote de plugins de grande dimensão podem facilmente ultrapassar este limite. Aumentar o limite — através de php.ini, .htaccess, wp-config.php, ou da camada de plugins do WordPress — resolve o erro sem comprometer a estabilidade do servidor quando feito corretamente.

Compreender Por Que o Limite Existe e Quando Se Torna um Problema

A diretiva max_execution_time do PHP é um mecanismo de proteção de recursos, não uma restrição arbitrária. Impede que um script descontrolado monopolize o tempo de CPU num conjunto de processos partilhados, o que é especialmente crítico em infraestruturas multi-tenant.

O limite torna-se um obstáculo real nestes cenários:

• Importações ou exportações de bases de dados de grande dimensão via phpMyAdmin ou WP-CLI que processam milhares de linhas
• Instalações de plugins ou temas que descomprimem arquivos superiores a 50 MB
• Operações em massa no WooCommerce — atualizações de preços, sincronizações de inventário, exportações de encomendas
• Migrações completas do site usando ferramentas como Duplicator ou All-in-One WP Migration
• Tarefas cron agendadas que agregam dados de APIs externas
• Plugins de otimização de imagens que processam centenas de uploads não otimizados num único lote

Uma nuance crítica que a maioria dos guias omite: max_execution_time mede o tempo de CPU consumido pelo processo PHP, não o tempo real decorrido. Num servidor com carga elevada, um script pode correr durante 90 segundos reais enquanto consome apenas 28 segundos de tempo de CPU e nunca acionar o limite. Por outro lado, um ciclo intensivo em CPU atinge o limite mais rapidamente do que o esperado. Esta distinção é importante ao diagnosticar timeouts intermitentes.

Como Verificar o Valor Atual de max_execution_time

Antes de alterar qualquer coisa, confirme o limite ativo. Crie um ficheiro temporário na raiz do seu WordPress — nunca o deixe publicamente acessível após os testes:

<?php
phpinfo();

Carregue-o como phpinfo-test.php, visite https://yourdomain.com/phpinfo-test.php, e procure max_execution_time no resultado. Elimine o ficheiro imediatamente após a verificação.

Em alternativa, use WP-CLI via SSH:

wp eval 'echo ini_get("max_execution_time");'

Isto retorna o valor atualmente ativo para pedidos WordPress, que pode diferir do php.ini global do servidor se já existir uma substituição por diretório em vigor.

Método 1: Editar o Ficheiro php.ini (Mais Fiável)

Modificar o php.ini é o método mais autoritativo porque define a diretiva ao nível do interpretador PHP, sem substituir nada e sem ser substituído por nada abaixo na hierarquia de configuração — a menos que uma chamada posterior a ini_set() o substitua em tempo de execução.

Passo 1: Localizar o Ficheiro php.ini Correto

É aqui que a maioria dos administradores comete um erro. O PHP pode carregar múltiplos ficheiros .ini dependendo do SAPI (Server API) em uso:

• CLI SAPI (/etc/php/8.x/cli/php.ini) — usado pelo WP-CLI e tarefas cron
• FPM SAPI (/etc/php/8.x/fpm/php.ini) — usado por stacks Nginx + PHP-FPM
• Apache mod_php (/etc/php/8.x/apache2/php.ini) — usado pelo Apache com o módulo PHP

Editar o php.ini do CLI resolverá os timeouts do WP-CLI mas não afetará os pedidos iniciados pelo browser. Identifique sempre o SAPI correto primeiro:

php -i | grep "Loaded Configuration File"

Para pedidos web, verifique o resultado do phpinfo() em Loaded Configuration File.

Passo 2: Editar ou Criar php.ini na Raiz Web

Em alojamento partilhado onde não tem acesso root, pode colocar um php.ini ao nível do utilizador no diretório raiz do seu site (public_html). Aceda-lhe via cPanel File Manager, FTP, ou SSH:

nano ~/public_html/php.ini

Adicione ou atualize a diretiva:

max_execution_time = 300

300 segundos (5 minutos) é suficiente para a maioria das operações. Para migrações extremamente grandes, considere 600 segundos temporariamente e reverta assim que a tarefa estiver concluída.

Passo 3: Verificar se a Alteração Entrou em Vigor

Após guardar, execute novamente a verificação phpinfo() ou o comando WP-CLI anterior. Se o valor não tiver mudado, o seu host pode estar a impor um limite rígido via max_execution_time num php.ini ao nível do servidor que substitui o seu ficheiro ao nível do utilizador. Nesse caso, avance para o Método 4.

Passo 4: Reiniciar o PHP-FPM (VPS e Servidores Dedicados)

Num VPS ou servidor dedicado onde controla o ambiente, é necessário reiniciar o PHP-FPM para que a alteração se propague para os pedidos web:

sudo systemctl restart php8.2-fpm

Substitua php8.2-fpm pela sua versão PHP instalada. O Apache com mod_php requer um reload do Apache em vez disso:

sudo systemctl reload apache2

Método 2: Editar o Ficheiro .htaccess (Apenas Apache)

O método .htaccess funciona exclusivamente em servidores Apache onde AllowOverride permite diretivas de configuração PHP. Não funciona em Nginx, LiteSpeed com determinadas configurações, ou qualquer stack onde o PHP corre como FastCGI/FPM com AllowOverride None.

Passo 1: Revelar e Aceder ao Ficheiro .htaccess

O ficheiro .htaccess está oculto por padrão. No cPanel File Manager, clique em Settings no canto superior direito e ative Show Hidden Files (dotfiles). O ficheiro encontra-se em public_html.

Via SSH:

nano ~/public_html/.htaccess

Passo 2: Adicionar a Diretiva PHP

Insira a seguinte linha. A posição é importante — coloque-a fora de qualquer bloco <IfModule> para garantir que se aplica globalmente:

php_value max_execution_time 300

Se o seu servidor correr PHP-FPM (identificável por PHP/x.x.x (fpm-fcgi) em phpinfo()), esta diretiva causará um Erro 500 Internal Server Error porque php_value não é válido nesse contexto. Use php_admin_value apenas se o host o permitir explicitamente, ou mude para o Método 1.

Passo 3: Testar Erros 500

Após guardar, carregue imediatamente a sua página inicial. Um erro 500 significa que a diretiva é incompatível com a configuração do seu servidor. Remova a linha e use um método alternativo.

Método 3: Editar wp-config.php Usando set_time_limit()

A função set_time_limit() reinicia o temporizador de execução a partir do ponto em que é chamada. Trata-se de uma chamada em tempo de execução PHP, não de uma diretiva de configuração, o que significa que funciona independentemente de o servidor permitir substituições php.ini ou .htaccess — desde que a lista disable_functions do PHP não a inclua.

Passo 1: Localizar wp-config.php

O ficheiro encontra-se na raiz da instalação WordPress, um nível acima de public_html em algumas configurações de servidor, ou diretamente dentro dela noutras.

find ~/public_html -maxdepth 2 -name "wp-config.php"

Passo 2: Adicionar a Diretiva

Abra wp-config.php e adicione a seguinte linha antes do comentário /* That's all, stop editing! Happy publishing. */:

set_time_limit(300);

Chamar set_time_limit(0) desativa o limite completamente para esse pedido. Use isto apenas como medida de diagnóstico temporária — nunca em produção — porque remove a proteção contra ciclos infinitos.

Aviso importante: set_time_limit() afeta apenas a execução do script atual. Não altera a configuração PHP global do servidor. Se um plugin internamente iniciar um subprocesso ou fizer um pedido HTTP bloqueante, esse subprocesso não é abrangido por esta chamada.

Método 4: Usar um Plugin WordPress

Para utilizadores que preferem não editar ficheiros do servidor diretamente, vários plugins expõem valores de configuração PHP através da interface de administração do WordPress. Esta abordagem é adequada para proprietários de sites não técnicos em alojamento gerido.

Opções recomendadas:

• WP Maximum Execution Time Exceeded — visa especificamente este erro e tenta múltiplos métodos de substituição
• PHP Settings — fornece uma vista de painel das diretivas PHP ativas e permite substituições seguras onde o host o permitir

Para instalar: navegue até Plugins > Adicionar Novo no painel WordPress, procure o nome do plugin, instale e ative. Siga a página de definições do plugin para definir o tempo de execução desejado.

Limitação: Os plugins só podem chamar set_time_limit() ou ini_set() em tempo de execução. Se o host tiver bloqueado max_execution_time via restrições open_basedir ou uma configuração de servidor codificada, o plugin falhará silenciosamente ao aumentar o limite. Verifique sempre a alteração usando phpinfo() após a ativação.

Método 5: Contactar o Seu Fornecedor de Alojamento

Se nenhum dos métodos acima produzir uma alteração verificada no resultado phpinfo(), o limite é imposto ao nível do servidor pelo seu host. Isto é comum em planos de alojamento partilhado de entrada onde o fornecedor define um limite rígido para proteger os recursos partilhados.

Ao contactar o suporte, forneça:

• A mensagem de erro exata e a ação WordPress que a desencadeia
• O valor atual de max_execution_time obtido em phpinfo()
• O valor de que necessita (por exemplo, 300 segundos) e o motivo (por exemplo, importação WooCommerce de grande dimensão)

Hosts de confiança irão ajustar o limite para a sua conta ou indicar-lhe uma opção no painel de controlo (como um seletor PHP no cPanel) onde pode configurá-lo você mesmo.

Comparação dos Cinco Métodos

Diagnosticar Timeouts Persistentes Após Aumentar o Limite

Se confirmou que o novo limite está ativo em phpinfo() mas o erro persiste, o bottleneck provavelmente não é max_execution_time. Considere estas causas alternativas:

Diretivas de timeout FastCGI ou Nginx — O Nginx tem a sua própria diretiva fastcgi_read_timeout, separada do PHP:

fastcgi_read_timeout 300;

Isto deve ser definido no bloco de servidor Nginx e requer um reload do Nginx.

Diretiva TimeOut do Apache — O próprio timeout de ligação do Apache pode terminar um pedido antes de o limite do PHP ser atingido:

TimeOut 300

request_terminate_timeout do PHP-FPM — Na configuração do pool PHP-FPM (/etc/php/8.x/fpm/pool.d/www.conf), esta diretiva mata independentemente os processos worker:

request_terminate_timeout = 300

wait_timeout e interactive_timeout do MySQL — Consultas de base de dados de longa duração podem fazer com que a ligação MySQL caia a meio da execução, que o PHP apresenta como uma falha de script em vez de um erro de base de dados. Verifique com:

SHOW VARIABLES LIKE '%timeout%';

Timeouts ao nível do WooCommerce ou de plugins — Alguns plugins implementam a sua própria lógica de timeout interna usando set_time_limit() do PHP com um valor inferior, o que reinicia o contador e pode substituir a sua configuração.

Considerações de Desempenho e Boas Práticas

Aumentar max_execution_time é uma correção direcionada, não uma solução arquitetural permanente. Se uma operação específica excede rotineiramente 30–60 segundos, o processo subjacente deve ser otimizado ou reestruturado:

• Processamento em lotes: Divida importações grandes em partes menores usando chunking baseado em AJAX (como o WP All Import faz nativamente) em vez de processar tudo num único pedido HTTP
• Processamento em segundo plano: Use WP-Cron ou uma fila de tarefas adequada (Action Scheduler, usado pelo WooCommerce) para mover trabalho de longa duração para fora do ciclo de vida do pedido web
• WP-CLI para operações em massa: A execução via CLI não está sujeita a timeouts do servidor web e é a ferramenta correta para importações de bases de dados, operações de pesquisa e substituição, e processamento em massa de media
• Otimizar consultas lentas: Use o plugin Query Monitor para identificar consultas de base de dados que consomem tempo de execução desproporcionado
• Atualizar o nível de alojamento: Se a sua carga de trabalho requer consistentemente tempos de execução alargados, um VPS com cPanel dá-lhe controlo total sobre a configuração PHP e recursos dedicados que não competem com outros inquilinos

Para cargas de trabalho de alto processamento como recomendações de produtos baseadas em IA ou pipelines de processamento de imagens em grande escala, o alojamento GPU descarrega o processamento intensivo completamente da camada PHP.

Lista de Verificação Prática

Use esta lista de verificação antes e depois de aplicar qualquer correção:

• Confirme o valor atual de max_execution_time via phpinfo() ou WP-CLI antes de fazer alterações
• Identifique o seu stack de servidor (Apache + mod_php, Apache + FPM, Nginx + FPM) antes de escolher um método
• Aplique apenas um método de cada vez — acumular alterações em php.ini, .htaccess e wp-config.php simultaneamente torna a depuração impossível
• Após aplicar uma alteração, verifique novamente o valor ativo em phpinfo() — não assuma que a alteração funcionou
• Teste reproduzindo a ação original que falhou, não apenas carregando a página inicial
• Se o erro for resolvido, considere se a operação subjacente pode ser otimizada para correr dentro do limite original
• Defina um lembrete no calendário para reverter quaisquer aumentos temporários de limite (por exemplo, set_time_limit(0)) após a conclusão da tarefa pontual
• Em alojamento partilhado, documente o que o host confirmou como o valor máximo permitido para o seu plano
• Se os timeouts persistirem após confirmar que o limite PHP foi aumentado, audite fastcgi_read_timeout do Nginx, TimeOut do Apache e request_terminate_timeout do PHP-FPM de forma independente

FAQ

Qual é o valor mais seguro a definir para max_execution_time no WordPress?

300 segundos (5 minutos) cobre a grande maioria das operações WordPress com uso intensivo de recursos, incluindo instalações de plugins de grande dimensão, importações WooCommerce e atualizações de temas. Valores acima de 600 segundos devem ser tratados como temporários e revertidos após a conclusão da tarefa específica.

Por que a minha alteração a max_execution_time não aparece em phpinfo() após editar php.ini?

Provavelmente está a editar o ficheiro php.ini errado. O PHP carrega diferentes ficheiros de configuração para CLI, Apache mod_php e PHP-FPM. Execute php -i | grep "Loaded Configuration File" para CLI e verifique a linha Loaded Configuration File numa página phpinfo() acessível pelo browser para identificar o ficheiro correto para pedidos web.

Aumentar max_execution_time afeta todos os utilizadores no meu servidor?

Num servidor partilhado, editar um php.ini ao nível do utilizador na sua raiz web afeta apenas a sua conta. Editar o php.ini global do servidor (que requer acesso root) afeta todos os processos PHP nesse servidor. Num servidor dedicado, controla a configuração global e é totalmente responsável pelo seu impacto.

O método .htaccess funcionará num servidor Nginx?

Não. O ficheiro .htaccess é um mecanismo específico do Apache. O Nginx não processa ficheiros .htaccess. Em stacks Nginx + PHP-FPM, deve editar a configuração do pool PHP-FPM ou o php.ini ao nível do servidor, ambos os quais requerem acesso SSH.

Um plugin WordPress pode aumentar permanentemente max_execution_time?

Não. Os plugins executam dentro do runtime PHP e só podem chamar set_time_limit() ou ini_set(), que afetam apenas o pedido atual. Não podem escrever em php.ini nem persistir alterações de configuração entre pedidos. Para um aumento permanente, deve modificar php.ini, .htaccess, ou um ficheiro de configuração de pool PHP-FPM ao nível do servidor.