Instaluje Pan/Pani wtyczkę, a ta ciągnie swoją kopię jQuery. Pana/Pani motyw już załadował jQuery przez wp_enqueue_script. Wtyczka, jeszcze raz, bezpośrednio z CDN. Na stronie dwie, a nawet trzy wersje tej samej biblioteki. Konflikty, rozdęty rozmiar, nieprzewidywalne zachowanie.

Problem jest stary jak sam WordPress, ale wciąż się odtwarza: deweloperzy kopiują i wklejają <script src="jquery.js"> do header.php, „bo tak szybciej". Szybciej, do pierwszego konfliktu z wtyczką, która oczekuje natywnej wersji WP.

Od 2026 roku WordPress dostarcza jQuery 3.6.0 w pakiecie i daje prosty, deterministyczny sposób podłączania, bez duplikacji, bez ręcznego śledzenia wersji. Poniżej jedyna właściwa ścieżka, od podstawowego wp_enqueue_script do bezpiecznej zamiany na wersję CDN i trybu noConflict.

💡 Szybki przegląd:

• Jak WordPress już ładuje jQuery i dlaczego nie trzeba robić tego ręcznie
• wp_enqueue_script z zależnością jquery, jedna linijka w functions.php
• Kiedy i jak bezpiecznie zastąpić wbudowane jQuery wersją CDN (Google / cdnjs)
• Tryb noConflict: ochrona przed kolizjami z innymi bibliotekami
• Wskazówki dla motywów i wtyczek: kiedy NIE należy wyrejestrowywać wbudowanego jQuery

JQuery jest już w jądrze: co WordPress robi za Pana/Panią

Począwszy od wersji 3.6, WordPress rejestruje jQuery pod uchwytem jquery. Nie musi Pan/Pani ładować jquery.min.js, umieszczać go w folderze motywu i podłączać tagiem <script>, jądro zrobi to samo, gdy tylko wskaże Pan/Pani jquery w zależnościach swojego skryptu.

Bieżąca wersja jQuery w jądrze WordPress to 3.6.0. Jest ona dostarczana razem z jQuery Migrate (dla wstecznej kompatybilności ze starym kodem) i ładuje się tylko wtedy, gdy jakiś skrypt zadeklarował jquery jako zależność. Jeśli nie ma zależności, jQuery nie trafia na stronę, witryna nie ładuje zbędnych zasobów.

Oto dlaczego bezpośredni <script src="/wp-content/themes/mytime/jquery.js"> w header.php jest błędem, a nie skrótem. Omija Pan/Pani system zależności, pozbawia WP możliwości zarządzania kolejnością i otrzymuje duplikat, gdy wtyczka uczciwie poprosi o jquery przez wp_enqueue_script.

Właściwy sposób: wp_enqueue_script z zależnością

Podstawowa mechanika mieści się w jednej linijce wewnątrz haka wp_enqueue_scripts. Pisze Pan/Pani swój skrypt, a WordPress sam rozstrzyga, kiedy i w jakiej kolejności wszystko załadować.

Proszę utworzyć (lub otworzyć) functions.php swojego motywu i dodać:

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' );

Co tu się dzieje:

• mytheme-main, unikalny uchwyt Pana/Pani skryptu. Proszę wymyślić własny, z prefiksem motywu.
• get_template_directory_uri() . '/js/main.js', ścieżka do pliku. Może to być również zewnętrzny URL CDN.
• array( 'jquery' ), kluczowy moment: mówi Pan/Pani WP „mój skrypt zależy od jQuery". Jądro widzi to i automatycznie ustawia jQuery w kolejce przed Pana/Pani skryptem. Żadnych tagów <script> w szablonie.
• '1.0.0', wersja do unieważniania cache. Proszę zmieniać przy każdej aktualizacji skryptu.
• array( 'strategy' => 'defer', 'in_footer' => true ), od WordPress 6.3 parametr $args przyjmuje tablicę. defer oznacza „wykonaj skrypt po zbudowaniu DOM, ale przed DOMContentLoaded". in_footer umieszcza skrypt w stopce.

Stara składnia z logicznym piątym parametrem (true = w stopce) nadal działa, ale dla nowych projektów proszę używać tablicy, czyta się ją czytelniej i daje kontrolę nad async/defer.

