www.jQueryBook.ru - jQuery документация

  

 

 

 



Как подключить jQuery: CDN, локальный файл, npm и WordPress

Опубликовано: 26.09.2026 · Обновлено: 26.09.2026 · Актуально для jQuery 3.7.1 и 4.0.0

Самый быстрый способ подключить jQuery — вставить один тег <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script> перед своим кодом: библиотека загрузится с официального CDN, и $ станет доступен на странице. Дальше — варианты для локального файла, npm-проектов и WordPress, а также разбор ошибки $ is not defined и других типичных проблем подключения.

Содержание

  1. Какую версию выбрать
  2. Подключение с CDN
  3. Локальный файл
  4. npm и сборщики
  5. jQuery в WordPress
  6. Проверка, что jQuery загрузился
  7. Готовность DOM
  8. Частые ошибки
  9. Чек-лист

Какую версию выбрать

На сентябрь 2026 года актуальны две ветки: jQuery 4.0.0 — основная линия разработки, и jQuery 3.7.1 — последний релиз ветки 3.x, которую многие держат из-за более широкой совместимости со старыми плагинами. Разница между ними в первую очередь в удалённых устаревших API (подробности — в статье что нового в jQuery 4.0), а не в наборе базовых возможностей, поэтому для нового проекта без старых плагинов разумно сразу брать 4.0.0.

У каждой версии есть полная сборка и облегчённая slim. Slim не включает Ajax и эффекты, а в 4.0 из неё дополнительно убрали модули Deferred, Callbacks и Queue, на которых эти функции построены. Если сайт использует jQuery только для выборки элементов и работы с DOM — берите slim, файл будет заметно легче.

СборкаЧто внутриКогда брать
jquery-4.0.0.min.jsПолный набор: DOM, события, Ajax, эффекты, DeferredНужны $.ajax(), .animate(), старые плагины на Deferred
jquery-4.0.0.slim.min.jsБез Ajax, эффектов, Deferred/Callbacks/QueueТолько выборка и манипуляции с DOM, современный код без jQuery-плагинов на Deferred
jquery-3.7.1.min.jsПолный набор, как в 4.0, но с сохранёнными устаревшими APIСтарые плагины и код, ещё не проверенные на совместимость с 4.0
jquery-3.7.1.slim.min.jsБез Ajax и эффектов (Deferred/Callbacks остаются)То же, что и slim 4.0, но нужна совместимость с 3.x-плагинами

Если на сайте много старых плагинов, не проверяйте совместимость с 4.0 «на глаз» — сначала прогоните через jQuery Migrate в тестовом окружении и посмотрите предупреждения в консоли, а уже потом переключайте прод.

Подключение с CDN

Проще всего вставить готовый тег <script> с одного из CDN. Официальный вариант — code.jquery.com, у него всегда актуальные файлы и есть теги с готовым SRI-хэшем на странице releases.jquery.com. Также jQuery зеркалируют cdnjs и jsDelivr — они бывают полезны, если основной CDN недоступен.

CDNURL для jQuery 4.0.0URL для jQuery 3.7.1
code.jquery.com (официальный)https://code.jquery.com/jquery-4.0.0.min.jshttps://code.jquery.com/jquery-3.7.1.min.js
cdnjshttps://cdnjs.cloudflare.com/ajax/libs/jquery/4.0.0/jquery.min.jshttps://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js
jsDelivrhttps://cdn.jsdelivr.net/npm/jquery@4.0.0/dist/jquery.min.jshttps://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js

Пример подключения с официального CDN:

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script>
  // ваш код, использующий $, идёт ниже
</script>

У тега со страницы releases.jquery.com есть ещё два атрибута — integrity и crossorigin="anonymous". Это механизм Subresource Integrity (SRI): браузер сверяет хэш скачанного файла с указанным в атрибуте и откажется выполнять скрипт, если файл был подменён на CDN или по пути к нему. Хэш привязан к конкретной версии файла, поэтому его нельзя придумать или взять «примерно такой же» — берите его только с официальной страницы для нужной версии:

<!-- jQuery 4.0.0, минифицированная полная сборка -->
<script src="https://code.jquery.com/jquery-4.0.0.min.js"
  integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao="
  crossorigin="anonymous"></script>

<!-- jQuery 3.7.1, минифицированная полная сборка -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"
  integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo="
  crossorigin="anonymous"></script>

Хэш относится к конкретному файлу: у jquery-4.0.0.js, jquery-4.0.0.slim.min.js и других сборок он свой. Для другой версии или сборки копируйте готовый тег на releases.jquery.com — не правьте номер версии в адресе, оставив старый integrity: браузер тогда просто не выполнит скрипт. Тот же файл на jsDelivr (npm/jquery@4.0.0/dist/jquery.min.js) имеет тот же хэш.

