Уже писал гайдик на эту тему, но там я рассказывал о процессе настройки на примере PHP7. Решил обновить информацию, т.к. PHP 8 используется 3я версия xdebug, а также есть нюансы, связанные с определением адреса клиентского хоста.
Проблема
Вы разрабатываете на PHP в WSL (например, Ubuntu), используешь PHP-FPM 8+, и хотите отлаживать код через VS Code.
Решение
Сначала проверим/установим xdebug.
Выяснить можно либо, выполнив файл php с кодом <?php phpinfo(); ?> — и проверить есть ли секция с xdebug. Она большая — и выглядит как то так:
Либо второй вариант — запустить из консоли:
|
1 |
php-fpm8.1 -v |
И убедиться, что в выводе есть строка «with Xdebug v3.XXX»
Если xdebug не установлен — давайте установим.
|
1 2 |
sudo apt-get update sudo apt install php8.1-xdebug |
Настроить xdebug.ini
Для fpm конфиг типично лежит вот тут:
|
1 |
/etc/php/8.1/fpm/conf.d/20-xdebug.ini |
Пример содержимого:
|
1 2 3 4 5 6 7 8 9 |
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=localhost xdebug.client_port=9003 xdebug.log=/var/log/xdebug_remote.log # xdebug.log_level=10 # xdebug.idekey=VSCODE |
После изменений конфы, не забываем про:
|
1 |
sudo service php8.1-fpm restart |
IDE KEY
Для VSCODE — ключ указывать не надо, т.к. по умолчанию он не требуется, потому что:
Xdebug теперь сам запускает сессию, если включено xdebug.start_with_request=yes
Большинство IDE (VS Code, PHPStorm) не требуют сравнения IDE Key — они слушают все входящие отладочные сессии.
Узнаём IP хоста из WSL
Может быть проблема с тем, чтобы понять какой хост указать в качестве клиентского (т.е. что писать для xdebug.client_host).
Когда речь идёт о Xdebug в WSL, часто возможны три сценария:
- PHP и VS Code оба в WSL →
127.0.0.1(localhost). - PHP в WSL, VS Code в Windows (без WSL Remote) → нужен IP Windows-хоста.
- Docker в WSL2 → сложнее:
host.docker.internal, мосты, порты и т.д.
Чтобы получить адрес в случае 2, попробуйте выполнить:
|
1 |
ip route | grep default |
или иногда:
|
1 |
cat /etc/resolv.conf | grep nameserver |
Перебрав эти варианты, вы скорее всего найдете правильный.
В WSL 2 (начиная с Windows 10 2004+) можно использовать host.docker.internal, но:
- Это работает только если включён флаг networkingMode: bridged (например, в Docker Desktop)
- В обычном WSL — лучше использовать IP из
ip route
Настройка отладки в VS Code
Нужно создать/проверить .vscode/launch.json:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}" } } ] } |
Там может быть много конфигураций, в примере указана лишь наша «Listen for Xdebug». Здесь надо настроить порт и pathMappings.
Логи
Если xdebug запускается, то он создаёт файл лога, который можно мониторить, и пока идет настройка можно установить уровень логирования в 10 (xdebug.log_level).
|
1 |
sudo tail -f /var/log/xdebug_remote.log |
Если ip клиента указан не верно, то там будут ошибки вроде: Could not connect to debugging client
Запуск отладки
Нажмите shift+ctrl+D и выберите конфигу «Listen for Xdebug». VS Code начнет слушать порт, ожидая отладочную информацию от xdebug.
Если вы задали точки останова (breakpoints), то при выполнении кода xdebug передаст данные VSCode, и вы сможете начать отладку.
