Como Corrigir Erros de JavaScript no WordPress

Como proprietário de um site WordPress, irá ocasionalmente deparar-se com erros que podem impedir o seu site de funcionar corretamente. Estes problemas de JavaScript podem ser difíceis de resolver, especialmente para iniciantes online.

JavaScript é uma parte crucial dos temas e plugins do WordPress. Isto significa que problemas relacionados com JavaScript podem rapidamente quebrar funcionalidades principais, abrandar o seu site ou afetar a experiência do utilizador.

Neste guia, irei guiá-lo através de como encontrar e corrigir erros de JavaScript no WordPress, desde a sua deteção na consola do navegador até ao isolamento de conflitos de plugins e temas e à execução do WordPress em modo de depuração seguro.

Como Corrigir Erros de JavaScript no WordPress

Normalmente, encontrará a causa de um erro JavaScript em poucos minutos, assim que souber onde procurar. Abaixo estão os cinco locais que verifico primeiro, além de alguns hábitos que ajudam a prevenir que estes erros ocorram no futuro.

Como Identificar e Resolver Problemas de JavaScript

Erros de JavaScript podem ocorrer devido a uma variedade de razões. Mostrarei os melhores locais para procurar e descobrir o que está a causar o problema no seu site.

1. Utilizar as Ferramentas de Desenvolvedor do Navegador

A consola do navegador é a sua melhor amiga quando se trata de identificar erros de JavaScript. Eis como aceder a ela:

Primeiro, abra a página onde está a experienciar o erro de JavaScript. Depois, clique com o botão direito em qualquer parte da página e clique em Inspecionar para abrir o menu de desenvolvedor do seu navegador.

Se preferir usar um atalho de teclado, prima Cmd+Option+J no Mac (ou Ctrl+Shift+J no Windows) para o Chrome. No Firefox, o equivalente é Cmd+Option+K ou Ctrl+Shift+K.

Uma vez aqui, navegue para o separador Console para ver avisos relacionados com JavaScript. Se nenhum erro for exibido, poderá ter de recarregar a página.

Problemas de JavaScript aparecem tipicamente em texto vermelho na consola. Ao resolver problemas, procure mensagens que forneçam pistas sobre qual script, ficheiro ou função está a causar o problema.

Assim que tiver identificado erros de JavaScript na consola, pode rastreá-los até à sua origem. Aqui estão alguns dos erros mais comuns que provavelmente verá na consola do seu navegador.

• Uncaught ReferenceError: jQuery is not defined: Um script tentou usar o jQuery antes de ser carregado, ou nada o carregou. Temas de blocos baseados no Editor de Site não enfileiram o jQuery a menos que um plugin o solicite.
• Uncaught TypeError: $ is not a function: O jQuery carregou em modo noConflict e um script usou o atalho $ mesmo assim. Envolver o trecho numa jQuery(function($) { }) bloco geralmente resolve o problema.
• Uncaught SyntaxError: Um erro de digitação ou um caractere solto no código personalizado. A consola indica o nome do ficheiro e o número da linha, o que normalmente é suficiente para o encontrar.
• Uncaught TypeError: Cannot read properties of undefined: O script foi executado antes que o elemento que ele visa existisse na página. Isto é comum quando um trecho é carregado no cabeçalho em vez do rodapé.
• Um 404 ou net::ERR_ABORTED num ficheiro .js: O ficheiro nunca foi carregado. Verifique a sua CDN, o seu plugin de cache, ou um ficheiro que foi renomeado durante uma atualização.

Na maioria dos casos, o problema mostrará o ficheiro/local de onde a origem do erro. A partir daí, pode dizer se está relacionado com um plugin ou tema.

2. Identificar Conflitos de Plugins ou Temas

A maioria dos erros de JavaScript no WordPress são frequentemente causados por conflitos de plugins ou temas. Se múltiplos plugins ou temas usarem bibliotecas JavaScript incompatíveis ou funções duplicadas, podem criar problemas.

Veja como resolver conflitos:

Conflitos de Temas

Recomendo que mude temporariamente para um tema predefinido do WordPress. Pelo menos um destes temas vem normalmente pré-instalado no seu site WordPress. São sempre nomeados com o ano (por exemplo, Twenty Twenty-Six).

Para ativar um dos temas predefinidos do WordPress, vá a Aparência » Temas no seu painel WordPress. Em seguida, passe o rato sobre um tema predefinido e clique em Ativar.

Se os problemas desaparecerem depois de mudar de tema, é provável que seja um problema com o seu tema WordPress.

A solução imediata é verificar se há atualizações. Se uma nova versão estiver disponível, clique na ligação Atualizar agora para atualizar o seu tema.

Muitas vezes, uma atualização do tema pode ter corrigido problemas críticos de JavaScript. Se o problema persistir, recomendo que contacte o desenvolvedor do tema e mude temporariamente para um novo tema.

O WPForms também documenta os conflitos de temas comuns que surgem com mais frequência.