Отдельно про Google Hosted Libraries (ajax.googleapis.com): этот CDN исторически был самым популярным способом подключить jQuery и до сих пор встречается в старых шаблонах, но новые версии появляются там с задержкой. Прежде чем прописывать адрес с 4.0, проверьте наличие нужной версии в каталоге developers.google.com/speed/libraries; надёжнее брать 4.0 с code.jquery.com, cdnjs или jsDelivr.

Для аудитории из РФ имеет смысл держать в запасе локальную копию файла: доступность зарубежных CDN у части провайдеров и клиентских сетей может быть нестабильной, и сайт не должен разваливаться из-за того, что не загрузился один внешний скрипт. Ниже — рабочий вариант с фолбэком на локальный файл.

Локальный файл

Скачайте нужный файл (например, jquery-4.0.0.min.js с code.jquery.com) и положите в папку со статикой сайта, например /js/. Дальше подключите тегом с относительным путём:

<script src="/js/jquery-4.0.0.min.js"></script>
<script src="/js/my-plugin.js"></script>
<script src="/js/app.js"></script>

Порядок важен: сначала jQuery, затем плагины, которые от неё зависят, и только потом ваш код, использующий и jQuery, и эти плагины. Каждый скрипт без async/defer выполняется сразу после загрузки и блокирует разбор страницы до этого момента — поэтому такие теги обычно ставят в самом конце <body>. Если хотите держать все скрипты в <head>, добавьте всем трём тегам атрибут defer — браузер сохранит порядок выполнения между ними и не остановит отрисовку страницы.

Частый сценарий — грузить jQuery с CDN, а при сбое подключать локальную копию. Классический вариант проверки:

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script>
  window.jQuery || document.write('<script src="/js/jquery-4.0.0.min.js">\x3C/script>');
</script>

document.write() здесь безопасен только потому, что оба тега синхронные, без async/defer: страница ещё не дочитана, и метод успевает дописать HTML в поток разбора. В остальных случаях приём считается устаревшим: из асинхронных скриптов он не работает, а Chrome на медленных соединениях может не загружать вставленные через него скрипты со сторонних доменов. Вариант без document.write() — динамически создать тег скрипта и продолжить инициализацию в обработчике загрузки:

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script>
(function () {
  if (window.jQuery) return; // CDN отработал, ничего делать не нужно

  var script = document.createElement('script');
  script.src = '/js/jquery-4.0.0.min.js';
  script.onload = function () {
    jQuery(function ($) {
      // код, зависящий от jQuery, безопасно вызывать здесь
    });
  };
  document.head.appendChild(script);
})();
</script>

Минус — код, зависящий от jQuery, приходится держать внутри onload, а не отдельным тегом ниже. Для одностраничников это обычно не проблема.

npm и сборщики

В проекте со сборщиком (Vite, webpack) jQuery ставится как обычная npm-зависимость:

npm install jquery

и импортируется как ES-модуль:

import $ from "jquery";

$(function () {
  $("#app").addClass("ready");
});

Проблема возникает со старыми плагинами, которые ожидают $ и jQuery как глобальные переменные, а не как импортированный модуль. В webpack это решается через ProvidePlugin — он подставляет импорт автоматически там, где встречает $ или jQuery без объявления:

// webpack.config.js
const webpack = require("webpack");

module.exports = {
  // ...
  plugins: [
    new webpack.ProvidePlugin({
      $: "jquery",
      jQuery: "jquery",
    }),
  ],
};

В Vite такого готового плагина из коробки нет, но глобальные алиасы можно выставить руками. Важно: инструкции import всплывают и выполняются раньше остального кода модуля, поэтому присваивание window.jQuery нужно вынести в отдельный модуль и импортировать его первым:

// jquery-global.js
import $ from "jquery";
window.$ = window.jQuery = $;
export default $;

// main.js — порядок импортов = порядок выполнения
import $ from "./jquery-global.js";
import "./legacy-plugin.js"; // теперь плагин найдёт window.jQuery

Если написать присваивание прямо в main.js между двумя import, плагин выполнится раньше него и не найдёт jQuery.

Для окружений без браузера — Node.js с jsdom, серверный рендеринг, тесты — способ подключения в jQuery 4.0 изменился. В 3.x было достаточно require("jquery")(window), и библиотека сама возвращала фабричную функцию, если не находила глобальный window. В 4.0 эта неявная фабрика убрана из основного модуля: нужный вход — jquery/factory (или jquery/factory-slim для slim-сборки):

// jQuery 4.0
const { JSDOM } = require("jsdom");
const { window } = new JSDOM("");
const $ = require("jquery/factory")(window);

Если после перехода на 4.0 такой код перестал работать, это первое место для проверки.

jQuery в WordPress

