Как использовать функцию wp_enqueue_script для добавления собственных скриптов в WordPress

Диагностика проблемы с добавлением скриптов в WordPress

Часто при разработке темы или плагина возникает необходимость добавить собственные JavaScript-файлы. Неправильное подключение скриптов приводит к конфликтам, дублированию, ошибкам загрузки или неправильному порядку исполнения. Например, если скрипт подключается напрямую через <script> в header.php, это нарушает систему зависимостей WordPress и может вызвать проблемы с кешированием или совместимостью.

Чтобы правильно подключить скрипты, нужно использовать стандартный API WordPress — функцию wp_enqueue_script. Это гарантирует, что скрипты будут подключены один раз, в правильном месте, с учетом зависимостей и версий.

Пошаговое решение: добавляем собственный скрипт через wp_enqueue_script

1. Создаем js-файл

В теме или плагине создайте папку /js/ и добавьте туда файл, например custom-script.js:

console.log('Custom script loaded');

2. Регистрируем и подключаем скрипт

В functions.php темы или в основном файле плагина добавьте следующий код:

function myplugin_enqueue_scripts() {
    wp_enqueue_script(
        'myplugin-custom-script', // уникальный хендл
        get_template_directory_uri() . '/js/custom-script.js', // путь к файлу
        array('jquery'), // зависимости (например, jQuery)
        '1.0', // версия
        true // размещение в footer
    );
}
add_action('wp_enqueue_scripts', 'myplugin_enqueue_scripts');

Если вы работаете в плагине, замените get_template_directory_uri() на plugin_dir_url(__FILE__).

Проверка результата после внедрения

Чтобы убедиться, что скрипт подключен правильно:

• Откройте исходный код страницы через браузер (Ctrl+U)
• Найдите тег <script>, который ссылается на custom-script.js
• Проверьте консоль браузера (F12 > Console) — должно появиться сообщение Custom script loaded

Если скрипт не подключается, проверьте правильность пути и хука wp_enqueue_scripts.

Частые ошибки и как их исправить

• Прямое добавление <script> в header.php: ломает логику WordPress, не учитывает зависимости и кеш. Решение — использовать wp_enqueue_script.
• Неправильный путь к файлу: часто возникает при использовании get_template_directory_uri() в плагинах. Для плагина используйте plugin_dir_url(__FILE__).
• Подключение скрипта вне правильного хука: вызов wp_enqueue_script должен быть в хуке wp_enqueue_scripts или admin_enqueue_scripts для админки.
• Забыли указать зависимости: если ваш скрипт зависит от jQuery или другого скрипта, обязательно укажите это в третьем параметре массива, иначе порядок загрузки нарушится.
• Скрипт не отображается в footer: убедитесь, что последний параметр в wp_enqueue_script установлен в true, чтобы скрипт загружался перед закрывающимся тегом </body>.

Практические советы для безопасности и производительности

• Версионирование скриптов: для сброса кеша при обновлении скрипта актуально указывать версию.
• Минификация: используйте минифицированные версии JavaScript для продакшена.
• Зависимости: корректно указывайте зависимости, чтобы избежать ошибок загрузки.
• Размещение в footer: подключайте скрипты в footer, если это возможно, чтобы ускорить загрузку страницы.
• Использование CDN: если скрипт доступен через CDN, можно подключать его напрямую с CDN, указывая URL в wp_enqueue_script.

Таблица сравнения способов подключения скриптов