WP_DEBUG и отладка WordPress: как найти и исправить ошибки

Почему WordPress ломается: белый экран, 500 и «тихие» ошибки

WordPress — это тысячи файлов на PHP, которые выполняются на сервере. Ошибка может возникнуть в теме, в плагине, в ядре или в вашем собственном коде. Проблема в том, что по умолчанию WordPress не показывает эти ошибки: на боевом сайте посетитель видит либо работающую страницу, либо белый экран без всяких пояснений. Так сделано специально — чтобы текст ошибки не выдавал посторонним структуру сайта и версии компонентов.

Именно поэтому первое, чему нужно научиться, — заставить WordPress рассказать, что не так, но так, чтобы это увидели только вы. Для этого в WordPress есть встроенный режим отладки, а удобнее всего он работает вместе с файлом-журналом: сайт пишет замечания в специальный файл, а вы читаете его через панель хостинга или FTP.

Типичные симптомы, которые указывают на ошибку PHP: полностью белая страница (была «страница сломалась»), код ответа 500, «поехавшая» вёрстка сразу после обновления, пропавшие блоки в редакторе, пустая корзина в магазине. Отдельная категория — ошибки JavaScript: страница загружается, но на кнопку не реагирует, слайдер не крутится, форма не отправляется. Эти два случая диагностируются разными инструментами, и в этой статье мы разберём оба.

Логика отладки всегда одна и та же: сначала включить журнал и получить текст ошибки с указанием файла и строки, затем найти источник — тему или плагин, затем устранить причину. Отлаживать «наугад», отключая всё подряд, можно, но это долго и не даёт понимания проблемы. Начнём с правильной настройки.

Как включить WP_DEBUG правильно: константы в wp-config.php

Режим отладки включается четырьмя строками в файле wp-config.php в корне сайта. Файл лежит рядом с папкой wp-content, правится через файловый менеджер хостинга или по FTP. Перед правками обязательно сделайте копию файла: одна лишняя кавычка в PHP останавливает весь сайт, и восстановить конфиг из бэкапа будет проще всего. О том, как устроены бэкапы и почему их лучше настраивать заранее, мы писали в статье про резервное копирование WordPress.

Вставьте блок ниже выше строки /* That's all, stop editing! */ — именно там WordPress ожидает пользовательские константы:

<?php
/*
 * Отладка WordPress: блок для wp-config.php.
 * Ставится ВЫШЕ строки «That's all, stop editing!».
 */
define( 'WP_DEBUG', true );          // включаем режим отладки
define( 'WP_DEBUG_LOG', true );      // замечания PHP пишутся в wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // ошибки НЕ показываются посетителям
define( 'SCRIPT_DEBUG', true );      // ядро отдаёт неминифицированные CSS и JS

Разберём, что делает каждая строка. WP_DEBUG — главный выключатель: пока он false, остальные константы не действуют. WP_DEBUG_LOG направляет замечания PHP в файл wp-content/debug.log — это и есть ваш журнал. WP_DEBUG_DISPLAY = false критически важен: без него WordPress начнёт печатать ошибки прямо в HTML, и посетители увидят пути к файлам и версии плагинов. SCRIPT_DEBUG подключает неминифицированные файлы ядра — полезно, когда вы ищете проблему во встроенных скриптах.

Сразу после включения откройте сайт в новой вкладке и посмотрите, появился ли файл debug.log. Если появился и в нём пусто — ошибок нет, и можно двигаться дальше по сценарию. Если он тут же наполнился однотипными строками, это нормально: у многих плагинов есть «фоновые» предупреждения, которые не мешают работе. В таком случае запомните этот набор как исходный шум и смотрите только на новые строки, которые появляются при вашем действии.

Выключается отладка возвратом WP_DEBUG в false. На боевом сайте включать её нужно ровно на время диагностики: файл лога быстро растёт, а режим отладки слегка замедляет страницы. И ещё одна деталь — после изменения wp-config.php обязательно сбросьте кэш страниц, если он настроен, иначе WordPress может продолжить отдавать закэшированную версию, а вы будете думать, что настройка не применилась. Про слои кэша подробно рассказано в материале про кэширование WordPress.

Где искать ошибки: debug.log, лог хостинга и Query Monitor

