Instala um plugin e ele arrasta consigo a sua própria cópia da jQuery. O seu tema já carregou a jQuery via wp_enqueue_script. O plugin, mais uma vez, carrega-a diretamente a partir de uma CDN. Na página: duas ou até três versões da mesma biblioteca. Conflitos, tamanho inchado, comportamento imprevisível.

O problema é tão antigo quanto o próprio WordPress, mas continua a acontecer: os developers fazem copy-paste de <script src="jquery.js"> no header.php «porque é mais rápido». Mais rápido, até ao primeiro conflito com um plugin que espera a versão nativa do WP.

Em 2026, o WordPress inclui a jQuery 3.6.0 de raiz e fornece uma forma simples e determinística de a incluir sem duplicação e sem gerir versões manualmente. Abaixo está a única abordagem correta, desde o básico wp_enqueue_script até à substituição segura por uma versão de CDN e à utilização do modo noConflict.

💡 Visão geral rápida:

• Como o WordPress já carrega a jQuery e porque não o deve fazer manualmente
• wp_enqueue_script com a dependência jquery: uma linha no functions.php
• Quando e como substituir com segurança a jQuery integrada por uma versão de CDN (Google / cdnjs)
• Modo noConflict: proteção contra colisões com outras bibliotecas
• Dicas para temas e plugins: quando NÃO deve substituir a jQuery integrada

A jQuery já está no core: o que o WordPress faz por si

A partir da versão 3.6, o WordPress regista a jQuery sob o identificador jquery. Não precisa de descarregar o jquery.min.js, colocá-lo na pasta do seu tema e incluí-lo com uma tag <script>. O core faz isto automaticamente assim que especifica jquery nas dependências do seu script.

A versão atual da jQuery no core do WordPress é a 3.6.0. Vem com o jQuery Migrate (para compatibilidade retroativa com código legado) e carrega apenas quando algum script declara jquery como dependência. Sem dependências, a jQuery não aparece na página e o site não carrega recursos desnecessários.

É por isto que um <script src="/wp-content/themes/mytime/jquery.js"> direto no header.php é um erro, não um atalho. Ignora o sistema de dependências, remove a capacidade do WP de gerir a ordem de carregamento e resulta numa duplicação quando um plugin solicita legitimamente a jquery via wp_enqueue_script.

A forma correta: wp_enqueue_script com uma dependência

A mecânica básica cabe numa linha dentro do hook wp_enqueue_scripts. Escreve o seu script e o WordPress trata de quando e em que ordem carregar tudo.

Crie (ou abra) o functions.php do seu tema e adicione:

1
function mytheme_enqueue_scripts() {
2
    wp_enqueue_script(
3
        'mytheme-main',
4
        get_template_directory_uri() . '/js/main.js',
5
        array( 'jquery' ),
6
        '1.0.0',
7
        array(
8
            'strategy'  => 'defer',
9
            'in_footer' => true,
10
        )
11
    );
12
}
13
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

O que está a acontecer aqui:

• mytheme-main é o identificador único para o seu script. Invente o seu, prefixado com o nome do tema.
• get_template_directory_uri() . '/js/main.js' é o caminho para o ficheiro. Também pode usar um URL externo de CDN.
• array( 'jquery' ) é o ponto-chave: está a dizer ao WP «o meu script depende da jQuery». O core vê isto e coloca automaticamente a jQuery na fila antes do seu script. Sem tags <script> no template.
• '1.0.0' é a versão para cache busting. Altere-a a cada atualização do script.
• array( 'strategy' => 'defer', 'in_footer' => true ): desde o WordPress 6.3, o parâmetro $args aceita um array. defer significa «executar o script após a construção do DOM, mas antes do DOMContentLoaded». in_footer coloca o script no footer.

A sintaxe antiga com um quinto parâmetro booleano (true = no footer) ainda funciona, mas para novos projetos use a sintaxe de array. É mais legível e dá-lhe controlo sobre async/defer.