Conflitos de Plugins

Se mudar para um tema predefinido não resolver o erro, o próximo passo é verificar conflitos de plugins.

Para o fazer, terá de desativar todos os plugins do seu site e verificar se o erro JavaScript persiste. Para um guia mais completo, consulte o nosso guia sobre como testar conflitos de temas ou plugins.

Para isso, vá a Plugins » Plugins Instalados e clique na caixa de seleção para selecionar todos os plugins.

Depois disso, clique na lista suspensa Ações em massa e selecione Desativar.

Em seguida, clique em Aplicar para desativar todos os plugins no seu site WordPress.

Se o erro desaparecer, é provável que um dos seus plugins WordPress seja a causa do problema. Para encontrar o plugin defeituoso, reative os plugins um a um. Para fazer isto, clique em Ativar abaixo do nome do plugin.

Crie o Seu Formulário WordPress Agora

Assim que ativar um plugin, verifique se o erro retorna. O plugin que ativou antes de ver o erro novamente é provavelmente o culpado.

Após identificar o plugin problemático, recomendo verificar se existem atualizações disponíveis. Se houver, certifique-se de que atualiza o plugin.

O desenvolvedor do plugin pode ter lançado uma atualização que resolve o problema. Mas se não houver atualizações disponíveis, considere eliminar o plugin problemático e mudar para um plugin alternativo.

3. Utilizar Ferramentas de Depuração no WordPress

O WordPress inclui ferramentas de depuração integradas que podem ajudá-lo a descobrir problemas de JavaScript. Quando ativa o modo de depuração no seu site, o WordPress exibirá qualquer erro que encontrar no front-end do seu site.

Para ativar o modo de depuração, terá de aceder aos seus ficheiros WordPress no seu servidor, seja através de FTP, cPanel, ou um plugin Gestor de Ficheiros FTP.

Assim que os ficheiros do seu site estiverem abertos, precisará de abrir o ficheiro wp-config.php para edição. Este estará localizado na pasta raiz do seu site. No seu ficheiro wp-config.php, defina WP_DEBUG para true. Isto ativa o modo de depuração do WordPress e regista os erros.

define( 'WP_DEBUG', true );

O WPForms tem um guia mais completo sobre como ativar a depuração no WordPress se desejar mais detalhes sobre as constantes disponíveis para si.

O WordPress inclui também constantes adicionais que permitem depurar outras áreas do software principal. Por exemplo, se pretender ver as versões não minificadas dos scripts principais do WordPress, adicione o seguinte trecho ao editor de código wp-config.php:

define('SCRIPT_DEBUG', true);

Quando SCRIPT_DEBUG está ativado, o WordPress carregará ficheiros como wp-includes/js/script.js em vez de wp-includes/js/script.min.js. Isto pode ser muito útil ao desenvolver ou depurar um site, pois fornece acesso completo ao código para facilitar a inspeção e modificação.

Se pretender armazenar registos de erros num ficheiro em vez de os exibir no frontend do seu site, terá de ativar a constante WP_DEBUG_LOG. Para o fazer, adicione a seguinte linha de código ao seu ficheiro wp-config.php.

define('WP_DEBUG_LOG', true);

Quando WP_DEBUG_LOG está ativado, regista os erros num ficheiro localizado em wp-content/debug.log. Este registo contém frequentemente informações valiosas sobre quais os scripts que estão a funcionar mal.

4. Ativar o Modo de Resolução de Problemas

Se desativar plugins ou mudar de tema afetar o seu site, considere usar o Modo de Resolução de Problemas com ferramentas como o Health Check & Troubleshooting. Para o fazer, terá de instalar e ativar o plugin Health Check & Troubleshooting no seu site.

O plugin permite-lhe ativar o Modo de Resolução de Problemas sem afetar os visitantes do seu site. Esta abordagem é particularmente útil em sites ativos onde não pode dar-se ao luxo de ter tempo de inatividade.

Após ativar o plugin, vá a Ferramentas » Saúde do Site na sua área de administração do WordPress. Em seguida, navegue até ao separador Resolução de Problemas.

Agora, clique no botão Ativar Modo de Resolução de Problemas para continuar.

Isto desativará todos os plugins no seu site e também definirá o seu site para um tema predefinido. Será direcionado para o ecrã do Modo de Resolução de Problemas.

Aqui, pode gerir o seu tema e plugins num ambiente controlado. Se houver algum problema no seu site, verá na secção Avisos.

O seu site usará um tema nativo do WordPress por predefinição após ativar o Modo de Resolução de Problemas.

Sugiro que verifique o seu site para ver se usar um tema predefinido resolve o erro no seu site. Se sim, o problema está provavelmente relacionado com o seu tema WordPress.

Clicar no menu suspenso Plugins disponíveis mostrará todos os plugins no seu site. Aqui, poderá ativar os plugins um de cada vez para verificar conflitos de plugins. Para ativar um plugin, clique em Ativar ao lado do nome do plugin.