Основное место поиска после включения отладки — тот самый файл wp-content/debug.log. Открыть его можно любым способом, который у вас есть: встроенный файловый менеджер хостинга, FTP-клиент, «Файловый менеджер» в панели. Файл текстовый, читается как обычный журнал. Если файловый менеджер неудобно листать, скачайте debug.log к себе и откройте в редакторе — так проще искать по ключевым словам.

Что в нём написано. Формат строки простой: уровень проблемы, текст, путь к файлу и номер строки. Например, запись вида PHP Warning: Undefined array key "price" in /home/user/site/wp-content/themes/mytheme/functions.php on line 142 означает, что в 142-й строке файла темы код обратился к несуществующему элементу массива. Это уже адрес проблемы: открываете файл, смотрите строку, исправляете.

Второй источник — лог ошибок самого хостинга. У каждой панели управления он лежит в своём месте и называется error_log (без расширения). Он полезен тем, что туда попадают ошибки, которые WordPress не перехватывает: например, нехватка памяти или падение процесса PHP. Если debug.log пуст, а сайт всё равно не работает, посмотрите именно лог хостинга — и обратите внимание на строки про Allowed memory size exhausted: чаще всего белый экран вызван именно лимитом памяти.

Третий, и самый удобный для новичка инструмент — плагин Query Monitor. Он бесплатный, ставится обычным способом и добавляет в админ-панель панель отладки внизу каждой страницы. В ней видно сразу всё: ошибки PHP и предупреждения, все запросы к базе данных с текстом SQL и временем выполнения, сработавшие хуки, HTTP-запросы, AJAX-вызовы, а также какой шаблон темы и какой плагин отдали текущую страницу. Для начинающего это самый быстрый способ понять, где именно прячется проблема, потому что не нужно угадывать по логу — плагин сам подсвечивает проблемные места.

Составьте привычку: сначала отключите всё ненужное, затем примените действие, которое вызывает ошибку, и только после этого смотрите журнал. Так вы не утонете в старых записях и точно поймёте, какая строка появилась из-за вашего шага.

Читаем ошибки PHP: warning, notice, fatal и deprecated

Не каждая запись в логе означает, что сайт сломан. Уровни ошибок различаются по серьёзности, и от этого зависит, что делать. Минимально достаточно запомнить четыре категории.

Уровень	Что означает	Насколько опасно
Notice	Мелкое замечание: обращение к неизвестной переменной или ключу массива	Сайт работает, но код стоит подправить
Warning	Предупреждение: неверный тип данных, отсутствующая функция, обращение к несуществующему файлу	Часть функциональности может работать неправильно
Deprecated	Использован устаревший способ, который уберут в будущих версиях	Сейчас работает, но сломается после обновления
Fatal error	Неустранимая ошибка: выполнение кода останавливается полностью	Белый экран или код ответа 500

Читать журнал нужно сверху вниз, но искать не первую строку, а причину. Часто одна настоящая ошибка порождает десяток записей: код упал на Fatal error, и дальше WordPress ругается уже на последствия. Ищите самую раннюю по времени запись, которая появилась сразу после вашего действия или обновления.

Отдельно обратите внимание на строки с пометкой Deprecated. Новички их игнорируют, а это готовый список будущих проблем: когда WordPress обновится, устаревшая функция может быть удалена, и тогда появится уже настоящая фатальная ошибка. Если плагин годами сыплет Deprecated, это повод поискать ему замену: скорее всего, он заброшен автором. Список ссылок на устаревшие функции WordPress ведёт на странице разработчика, и именно оттуда удобно сверяться.

Записи вида Undefined array key чаще всего означают одну из двух вещей: либо код ожидает данных, которых нет (например, необязательное поле в массиве), либо у пользователя (или внешнего сервиса) пришли не те данные, которые предполагал автор кода. Первое лечится исправлением условия, второе — проверкой входных данных, и об этом мы ещё поговорим в разборе ошибок. И помните: убирать сообщение об ошибке «подавлением» (@ перед функцией) — плохая практика, вы просто лишаете себя информации.

Отладка JavaScript и AJAX в WordPress

Если PHP-журнал чист, а интерфейс не работает — проблема в JavaScript. Здесь инструмент один: консоль разработчика в браузере, которая открывается клавишей F12. Вкладка Console показывает ошибки скриптов и подсказывает файл со строкой, вкладка Network — все запросы страницы, включая AJAX, с их кодами ответа и содержимым.

