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

Частая ошибка при настройке отладки PHP:

PHP Warning: Failed loading Zend extension 'xdebug.so' (tried: /usr/lib/php/20230831/xdebug.so ...): cannot open shared object file: No such file or directory

PHP пытается загрузить Xdebug, но файла нет там, где он его ищет. Разберём причины по порядку.

Почему так бывает

  • Xdebug не установлен для той версии PHP, которая запускается.
  • В системе несколько версий PHP, а расширение поставили только для одной.
  • В php.ini прописан старый путь, например после обновления PHP поменялся каталог расширений.
  • Расширение подключено дважды: и в php.ini, и в conf.d.

Шаг 1. Какая версия PHP работает

php -v
php --ini
php -i | grep extension_dir

Номер каталога, например 20230831, это версия API, он свой для каждой ветки PHP (8.3 в этом примере). Расширение должно лежать именно там.

Учтите, что у консоли, PHP-FPM и Apache могут быть разные версии и разные файлы php.ini.

Шаг 2. Установка из пакетов

sudo apt update
sudo apt install php8.3-xdebug

Подставьте свою версию. Пакет сам кладёт файл в нужный каталог и создаёт /etc/php/8.3/mods-available/xdebug.ini, вручную ничего прописывать не надо.

Если пакета для вашей версии нет в репозитории, можно собрать через PECL:

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

После этого добавьте в php.ini строку zend_extension=xdebug.

Шаг 3. Проверка путей

find /usr/lib/php -name xdebug.so
grep -rn xdebug /etc/php/

Если в каком-то файле указан полный путь к несуществующему каталогу, исправьте его или замените на короткое zend_extension=xdebug: тогда PHP сам возьмёт файл из extension_dir. Повторы удалите.

Шаг 4. Настройки Xdebug 3

Если вы переносите старую конфигурацию, помните, что в Xdebug 3 параметры поменялись. Минимальный набор для пошаговой отладки:

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Порт по умолчанию теперь 9003, а не 9000. Старые параметры вроде xdebug.remote_enable больше не действуют.

Шаг 5. Перезапуск и проверка

sudo systemctl restart php8.3-fpm   # или apache2
php -v

В выводе должна появиться строка вида with Xdebug v3.x.x. Для веб-сервера проверьте через phpinfo().

Важно для боевых серверов

Xdebug заметно замедляет PHP, даже когда отладка не идёт. На рабочем сервере его лучше не держать включённым: sudo phpdismod xdebug.

Связанные статьи

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


Комментарии загружаются…