WordPress поставляет jQuery в комплекте с ядром — отдельно подключать библиотеку с CDN для тем и плагинов не нужно и обычно не стоит. Правильный способ добавить свой скрипт, зависящий от jQuery, — зарегистрировать зависимость через wp_enqueue_script(), а не вставлять тег <script> напрямую в шаблон:

function my_theme_scripts() {
    wp_enqueue_script(
        'my-theme-script',
        get_template_directory_uri() . '/js/my-script.js',
        array( 'jquery' ), // зависимость — WordPress сам подключит jQuery раньше
        '1.0.0',
        true // грузить в подвале страницы
    );
}
add_action( 'wp_enqueue_scripts', 'my_theme_scripts' );

Так WordPress гарантирует, что jQuery окажется на странице раньше вашего скрипта, даже если её уже подключает тема или другой плагин — дубликатов не будет.

Важная особенность: ядро WordPress подключает jQuery в режиме noConflict, чтобы не спорить за символ $ с другими библиотеками в теме. Из-за этого глобальный алиас $ в WordPress не работает — доступен только jQuery. Стандартный обходной приём — обернуть код в функцию и вернуть короткий алиас локально:

jQuery(function ($) {
    // здесь $ снова означает jQuery, но только внутри этой функции
    $('.my-block').addClass('is-ready');
});

Не отключайте и не дерегистрируйте встроенный jquery без веской причины (например, замены на другую версию для конкретного плагина, который иначе не работает) — на нём завязана часть админки и многих плагинов, и без явной необходимости трогать эту зависимость не стоит.

Проверка, что jQuery загрузился

Откройте консоль разработчика (клавиша F12 или сочетание Ctrl+Shift+I) на нужной странице и введите:

typeof jQuery

Если возвращается "function" — библиотека загружена. Значение "undefined" означает, что скрипт не подключился или подключился с ошибкой. Узнать версию можно так:

jQuery.fn.jquery
// вернёт строку вида "4.0.0"

Чтобы убедиться, что файл вообще запрашивался, откройте вкладку Network, перезагрузите страницу и найдите jquery в списке запросов — по столбцу Status видно, отдал ли сервер 200, 404 или редирект, а по Size — не пришёл ли вместо файла пустой ответ.

Готовность DOM

Код, который ищет элементы на странице (через функцию jQuery() / $()), должен запускаться только после того, как эти элементы появились в DOM. Стандартный способ — короткая форма:

$(function () {
    // DOM готов, можно искать элементы и вешать обработчики
});

Она эквивалентна более явной записи $(document).ready(function () { ... }) — обе формы работают и сейчас, короткую просто удобнее читать. А вот привязка через .on('ready', fn), которую иногда ещё встречают в старом коде, не годится: ready — это не обычное DOM-событие, и такой способ подписки на него не поддерживается уже много версий подряд. Используйте $(fn) или $(document).ready(fn).

Если jQuery на странице нужен только ради ожидания готовности DOM, а остальной код написан на чистом JavaScript, обычно достаточно нативного события:

document.addEventListener('DOMContentLoaded', function () {
    // DOM готов, jQuery не нужен
});

Похожий эффект даёт атрибут defer у обычного тега <script>: браузер откладывает выполнение скрипта до момента, близкого к DOMContentLoaded, без обёрток вида $(document).ready(). Подробнее о разнице между .ready() и обработчиками через .on() — в статье про события в jQuery.

Частые ошибки

СимптомПричинаРешение
$ is not definedВаш код выполняется раньше, чем подключился jQuery, либо тег с jQuery вообще отсутствует на страницеПроверьте порядок тегов: jQuery должен быть выше вашего скрипта; убедитесь через вкладку Network, что файл вообще загрузился
jQuery is not definedТо же самое, но код обращается к полному имени, а не к алиасу $Та же проверка порядка подключения и факта загрузки файла
$(...).plugin is not a functionПлагин подключён раньше самой jQuery, либо на странице загружены две версии jQuery и плагин прицепился не к тойПроверьте порядок тегов (jQuery → плагины → ваш код) и убедитесь, что тег с jQuery на странице один
Код ломается непредсказуемо, часть плагинов «не видит» другиеНа странице подключены две версии jQuery одновременно (например, одну тянет тема, другую — виджет)Найдите оба тега <script> и оставьте один; если убрать нельзя — разведите версии через jQuery.noConflict(true)
$ занят — конфликт с другой библиотекойЕщё одна библиотека тоже использует символ $ (например, Prototype.js)Вызовите jQuery.noConflict(); после подключения jQuery и используйте полное имя jQuery вместо $
Скрипт с CDN не грузится, в консоли ошибка про mixed contentСтраница открыта по https, а адрес CDN указан по httpИспользуйте протокол-независимый или явно https-адрес CDN (все актуальные CDN jQuery отдают https)
Браузер блокирует скрипт с CDN, в консоли ошибка Content Security PolicyЗаголовок CSP сайта не разрешает загрузку скриптов с домена CDNДобавьте домен CDN (например, code.jquery.com) в директиву script-src вашей CSP-политики или разместите файл локально
Код после CDN-скрипта иногда падает с $ is not defined только на медленной сетиТегу с jQuery по ошибке добавлен async, из-за чего порядок выполнения относительно соседних скриптов не гарантированУберите async у тега с jQuery либо переведите все зависимые скрипты на defer, который сохраняет порядок

