Ошибка jQuery is not defined означает, что код обратился к объекту jQuery раньше его появления в текущем контексте или библиотека вообще не загрузилась. Из-за этого перестают работать меню, формы, модальные окна, слайдеры и другие элементы, хотя HTML и CSS страницы продолжают отображаться.

Не стоит сразу добавлять вторую копию jQuery в шаблон. Это может временно скрыть сообщение, но создать конфликты плагинов, повторные обработчики и разные версии API. Сначала нужно определить первый неуспешный запрос или первый скрипт, нарушивший порядок выполнения.

Сохраните точный текст и место ошибки

  • Откройте Console и запишите полный текст ReferenceError.
  • Нажмите на имя файла и строку, где возникла первая ошибка.
  • Не ориентируйтесь только на последующие сообщения плагинов.
  • Проверьте, ошибка относится к jQuery или только к короткому имени $.
  • Зафиксируйте URL страницы, устройство, браузер и режим авторизации.
  • Сравните обычный режим, приватное окно и страницу после очистки кеша.

Первая ошибка важнее десятков последующих. Если базовая библиотека не определена, каждый зависимый скрипт добавляет свое сообщение и усложняет картину.

Проверьте загрузку jQuery в Network

Перезагрузите страницу с открытой вкладкой Network и отключенным кешем. Найдите файл jQuery по имени или откройте список JavaScript-ресурсов. Успешный статус 200 сам по себе недостаточен: сервер может вернуть HTML-страницу ошибки под видом файла .js.

  • URL библиотеки не возвращает 404, 403, 429 или 5xx.
  • После redirect загружается JavaScript, а не форма входа или страница CDN.
  • Content-Type соответствует JavaScript и не блокируется браузером.
  • Размер ответа выглядит реалистично и тело содержит библиотеку.
  • Запрос не заблокирован CSP, SRI, CORS, расширением или корпоративным фильтром.
  • Схема HTTPS не смешивается с HTTP-ресурсом.

Если библиотека загружается с внешнего CDN, повторите тест в другой сети и без расширений. Недоступность одного домена или блокировка privacy-фильтром не должна полностью ломать основную функцию сайта.

Сверьте порядок тегов script

Файл, который использует jQuery, должен выполняться после самой библиотеки. Визуальное расположение тегов в исходном шаблоне не всегда определяет фактический порядок: атрибуты async и defer, динамическая вставка и оптимизаторы могут его изменить.

  • Зависимый скрипт не расположен выше подключения jQuery.
  • У jQuery и зависимых файлов согласован режим загрузки.
  • Async не используется для библиотек с последовательными зависимостями.
  • Defer-файлы подключены в правильном порядке и не смешаны с ранним inline-кодом.
  • Inline-скрипт не обращается к jQuery до завершения загрузки внешнего файла.
  • Динамически добавляемый script дожидается события load до запуска зависимого кода.

Defer обычно сохраняет порядок внешних скриптов в документе, а async выполняет каждый файл сразу после загрузки и не гарантирует последовательность. Поэтому пара async-файлов jQuery и plugin может работать случайно: быстро на одном устройстве и падать на другом.

Отличайте jQuery is not defined от $ is not defined

Если объект jQuery существует, а символ $ недоступен, библиотека могла перейти в режим noConflict или другое приложение заняло короткое имя. В таком случае повторное подключение jQuery не требуется.

  • Проверьте в Console типы window.jQuery и window.$.
  • Используйте полное имя jQuery там, где $ не гарантирован.
  • Передавайте $ локальным параметром в безопасную функцию-обертку.
  • Не меняйте глобальный $ без проверки других библиотек.
  • Учитывайте, что module script не создает глобальные переменные автоматически.
  • Проверьте, не вызывается ли noConflict другим плагином.

Проверьте WordPress и зависимости плагинов

В WordPress jQuery лучше подключать через штатную очередь скриптов, указывая ее как зависимость. Ручной тег в header может конфликтовать с версией CMS, кеширующим плагином и загрузкой файлов в footer.

  • Скрипт зарегистрирован через enqueue, а не вставлен несколько раз в шаблон.
  • В списке зависимостей явно указана библиотека jquery.
  • Файл подключается в том же месте, что и его зависимости.
  • Тема вызывает обязательные функции вывода скриптов в header и footer.
  • Плагин оптимизации не задерживает jQuery отдельно от зависимого кода.
  • Код учитывает штатный режим noConflict WordPress.

После исправления очистите кеш WordPress, page cache, CDN и браузера. Иначе часть посетителей продолжит получать старый HTML с прежним порядком файлов.

Проверьте сборщик и ES-модули

В проектах с Vite, Webpack или другим сборщиком пакет jQuery может присутствовать в зависимостях, но не быть доступным как window.jQuery. Модульный код должен импортировать библиотеку явно, а старый плагин иногда ожидает глобальную переменную.

  • Пакет установлен в том окружении, где выполняется production-сборка.
  • Импорт используется до обращения к библиотеке.
  • Tree shaking не удаляет зависимость, вызываемую только старым плагином.
  • Настройка external не исключает jQuery без отдельного CDN-подключения.
  • Chunk с библиотекой загружается раньше legacy-кода.
  • Если нужен global, он создается осознанно в одной точке приложения.

Не следует одновременно импортировать jQuery в bundle и подключать другую версию отдельным тегом без необходимости. Две копии могут хранить разные наборы plugin и данные элементов.

Проверьте CSP, SRI и CDN