Proszę sprawdzić, czy Pana/Pani motyw wywołuje wp_head() przed zamykającym </head> i wp_footer() przed </body>. Bez tych wywołań wp_enqueue_script po prostu nie zadziała, to częsta pułapka przy przechodzeniu ze starych motywów.

Jak zastąpić wbudowane jQuery własną wersją

Czasami natywna wersja nie wystarcza. Chce Pan/Pani jQuery 4.0.0 z CDN dla najświeższych poprawek albo potrzebuje Pan/Pani konkretnej wersji dla kompatybilności ze starą wtyczką. Zastąpić można, ale ostrożnie.

Błąd: po prostu wywołać wp_enqueue_script('jquery', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'). WordPress NIE nadpisuje już zarejestrowanego uchwytu, otrzyma Pan/Pani natywną wersję ORAZ wersję CDN na jednej stronie.

Prawidłowa kolejność: najpierw wyrejestrować natywny jquery, potem zarejestrować swój:

1
function mytheme_use_cdn_jquery() {
2
    // Снимаем встроенную jQuery
3
    wp_deregister_script( 'jquery' );
4
 
5
    // Регистрируем свою — из 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
    // Ставим в очередь
15
    wp_enqueue_script( 'jquery' );
16
}
17
add_action( 'wp_enqueue_scripts', 'mytheme_use_cdn_jquery' );

Trzy punkty, o których często się zapomina:

Google Hosted Libraries. Alternatywny CDN od Google wciąż działa i utrzymuje jQuery 3.7.1: https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js. Plus: miliony witryn już nagrzewają cache przeglądarki pod tym URL-em. Minus: Google dodaje własne nagłówki i aktualizuje wersje nie od razu po wydaniu.

cdnjs. Jeśli potrzebna jest jQuery 4.0.0, proszę brać z cdn.jsdelivr.net/npm/[email protected]/. cdnjs mirroruje pakiet npm i serwuje z poprawnymi nagłówkami CORS.

Proszę nie wyrejestrowywać jQuery w publicznych motywach. Jeśli Pana/Pani motyw trafia do repozytorium WordPress.org, proszę używać natywnego jQuery z jądra. Powód jest prosty: gdy na jednej witrynie spotykają się motyw (z CDN jQuery 4.0.0) i wtyczka (oczekująca jQuery 3.6.0 z jądra), konflikt rozwiązuje użytkownik, a nie deweloper. W motywach komercyjnych i projektach niestandardowych proszę zastępować śmiało.

Tryb noConflict: gdy na stronie jest więcej niż jedna biblioteka

jQuery domyślnie zajmuje globalną zmienną $. Problem w tym, że $ to popularna nazwa: używają jej Prototype, MooTools i niektóre stare frameworki. Jeśli wtyczka lub drugi skrypt również rości sobie prawo do $, wygrywa ten, który załadował się ostatni, reszta się psuje.

Ochrona, jedna linijka na początku Pana/Pani skryptu:

1
var $j = jQuery.noConflict();

Po tym $ zostaje zwolnione dla innych bibliotek, a Pana/Pani kod działa przez $j. Pełny przykład, panel boczny z animacją przy najechaniu:

1
jQuery(document).ready( function( $ ) {
2
    // Здесь $ — это jQuery, но только внутри этой функции
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
} );

Tutaj $ działa jako jQuery wewnątrz domknięcia jQuery(document).ready(), a na zewnątrz jest wolny dla innych. To czystsze rozwiązanie niż tworzenie zmiennych $j, $jq i $myJQ w całym kodzie.

Kiedy noConflict nie jest potrzebny: jeśli Pana/Pani witryna jest w całości na WordPressie, bez zewnętrznych frameworków JS, a wszystkie wtyczki są napisane pod wp_enqueue_script, $ jest bezpieczny. Jednak włączanie noConflict do standardowego szablonu startowego motywu to dobry nawyk, którego koszt to jedna linijka.

Co powinien zrobić deweloper wtyczek

Jeśli pisze Pan/Pani wtyczkę do publicznej dystrybucji, proszę używać tylko wp_enqueue_script z zależnością od jquery. Żadnych wp_deregister_script('jquery') wewnątrz wtyczek: nie wie Pan/Pani, jakiej wersji jQuery oczekują inne wtyczki na tej samej witrynie.

Prawidłowy wzorzec dla wtyczki wygląda tak:

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, stała wersji wtyczki. Przy każdej aktualizacji wtyczki przeglądarka użytkownika otrzyma świeży skrypt, a nie stary z cache.

Skrypty administracyjne (tylko w panelu administracyjnym) proszę podpinać na hak admin_enqueue_scripts, jQuery w panelu administracyjnym również jest zarejestrowane pod tym samym uchwytem jquery.

⁉️🤔 Często zadawane pytania

Dlaczego mój kod jQuery nie działa, mimo że wp_enqueue_script zostało wywołane poprawnie?

Najczęstsza przyczyna: motyw nie wywołuje wp_head() i wp_footer(). Bez tych funkcji WordPress fizycznie nie może wstawić tagów <script> do HTML. Proszę otworzyć header.php, powinno tam być <?php wp_head(); ?> przed </head>. W footer.php, <?php wp_footer(); ?> przed </body>. Jeśli motyw jest stary i nie ma tych wywołań, proszę je dodać, to bezpieczne. Wszystkie nowoczesne motywy i wtyczki polegają na wp_head/wp_footer, bez nich zepsute jest nie tylko podłączanie skryptów, ale także wtyczki SEO, czcionki i mikrodane.

Czy można używać jQuery 4.0.0 w WordPressie, skoro jądro dostarcza 3.6.0?

Tak, przez wp_deregister_script + wp_register_script (patrz sekcja powyżej). Proszę jednak wziąć pod uwagę: jQuery 4.0.0 usunęło wsparcie dla IE 11 i szereg przestarzałych metod. Jeśli Pana/Pani witryna lub wtyczka polega na jQuery Migrate, proszę pozostać przy wersji z jądra lub jawnie podłączyć Migrate. WordPress stopniowo zmierza w stronę natywnego JavaScript i React dla edytora bloków, ale jQuery pozostanie w jądrze jeszcze długo: zbyt wiele motywów i wtyczek od niego zależy.

Wtyczka ciągnie swoje jQuery, chociaż już podłączyłem przez functions.php, co robić?

Wtyczka najprawdopodobniej na sztywno wstawiła <script src="jquery..."> z pominięciem wp_enqueue_script. To błąd wtyczki. Są dwa rozwiązania: znaleźć w kodzie wtyczki bezpośrednie wywołanie i zastąpić je wp_enqueue_script z zależnością (jeśli jest Pan/Pani gotów patchować wtyczkę) albo napisać do autora wtyczki z prośbą o poprawkę. Jako tymczasowe obejście można wywołać wp_dequeue_script lub usunąć hak wtyczki, ale to leczy objawy, a nie przyczynę.

Co jest szybsze: jQuery z jądra WordPress czy z CDN?

Jeśli przeglądarka użytkownika już zbuforowała jQuery z CDN (Google lub cdnjs), wersja CDN załaduje się natychmiast, z kodem 304 Not Modified. Jeśli nie, różnica w szybkości ładowania między jądrem a CDN jest pomijalnie mała dla jQuery (plik około 85 KB po gzip). Dla projektów o dużym obciążeniu CDN oszczędza transfer na Pana/Pani serwerze; dla typowej witryny na WordPressie nie ma różnicy.

Czy warto rezygnować z jQuery na rzecz natywnego JS

Krótka odpowiedź: zależy od projektu. jQuery 4.0.0 w skompresowanej formie waży około 85 KB, to nie zero, ale też nie powód do paniki. Nowoczesny natywny JS: querySelectorAll, fetch i classList pokrywają 90% tego, po co sięgało się po jQuery w 2015 roku. Jeśli pisze Pan/Pani nowy motyw od zera i nie zależy Pan/Pani od wtyczek jQuery, proszę rozważyć vanilla JS, jest czystszy i szybszy.

Ale jeśli w projekcie są już zależności jQuery (slidery, galerie, komponenty UI wtyczek), proszę nie komplikować. WordPress i tak załaduje jQuery, gdy wtyczka o nią poprosi. Proszę pisać staranne wp_enqueue_script z zależnościami, nie przeszkadzać jądru w zarządzaniu kolejnością, a jQuery będzie działać szybko i przewidywalnie.

🔗 Dokumentacja wp_enqueue_script | 🔗 Dokumentacja wp_deregister_script