Чек-лист

  • Определились, нужна ли ветка 4.0.0 или 3.7.1, и обычная сборка или slim.
  • Тег с jQuery стоит выше тегов с плагинами и вашим кодом (или у всех проставлен согласованный defer).
  • Если используете CDN — рядом есть план на случай его недоступности: локальный файл и фолбэк-проверка window.jQuery.
  • Если используете integrity, хэш соответствует точной версии и сборке файла (скопирован с releases.jquery.com), а не остался от другой версии.
  • В npm-проекте плагинам, ожидающим глобальные $/jQuery, явно проброшены глобальные переменные (через ProvidePlugin или ручное присваивание).
  • В WordPress свой скрипт зарегистрирован через wp_enqueue_script() с зависимостью jquery, а не отдельным тегом в шаблоне.
  • Код, ищущий элементы на странице, обёрнут в $(function(){...}), а не выполняется до готовности DOM.
  • После подключения проверили в консоли typeof jQuery и jQuery.fn.jquery, а во вкладке Network — что файл действительно загрузился с кодом 200.

Если jQuery на сайте не используется активно и подключён «по привычке» — возможно, часть задач вообще проще закрыть без него; сравнение вариантов — в статье нужен ли jQuery, или хватит чистого JS. А для более редких методов и устаревших свойств вроде jQuery.browser или динамической подгрузки скриптов через jQuery.getScript() держите под рукой справочник jQuery API.

Частые вопросы

Куда вставлять подключение jQuery — в head или перед </body>?

Оба варианта рабочие. Тег в конце <body> (перед вашими скриптами) не блокирует отрисовку страницы и остаётся самым предсказуемым вариантом. Тег в <head> с атрибутом defer даёт тот же эффект: скрипт грузится параллельно с HTML и выполняется перед DOMContentLoaded, сохраняя порядок относительно других defer-скриптов. Не ставьте jQuery в <head> без defer и без async — тогда браузер остановит разбор HTML, пока не скачает и не выполнит файл.

Можно ли подключить две версии jQuery на одной странице?

Технически да, но вторая версия перезапишет window.$ и window.jQuery, и плагины, привязанные к первой версии, могут сломаться. Если это неизбежно (например, тема и плагин тянут разные версии), сразу после первой загрузки сохраните её через var jQuery1 = jQuery.noConflict(true);, а второй версии оставьте глобальные имена. Правильнее — привести все части сайта к одной версии.

Чем slim-сборка отличается от обычной?

В slim-сборке нет модулей Ajax и эффектов (.animate(), .fadeIn() и т. п.) в любой ветке. В jQuery 4.0 slim дополнительно лишена модулей Deferred, Callbacks и Queue, на которых эти функции основаны. Если сайт использует только выборку и манипуляции с DOM (.addClass(), .attr(), .on()), slim выйдет заметно легче обычной сборки; если нужны $.ajax() или анимации — берите полную версию.

Нужно ли подключать jQuery для Bootstrap 5?

Нет. Начиная с 5-й версии Bootstrap переписал JS-компоненты на чистый JavaScript и не требует jQuery для выпадающих меню, модальных окон, тултипов и остального. jQuery нужен только для Bootstrap 4 и более старых версий. Если на сайте Bootstrap 5 и jQuery всё равно подключён — это, скорее всего, наследие темы или отдельного плагина, а не требование самого Bootstrap.

Как узнать версию jQuery на сайте?

Откройте консоль разработчика (F12) на нужной странице и выполните jQuery.fn.jquery — вернётся строка вида "4.0.0". Если jQuery не подключён, команда вызовет ошибку jQuery is not defined. Также версию видно во вкладке Network: у файла с CDN обычно есть номер версии прямо в имени, например jquery-3.7.1.min.js.

Почему $ не работает в WordPress, хотя jQuery подключён?

Ядро WordPress подключает jQuery в noConflict-режиме, чтобы не конфликтовать с другими библиотеками в теме и плагинах, поэтому короткий алиас $ глобально недоступен — работает только jQuery. Внутри своего кода алиас можно вернуть локально: оберните код в jQuery(function($){ /* тут $ снова работает */ }); — это стандартный и безопасный приём именно для WordPress.

Ещё по теме

[ наверх ]

 



Справочник по jQuery JavaScript API на русском языке