Как исправить ошибку Xdebug в PHP

При настройке Xdebug для PHP часто всплывает предупреждение:

PHP Warning: Failed loading Zend extension 'xdebug.so': cannot open shared object file: No such file or directory

Суть простая: PHP не находит модуль xdebug.so или не может его загрузить. Ниже пошаговый разбор типичных причин и способов починить загрузку расширения.

Почему PHP не грузит Xdebug

Чаще всего дело в одном из пунктов:

1. Несовместимая версия Xdebug с вашей версией PHP.
2. Неверный путь к xdebug.so в php.ini или conf.d.
3. Пакет Xdebug не установлен (или установлен не для той SAPI: CLI vs FPM/Apache).
4. Несколько версий PHP в системе, а правка ушла не в тот ini-файл.

Шаг 1. Проверить, видит ли PHP модуль

Сначала убедитесь, что Xdebug вообще в списке модулей:

php -m | grep -i xdebug
php -v

Если grep ничего не вывел, модуль не загружен. Имеет смысл сразу посмотреть, какой ini реально используется:

php --ini
# для FPM отдельно, если отладка идёт через веб:
php-fpm8.1 -i 2>/dev/null | head -n 5
# или phpinfo() в браузере

CLI и FPM/Apache часто читают разные ini. Правка только в cli/php.ini веб-серверу не поможет.

Шаг 2. Установить Xdebug

Через apt (Ubuntu/Debian)

Подставьте свою версию PHP вместо 8.1:

php -v
sudo apt update
sudo apt install php8.1-xdebug

Для 7.4, 8.2, 8.3 пакеты называются аналогично: php7.4-xdebug, php8.2-xdebug и т.д.

Через PECL

Когда в репозитории нет нужной сборки, ставят через PECL:

sudo apt install php-pear php8.1-dev
sudo pecl install xdebug

После PECL в конце вывода обычно показывают путь к xdebug.so. Его и нужно прописать в ini (см. следующий шаг).

Шаг 3. Найти xdebug.so и прописать zend_extension

Если ошибка «No such file or directory» остаётся, путь в конфиге неверный. Найдите файл:

find /usr/lib/php/ -name 'xdebug.so' 2>/dev/null
# иногда:
find /usr/lib/ -name 'xdebug.so' 2>/dev/null

Пример найденного пути: /usr/lib/php/20210902/xdebug.so (каталог 20210902 зависит от ABI PHP).

Откройте ini для нужной SAPI. Для PHP 8.1 типичные пути:

sudo nano /etc/php/8.1/cli/php.ini
sudo nano /etc/php/8.1/fpm/php.ini
# или Apache:
sudo nano /etc/php/8.1/apache2/php.ini
# удобнее отдельный drop-in:
# /etc/php/8.1/mods-available/xdebug.ini

Минимальная строка загрузки:

zend_extension=/usr/lib/php/20210902/xdebug.so

Если модуль лежит в стандартном extension_dir, иногда достаточно короткой формы (зависит от сборки):

zend_extension=xdebug

Перезапустите сервис, которым реально ходит приложение:

sudo systemctl restart php8.1-fpm
# или
sudo systemctl restart apache2
# nginx + php-fpm: достаточно рестарта fpm

Шаг 4. Проверить, что модуль реально загрузился

php --ini
php -v
php -m | grep -i xdebug

В php -v должна появиться строка вида:

with Xdebug v3.x.x, Copyright (c) 2002-2024, by Derick Rethans

Если в CLI всё ок, а в браузере нет, сравните вывод phpinfo() под веб-сервером: Loaded Configuration File и путь к zend_extension.

Шаг 5. Починка битых зависимостей

Если пакет поставился криво или после смены версии PHP остались «хвосты»:

sudo apt --fix-broken install
sudo apt autoremove
sudo apt clean

После смены major-версии PHP лучше переустановить phpX.Y-xdebug именно для новой X.Y, а не тащить старый .so.

Базовая настройка Xdebug 3 для локальной отладки

Для Xdebug 3 (порт по умолчанию 9003) типичный блок в conf.d / php.ini:

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log

Параметры xdebug.remote_enable / xdebug.remote_autostart относятся к Xdebug 2. В третьей ветке их не используют: вместо них mode, start_with_request, client_host, client_port.

После правок снова рестарт FPM/Apache и проверка:

sudo systemctl restart php8.1-fpm
php -m | grep -i xdebug

Краткий чеклист

• Версия PHP и пакет phpX.Y-xdebug совпадают.
• xdebug.so существует, путь в zend_extension верный.
• Правки внесены в ini той SAPI, которой пользуется приложение.
• Сервис перезапущен, php -m / phpinfo() показывают xdebug.
• Конфиг соответствует ветке Xdebug (2 vs 3).

Итог

Ошибка «Failed loading Zend extension ‘xdebug.so’» почти всегда сводится к отсутствующему пакету, чужому пути к .so или правке не того php.ini. Проверьте установку, найдите реальный файл модуля, пропишите zend_extension и перезапустите нужный PHP-сервис. После этого IDE сможет ловить брейкпоинты, а предупреждение в логах пропадёт.

Источники и ссылки