Политика Content Security Policy может разрешать основной bundle, но блокировать библиотеку с другого домена или ранний inline-код. Subresource Integrity блокирует ресурс, если контрольная сумма не соответствует фактическому файлу.

  • В Console нет сообщения Refused to load the script из-за CSP.
  • Домен CDN разрешен в script-src.
  • Nonce или hash применяется к нужному inline-скрипту.
  • Значение integrity соответствует текущей версии файла.
  • Атрибут crossorigin согласован с настройками CDN.
  • CDN не возвращает challenge или HTML-заглушку вместо JavaScript.

Не ослабляйте CSP до небезопасного режима ради устранения одной ошибки. Лучше разрешить конкретный проверенный источник или перенести библиотеку на свой домен с контролируемым обновлением.

Отключите оптимизацию JavaScript для контрольного теста

Плагины ускорения, CDN и функции delay JavaScript могут объединять, переносить и откладывать файлы. После обновления настройки зависимость иногда выполняется раньше jQuery только на первом посещении или только на мобильном устройстве.

  • Временно отключите объединение и изменение порядка на тестовом окружении.
  • Исключите jQuery и связанные плагины из несовместимого delay-режима.
  • Не исключайте только библиотеку, оставляя зависимый inline-код ранним.
  • Сравните исходный HTML до оптимизатора и итоговый HTML в браузере.
  • Очистите все уровни кеша после изменения правил.
  • Проверьте холодную загрузку с медленным соединением.

Проверьте дубли и несовместимые версии

Несколько версий jQuery не всегда вызывают ReferenceError напрямую, но могут создать последовательность, при которой одна копия заменяет другую, plugin регистрируется не там или noConflict удаляет ожидаемый global.

  • В Network загружается одна согласованная версия библиотеки.
  • Плагины совместимы с выбранной версией jQuery.
  • Старая версия не добавляется отдельным виджетом или шаблоном.
  • Миграционный plugin используется временно и контролируемо.
  • После AJAX-навигации script не вставляется повторно.
  • В iframe проверяется собственный window, а не объект родительской страницы.

Не путайте загрузку библиотеки с готовностью DOM

jQuery is not defined означает отсутствие самой переменной. Ошибка обращения к несуществующему элементу после загрузки библиотеки относится уже к моменту готовности DOM или к неверному selector. Эти проблемы исправляются по-разному.

  • Сначала подтвердите наличие window.jQuery.
  • Затем проверьте, существует ли нужный DOM-элемент на текущей странице.
  • Инициализируйте виджет после создания динамического контента.
  • Не запускайте один plugin на страницах, где его разметки нет.
  • При SPA-навигации учитывайте повторное монтирование и уничтожение компонента.
  • Не оборачивайте отсутствие библиотеки только в DOM ready: это не загрузит jQuery.

Безопасный порядок исправления

  1. Найдите первую ошибку и файл, который обратился к jQuery.
  2. Проверьте запрос библиотеки, тело ответа и сообщения блокировки.
  3. Сверьте фактический порядок выполнения script.
  4. Уберите async из последовательных зависимостей или настройте загрузку явно.
  5. Исправьте enqueue, import или динамическое ожидание в зависимости от проекта.
  6. Устраните конфликт noConflict без принудительного захвата глобального $.
  7. Очистите кеш сайта, CDN и браузера.
  8. Проверьте холодную загрузку на медленном соединении.
  9. Повторите тест на страницах с разными наборами плагинов.
  10. Добавьте автоматическую проверку Console и загрузки ключевых ресурсов.

Как проверить результат

  • В Console нет jQuery is not defined и связанных ошибок plugin.
  • Файл библиотеки загружается со статусом 200 и корректным типом содержимого.
  • jQuery выполняется раньше всех зависимых скриптов.
  • Меню, формы, модальные окна и другие связанные элементы работают.
  • Страница исправна при холодной загрузке и после очистки кеша.
  • Нет второй версии jQuery и повторной регистрации обработчиков.
  • CSP и SRI остаются включенными и корректными.
  • Исправление работает на мобильном устройстве и при медленной сети.

Типичные ошибки

  • Добавить еще один CDN-тег в случайное место шаблона.
  • Использовать async для библиотеки и ее плагинов.
  • Заменить jQuery на $ без проверки noConflict.
  • Отключить CSP полностью.
  • Считать статус 200 доказательством, что загружен JavaScript.
  • Исправить только desktop и не проверить мобильную оптимизацию.
  • Очистить кеш браузера, но оставить старый HTML в CDN.
  • Скрыть ReferenceError через try/catch, оставив интерфейс нерабочим.

Как предотвратить повторение

  • Управляйте зависимостями через CMS или сборщик, а не ручные копии тегов.
  • Фиксируйте версии и обновляйте библиотеку вместе с проверкой plugin.
  • Не используйте async для последовательной цепочки зависимостей.
  • Проверяйте production-сборку с включенной оптимизацией.
  • Добавьте мониторинг ошибок JavaScript и source maps с закрытым доступом.
  • Тестируйте холодную загрузку ключевых страниц.
  • Храните CSP и SRI в синхронизации с реальными ресурсами.
  • Удаляйте устаревшие plugin и лишние копии jQuery.

Когда нужна помощь

Если сайт показывает jQuery is not defined и из-за этого не работают формы, меню или виджеты, можно прислать URL страницы, текст первой ошибки и описание последнего изменения. Я проверю загрузку ресурсов, порядок скриптов, WordPress enqueue или сборщик, CSP, CDN и кеш, затем устраню причину без добавления конфликтующих копий библиотеки.