Verifique se o seu tema chama wp_head() antes do fecho de </head> e wp_footer() antes de </body>. Sem estas chamadas, o wp_enqueue_script simplesmente não funciona. Esta é uma armadilha comum ao migrar de temas antigos.

Como substituir a jQuery integrada pela sua própria versão

Por vezes, a versão nativa não é suficiente. Quer a jQuery 4.0.0 de uma CDN para as correções mais recentes ou precisa de uma versão específica para compatibilidade com um plugin legado. Pode substituí-la, mas com cuidado.

O erro: simplesmente chamar wp_enqueue_script('jquery', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'). O WordPress NÃO substitui um identificador já registado. Ficará com a versão nativa E a versão da CDN na mesma página.

A sequência correta: primeiro remova o registo da jquery nativa, depois registe a sua:

1
function mytheme_use_cdn_jquery() {
2
    // Deregister the built-in jQuery
3
    wp_deregister_script( 'jquery' );
4
 
5
    // Register your own — from CDN
6
    wp_register_script(
7
        'jquery',
8
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js',
9
        array(),
10
        '4.0.0',
11
        true
12
    );
13
 
14
    // Enqueue it
15
    wp_enqueue_script( 'jquery' );
16
}
17
add_action( 'wp_enqueue_scripts', 'mytheme_use_cdn_jquery' );

Três pontos frequentemente ignorados:

Google Hosted Libraries. A CDN alternativa do Google ainda está ativa e aloja a jQuery 3.7.1: https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js. A vantagem: milhões de sites já têm as caches do browser aquecidas para este URL. A desvantagem: o Google adiciona os seus próprios cabeçalhos e não atualiza as versões imediatamente após o lançamento.

cdnjs. Se precisar da jQuery 4.0.0, obtenha-a de cdn.jsdelivr.net/npm/[email protected]/. A cdnjs espelha o pacote npm e serve-o com cabeçalhos CORS adequados.

Não remova o registo da jQuery em temas públicos. Se o seu tema for para o repositório WordPress.org, use a jQuery nativa do core. A razão é simples: quando um site tem um tema (com jQuery 4.0.0 de CDN) e um plugin (que espera a jQuery 3.6.0 do core), é o utilizador quem resolve o conflito, não o developer. Em temas comerciais e projetos personalizados, sinta-se à vontade para a substituir.

Modo noConflict: quando há mais do que uma biblioteca na página

Por predefinição, a jQuery ocupa a variável global $. O problema é que $ é um nome popular: Prototype, MooTools e algumas frameworks legadas também o usam. Se um plugin ou outro script também reivindicar $, o que carregou por último ganha e os outros quebram.

Proteção numa linha no início do seu script:

1
var $j = jQuery.noConflict();

Após isto, $ é libertado para outras bibliotecas e o seu código funciona através de $j. Exemplo completo: uma barra lateral com animação hover:

1
jQuery(document).ready( function( $ ) {
2
    // Here $ is jQuery, but only inside this function
3
    $( '#sidebar li a' ).hover(
4
        function() {
5
            $( this ).stop().animate( { paddingLeft: '20px' }, 400 );
6
        },
7
        function() {
8
            $( this ).stop().animate( { paddingLeft: '0' }, 400 );
9
        }
10
    );
11
} );

Aqui, $ funciona como jQuery dentro do closure jQuery(document).ready(), e fora dele está livre para outros. Isto é mais limpo do que espalhar variáveis $j, $jq e $myJQ pelo seu código.

Quando o noConflict não é necessário: se o seu site funciona inteiramente em WordPress sem frameworks JS de terceiros e todos os plugins são escritos para wp_enqueue_script, $ é seguro. Mas incluir o noConflict no boilerplate padrão do seu tema é um bom hábito que custa apenas uma linha.

O que os developers de plugins devem fazer

Se está a escrever um plugin para distribuição pública, use apenas wp_enqueue_script com uma dependência de jquery. Nada de wp_deregister_script('jquery') dentro de plugins: não sabe que versão da jQuery os outros plugins no mesmo site esperam.

O padrão correto para um plugin é este:

1
function myplugin_frontend_scripts() {
2
    wp_enqueue_script(
3
        'myplugin-frontend',
4
        plugins_url( '/js/frontend.js', __FILE__ ),
5
        array( 'jquery' ),
6
        MYPLUGIN_VERSION,
7
        true
8
    );
9
}
10
add_action( 'wp_enqueue_scripts', 'myplugin_frontend_scripts' );

MYPLUGIN_VERSION é a constante de versão do plugin. A cada atualização do plugin, o browser do utilizador recebe um script novo em vez de um antigo em cache.

Para scripts de administração (apenas painel de administração), use o hook admin_enqueue_scripts. A jQuery no admin também está registada sob o mesmo identificador jquery.

⁉️🤔 Perguntas frequentes

Porque é que o meu código jQuery não funciona, mesmo com o wp_enqueue_script chamado corretamente?

A causa mais comum: o tema não chama wp_head() e wp_footer(). Sem estas funções, o WordPress não consegue inserir fisicamente as tags <script> no HTML. Abra o header.php. Deve ter <?php wp_head(); ?> antes de </head>. No footer.php, deve ter <?php wp_footer(); ?> antes de </body>. Se o tema for antigo e estas chamadas estiverem em falta, adicione-as. Isto é seguro. Todos os temas e plugins modernos dependem do wp_head/wp_footer. Sem eles, não só o carregamento de scripts é quebrado, mas também plugins de SEO, fontes e dados estruturados.

Posso usar a jQuery 4.0.0 no WordPress se o core inclui a 3.6.0?

Sim, via wp_deregister_script + wp_register_script (ver secção acima). Mas note: a jQuery 4.0.0 abandonou o suporte ao IE 11 e vários métodos obsoletos. Se o seu site ou plugin depende do jQuery Migrate, mantenha a versão do core ou inclua o Migrate explicitamente. O WordPress está gradualmente a migrar para JavaScript nativo e React para o editor de blocos, mas a jQuery permanecerá no core por muito tempo: demasiados temas e plugins dependem dela.

Um plugin carrega a sua própria jQuery, mesmo eu já a tendo incluído via functions.php. O que devo fazer?

O plugin provavelmente codificou <script src="jquery..."> ignorando o wp_enqueue_script. Isto é um erro do plugin. Duas soluções: encontre a chamada direta no código do plugin e substitua-a por wp_enqueue_script com uma dependência (se estiver disposto a corrigir o plugin), ou contacte o autor do plugin pedindo-lhe para o corrigir. Como solução temporária, pode chamar wp_dequeue_script ou remover o hook do plugin, mas isto trata os sintomas e não a causa.

O que é mais rápido: jQuery do core do WordPress ou de uma CDN?

Se o browser do utilizador já tiver a jQuery em cache de uma CDN (Google ou cdnjs), a versão da CDN carrega instantaneamente com um código 304 Not Modified. Se não, a diferença de velocidade de carregamento entre o core e a CDN é negligenciável para a jQuery (cerca de 85 KB comprimidos). Para projetos de alto tráfego, uma CDN poupa a largura de banda do seu servidor; para um site WordPress típico, não há diferença.

Deve abandonar a jQuery em favor de JS nativo

Resposta curta: depende do projeto. A jQuery 4.0.0 comprimida pesa cerca de 85 KB. Não é zero, mas também não é motivo para pânico. O JS nativo moderno (querySelectorAll, fetch e classList) cobre 90% do que as pessoas precisavam da jQuery em 2015. Se está a construir um tema novo de raiz e não depende de plugins jQuery, considere vanilla JS. É mais limpo e rápido.

Mas se o projeto já tem dependências de jQuery (sliders, galerias, componentes de UI de plugins), não complique. O WordPress carregará a jQuery de qualquer forma quando um plugin a solicitar. Escreva chamadas wp_enqueue_script limpas com dependências, não interfira na gestão da ordem de carregamento do core e a jQuery funcionará de forma rápida e previsível.

🔗 Documentação do wp_enqueue_script | 🔗 Documentação do wp_deregister_script