Siga os passos na secção resolução de conflitos de plugins deste guia para mais detalhes. Quando terminar de resolver problemas no seu site, clique no botão Desativar Modo de Resolução de Problemas para o devolver ao seu estado original.

5. Verificação de Conflitos de Plugins de Desempenho

Se o erro só aparecer no seu site ao vivo, apenas para visitantes desconectados, ou desaparecer no momento em que desliga a cache, um plugin de desempenho é a causa provável.

Opções como Adiar JavaScript, Atrasar JavaScript, Minificar e Combinar alteram a ordem de execução dos seus scripts. Essa ordem é importante porque o jQuery não pode ser adiado com segurança quando outros scripts esperam que ele esteja pronto primeiro.

Plugins como WP Rocket, LiteSpeed Cache, Autoptimize e Perfmatters incluem estas opções e, muitas vezes, são ativadas por um pacote de otimização de um clique em vez de deliberadamente.

Temas de bloco criados com o Editor de Site não enfileiram o jQuery, a menos que algo o solicite explicitamente. Assim, um trecho que funcionou bem num tema mais antigo pode falhar após a mudança para o Twenty Twenty-Six.

Uma interrupção na CDN faz algo semelhante, desativando os seus scripts sempre que um plugin carrega o jQuery a partir de uma CDN em vez do próprio WordPress.

• Para testar isto, desative toda a otimização de JavaScript no seu plugin de desempenho, limpe toda a cache e recarregue a página.
• Se o erro desaparecer, reative uma opção de cada vez até que ele retorne. Em seguida, adicione o script que falha à lista de exclusão dessa opção.
• Para o próprio jQuery, o caminho a excluir é /wp-includes/js/jquery/jquery.min.js.

Se o WP Rocket for o seu plugin de cache, o WPForms tem um documento sobre como configurar as suas opções de otimização. O documento sobre JavaScript não carregar corretamente abrange uma lista de verificação mais abrangente.

Melhores Práticas para Evitar Erros de JavaScript

Em seguida, partilho algumas dicas para ajudar a proteger o seu site WordPress e a evitar problemas relacionados com JavaScript.

• Mantenha o seu site atualizado: Atualizar regularmente o WordPress, o seu tema e outros plugins pode ajudar a evitar conflitos e bugs. Frequentemente, o problema que encontra terá provavelmente sido resolvido por uma atualização recente do plugin ou tema. Deixar as atualizações acumularem-se é um dos erros mais comuns do WordPress com que me deparo.
• Utilize um tema filho para personalizações: Por vezes, a atualização do seu tema ou plugins irá sobrescrever trechos de código personalizados que adicionou ao seu site. Isto pode resultar em funcionalidades JavaScript quebradas. Utilizar um tema filho garante que os seus trechos personalizados permanecem inalterados.
• Verifique novamente os trechos de JavaScript personalizados: Se adicionou JavaScript personalizado no seu tema ou plugin WordPress, verifique se está formatado corretamente. Verifique também se é compatível com os restantes scripts do seu site. Sugiro envolver o JavaScript inline com uma função ou utilizar jQuery para evitar conflitos.
• Enfileire os scripts corretamente: Se estiver a adicionar quaisquer scripts personalizados, deve enfileirá-los corretamente utilizando as funções do WordPress para evitar problemas de carregamento. Eis um exemplo:

function my_custom_scripts() { 
          wp_enqueue_script('my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery'), null, true); 
} 
add_action('wp_enqueue_scripts', 'my_custom_scripts');

• Teste em vários navegadores: Os navegadores modernos padronizaram largamente as suas implementações de JavaScript. No entanto, é ainda importante testar o seu site em diferentes navegadores, incluindo versões mais antigas do Internet Explorer. Isto pode ajudar a identificar problemas específicos do navegador no início do processo de desenvolvimento web.
• Implemente tratamento de erros adequado: Boas práticas de tratamento de erros no seu trecho de JS personalizado podem evitar que muitos problemas causem grandes perturbações. Isto inclui a utilização de blocos try-catch e a oferta de opções de fallback sempre que possível.

Em seguida, Explore os Melhores Plugins para Usar no WordPress

Neste post, mostrei como identificar e corrigir erros de JavaScript no WordPress. Como regra geral, lembre-se de manter os plugins e temas atualizados e seguir as melhores práticas ao adicionar JavaScript personalizado.

Além disso, certifique-se de usar plugins recomendados no seu site WordPress e evite usar versões nulled de plugins como o plugin nulled WPForms Pro.

Crie o Seu Formulário WordPress Agora

Pronto para construir o seu formulário? Comece hoje com o plugin construtor de formulários WordPress mais fácil. O WPForms Pro inclui muitos modelos gratuitos e oferece uma garantia de devolução do dinheiro em 14 dias.

Se este artigo o ajudou, por favor siga-nos no Facebook e Twitter para mais tutoriais e guias gratuitos do WordPress.