Классический сценарий в WordPress — AJAX-запрос, который «молча» не работает. WordPress отправляет такие запросы на файл /wp-admin/admin-ajax.php, и если в ответе приходит 0 вместо данных, это значит, что функция-обработчик не сработала или упала. Проверить запрос руками удобнее всего прямо из консоли браузера, скопировав его с вкладки Network:

// Отладка AJAX-запроса WordPress из консоли браузера (F12 → Console).
const body = new URLSearchParams({
  action: 'ds_get_price',   // тот же action, что в обработчике PHP
  product_id: '42',
  nonce: window.dsData ? window.dsData.nonce : ''  // nonce из wp_localize_script()
});

fetch('/wp-admin/admin-ajax.php', { method: 'POST', body })
  .then(r => {
    console.log('Статус:', r.status, '| тип:', r.headers.get('content-type'));
    return r.text();
  })
  .then(text => {
    try { console.log('Ответ:', JSON.parse(text)); }
    catch (e) { console.error('Ответ не JSON, а значит что-то не так:', text); }
  })
  .catch(err => console.error('Ошибка сети или сервера:', err));

Как читать результат. Пустая строка или 0 — обработчик не подключён либо в нём фатальная ошибка PHP (тут пригодится включённый ранее debug.log). Ошибка с кодом 403 — истёк или неверен nonce. Нечитаемый «мусор» перед JSON — это предупреждения PHP, которые вывелись вместо отключённого показа ошибок, поэтому держите WP_DEBUG_DISPLAY = false и читайте лог. Механику admin-ajax разбирали подробнее в статье про AJAX в WordPress.

Второй частый случай — скрипт не видит данные, которые WordPress должен был передать. Проверить это можно так:

// Что WordPress передал в JS через wp_localize_script / wp_add_inline_script
console.log('Данные темы:', window.dsData);
console.table(Object.entries(window.dsData || {}));

// Проверить, что нужный объект вообще существует
if (typeof jQuery === 'undefined') {
  console.warn('jQuery не загружен — проверьте зависимости wp_enqueue_script');
}

Ошибка «jQuery is not defined» почти всегда означает, что ваш скрипт подключён раньше библиотеки и не указал её в зависимостях. Лечится это в PHP-части, при подключении, а не в самом JavaScript; как правильно указать зависимости и порядок, показано в материале про подключение CSS и JS через wp_enqueue_scripts. И не забывайте после правок сбрасывать кэш браузера сочетанием Ctrl+F5, иначе можно долго отлаживать уже исправленный скрипт.

Сравнение инструментов отладки WordPress

Инструментов несколько, и для разных задач подходит разный. Сводная таблица поможет выбрать, с чего начать в конкретной ситуации.

Инструмент	Что показывает	Когда использовать	Сложность
WP_DEBUG + debug.log	Ошибки, предупреждения и notice PHP с путём и номером строки	Базовая диагностика, всегда первый шаг	Низкая
Query Monitor	Ошибки, SQL-запросы, хуки, HTTP и AJAX-запросы, какой шаблон и плагин отдали страницу	Когда нужно понять причину, а не только факт ошибки	Низкая
Консоль браузера (F12)	Ошибки JavaScript, сетевые запросы, содержимое AJAX-ответов	Не работает интерфейс, формы, слайдеры, кнопки	Низкая
Лог хостинга (error_log)	Нехватка памяти, падения процесса PHP, ошибки сервера	Белый экран при чистом debug.log	Средняя
Xdebug	Пошаговое выполнение кода, значения переменных, стек вызовов	Сложные ошибки логики в своём коде	Высокая

Для девяноста процентов задач новичка хватает первых трёх строк таблицы. Xdebug — мощный, но тяжёлый инструмент: он требует настройки на сервере и отдельного клиента в редакторе кода, поэтому к нему переходят, когда нужно разобраться в сложной логике собственного кода, а не просто найти опечатку. Начинайте с журнала и Query Monitor, а к отладчику переходите по необходимости.

И важное дополнение к таблице: чем больше слоёв вы включите одновременно, тем сложнее разобраться. Включённый SCRIPT_DEBUG вместе с плагином минификации, несколько инструментов отладки сразу и активный кэш страниц — это гарантированная путаница. Опытные разработчики включают по одному инструменту и выключают кэш на время диагностики.

