Отображения путей¶

Отображения путей переводят между путями, которые знает отлаживаемая программа, и путями на вашей машине. Они нужны всякий раз, когда код выполняется не там, где он правится.

Когда они нужны¶

PHP в Docker-контейнере, где проект примонтирован в /app.
Любой адаптер, подключённый к процессу на другой машине.
Код, собранный в контейнере и отлаживаемый на хосте.

Они не нужны, когда программа работает локально из тех же путей, которые вы правите, — а это обычный случай для Rust, Go и Python.

Случай PHP¶

[profiles.docker]
adapter = "php"
program = "."

[profiles.docker.launch_arguments]
sessionMode = "server"
port = 9003
pathMappings = { "/app" = "${root}" }

Читается как путь в контейнере = путь на хосте. Xdebug сообщает /app/src/index.php, Bugsaur превращает это в <корень>/src/index.php, который ваш редактор способен открыть.

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

Несколько монтирований¶

pathMappings = { "/app" = "${root}", "/vendor-src" = "${root}/vendor" }

Порядок не важен, используется самый длинный совпавший префикс.

Как не ошибиться в отображении¶

Самая частая ошибка — угадывать путь внутри контейнера. Спросите у контейнера, вместо того чтобы предполагать:

docker compose exec php pwd
docker compose exec php ls /app

Сверьте это с записью volumes: в вашем docker-compose.yml:

services:
  php:
    volumes:
      - .:/app          # хост . -> контейнер /app

Слева в томе путь хоста, справа путь контейнера, и pathMappings повторяет эту пару.

Признаки неверного отображения¶

Симптом	Что означает
Отладчик останавливается, но исходника не показывает	сообщённого пути локально не существует
Точки останова остаются `pending` и не привязываются	пути хоста никогда не совпадают с путями контейнера
Открывается не тот файл, но на правильном номере строки	префикс отображён не в тот каталог
Всё работает, кроме одного каталога	у второго монтирования нет отображения

Полный разбор: Диагностика → Исходник не найден.

Для других адаптеров¶

pathMappings — ключ, который читает именно PHP-адаптер. У других адаптеров свои аналоги, и они передаются через launch_arguments без изменений — например, source map у CodeLLDB:

[profiles.remote]
adapter = "codelldb"
program = "build/app"

[profiles.remote.launch_arguments]
sourceMap = { "/build" = "${root}" }

Как называется ключ и что он принимает — дело адаптера; Bugsaur передаёт тело как есть. См. Адаптеры.