Свои сниппеты для отладки в functions.php

Когда стандартного лога не хватает, удобно добавить свою функцию логирования и писать в журнал именно то, что нужно. Такой сниппет стоит держать в functions.php дочерней темы, а не в основной: тогда обновление темы не сотрёт ваши правки. Про создание такой темы есть отдельная статья — дочерняя тема WordPress.

Первый сниппет — универсальный логгер, который умеет принимать и строку, и массив, и объект:

<?php
/**
 * Пишем данные отладки в wp-content/debug.log.
 * Работает только когда включён WP_DEBUG.
 */
function ds_log( $data, $label = '' ) {
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }

    $prefix = $label ? '[' . $label . '] ' : '';
    $output = is_scalar( $data ) ? (string) $data : print_r( $data, true );

    error_log( $prefix . $output );
}

// Пример использования: посмотреть, какая страница запрошена и с какими параметрами.
add_action( 'template_redirect', function () {
    ds_log( array(
        'is_singular' => is_singular(),
        'post_id'     => get_queried_object_id(),
        'query'       => $GLOBALS['wp_query']->request,
    ), 'ds-debug' );
} );

В файле debug.log это появится одной понятной записью с меткой [ds-debug], и вам не придётся угадывать, чей это вывод. Такой логгер особенно полезен при отладке кастомных типов записей и полей: видно, что именно запрошено и что вернула база.

Второй сниппет — свой обработчик ошибок PHP. Он добавляет в журнал метку времени и имя файла, а также передаёт обработку дальше, чтобы не мешать штатной логике WordPress:

<?php
/**
 * Дополнительное логирование ошибок PHP с точным местом.
 * Ставить только на время отладки!
 */
set_error_handler( function ( $errno, $errstr, $errfile, $errline ) {
    if ( ! ( error_reporting() & $errno ) ) {
        return false;
    }

    error_log( sprintf( 'PHP [%d] %s в %s:%d', $errno, $errstr, $errfile, $errline ) );

    return false; // WordPress продолжит обрабатывать ошибку сам
} );

Третий приём — быстрый «снимок» переменной в момент выполнения, без записи в лог. Он хорош, когда нужно посмотреть значение здесь и сейчас, но обязательно удаляйте такие строки после диагностики: var_dump и print_r в боевом коде могут вывести данные посетителю.

<?php
// Снимок значения (только для локальной отладки, потом удалить!).
$order_id = 42;
$meta     = get_post_meta( $order_id );

echo '<pre>';
print_r( $meta );
echo '</pre>';

// Аккуратная альтернатива: остановить выполнение с понятным сообщением.
if ( ! $meta ) {
    wp_die( 'Метаданные заказа не найдены — проверьте ID ' . absint( $order_id ) );
}

И ещё один полезный приём для разработки — видеть, какие хуки вообще срабатывают на странице. Это помогает понять, куда цеплять свой код, и находится в той же логике, что и обычные фильтры. Механику действий и фильтров мы подробно разбирали в статье про хуки WordPress, а коллекция готовых приёмов для functions.php собрана в подборке полезных сниппетов.

8 ошибок новичков при отладке WordPress

Отладка — та область, где спешка стоит дороже всего. Вот ошибки, которые встречаются у начинающих чаще всего.

• Включили WP_DEBUG на живом сайте и забыли выключить. Файл лога растёт, режим замедляет страницы, а при неверной настройке ошибки видят посетители. Включайте на время диагностики и возвращайте false сразу после.
• Забыли про WP_DEBUG_DISPLAY = false. Сайт начинает показывать пути, версии и тексты ошибок всем подряд — это и некрасиво, и небезопасно. Про безопасность подробнее в материале про 10 настроек безопасности WordPress.
• Отключают плагины на боевом сайте. Так теряют данные, ломают магазин и пугают посетителей. Для экспериментов нужна копия сайта, а на живом сайте правильно — отлаживать по логу, а не методом перебора.
• Правят код основной темы. Первое же обновление темы стирает правки. Держите сниппеты в дочерней теме или в отдельном плагине.
• Смотрят только первую строку лога. Одна настоящая причина порождает десяток записей-последствий. Ищите самое раннее сообщение после вашего действия.
• Игнорируют предупреждения Deprecated. Это анонс будущей поломки: после обновления WordPress или плагина код перестанет работать.
• Отлаживают с включённым кэшем страниц. Вы смотрите старую версию страницы и делаете неверные выводы. На время диагностики кэш сбрасывайте или отключайте — об этом же речь в статье про кэширование WordPress.
• Убирают ошибку «заглушкой». Символ @ перед функцией и error_reporting(0) прячут симптом, но не лечат причину. Ошибка вернётся в самый неудачный момент.

Общая логика у всех пунктов одна: отладка — это управляемый процесс, а не гадание. Включите журнал, воспроизведите проблему, найдите самую первую запись, устраните причину, проверьте на копии и только потом переносите исправление на боевой сайт.

Как отлаживать безопасно: копия сайта, бэкап и закрытый лог

Отладка на живом сайте опасна сама по себе: в момент эксперимента сайт может отдать ошибку всем посетителям, а вы — потерять данные. Поэтому рабочая схема выглядит так. Сначала — актуальный бэкап: перед любым вмешательством в код или настройки сохраните и файлы, и базу данных. Затем — копия сайта для экспериментов; почти все нормальные хостинги дают либо отдельный поддомен, либо «тестовую среду» в один клик. Все правки сначала обкатываются на копии и только потом переносятся на боевой сайт.

Отдельно закройте доступ к файлу лога. Пока WP_DEBUG включён, debug.log лежит в публичной папке wp-content, и любой желающий теоретически может его прочитать — а там бывают пути, имена таблиц и токены. Простейшая защита для сервера на Apache — файл .htaccess в папке wp-content:

# wp-content/.htaccess — закрываем доступ к журналу отладки
<Files debug.log>
  Require all denied
</Files>

Если сервер работает на Nginx, та же защита делается на уровне конфигурации сайта:

# Закрыть журнал отладки в конфиге Nginx
location = /wp-content/debug.log {
    deny all;
    return 404;
}

Ещё один приём — держать отладку под контролем времени. Если правки делаются вечером и быстро, достаточно просто не забыть выключить WP_DEBUG. Если диагностика растягивается на дни, полезно напомнить себе об этом автоматически — например, через планировщик wp-cron можно повесить уведомление на почту, а про отправку писем с сайта мы рассказывали в статье про настройку SMTP и wp_mail.

Наконец, полезно фиксировать найденные ошибки и их причины — хотя бы в обычном файле-заметке в проекте. Через месяц та же ошибка почти наверняка повторится, и готовый разбор сэкономит часы. Если проблем становится слишком много и сайт уже непонятно как устроен, разобраться бывает быстрее с чистого листа: об этом — в материале про импорт и экспорт контента WordPress, а о том, что делать с устаревшим сайтом, — в статье про безопасное обновление WordPress.

Частые вопросы об отладке WordPress

Вывод

Отладка WordPress — это не магия и не «рулетка с плагинами», а понятная последовательность. Включите WP_DEBUG с записью в debug.log и выключенным показом ошибок, воспроизведите проблему, найдите самое раннее сообщение с путём и номером строки — и вы уже знаете, в каком файле искать причину. Для ошибок интерфейса переключитесь на консоль браузера: ошибки JavaScript и ответы admin-ajax вкладка Network показывает наглядно. Плагин Query Monitor добавьте как постоянный инструмент разработки — он покажет не только ошибку, но и SQL-запросы, сработавшие хуки и источник страницы.

И три правила безопасности, которые стоит запомнить сразу: отлаживайте на копии сайта, держите актуальный бэкап и закрывайте доступ к журналу. Соблюдение этих правил отличает аккуратного разработчика от новичка, который правит боевой сайт «на живую».

Если отладка и правки кода занимают слишком много времени, а сайт нужен работающим уже сейчас, это можно поручить команде, которая делает и поддерживает сайты на WordPress: мы находим причины ошибок по логам, настраиваем отладочный режим правильно, чиним конфликты плагинов и берём сайт на поддержку после исправления. Посмотрите услуги разработки и продвижения сайтов, примеры работ в портфолио выполненных проектов и другие материалы в блоге о сайтах и продвижении. Опишите проблему через форму обратной связи — подскажем, что именно сломалось на вашем сайте, и посчитаем стоимость исправления. А если речь идёт о доработке функциональности, а не о поломке, посмотрите отдельную статью про заказ доработки сайта программисту и материал про поддержку сайта: что входит и сколько стоит.