Xdebug in VSCode With Docker

Table of Contents

참고 원문:

목표

컨테이너 안에서 실행되는 PHP를 VSCode에서 브레이크포인트 기반으로 디버깅합니다.

1) Xdebug 설정 (xdebug.ini)

1zend_extension=xdebug.so
2xdebug.mode=develop,debug
3xdebug.start_with_request=yes
4xdebug.client_port=9003
5xdebug.client_host=<HOST_IP>
6xdebug.log=/dev/stdout
7xdebug.log_level=0

핵심 포인트:

  • xdebug.client_host: IDE가 실행되는 호스트 IP
  • xdebug.client_port: VSCode와 동일 포트 사용(기본 9003)
  • xdebug.start_with_request=yes: 요청마다 디버깅 시작

호스트 IP 확인 예시:

1# macOS
2ipconfig getifaddr en0
3
4# WSL
5grep nameserver /etc/resolv.conf | cut -d ' ' -f2
6
7# Linux
8hostname -I | cut -d ' ' -f1

2) VSCode 확장 설치

  • 확장: PHP Debug (Xdebug 지원)

3) launch.json 설정

.vscode/launch.json에 아래 구성을 추가합니다.

 1{
 2  "version": "0.2.0",
 3  "configurations": [
 4    {
 5      "name": "Listen for Xdebug (Docker)",
 6      "type": "php",
 7      "request": "launch",
 8      "port": 9003,
 9      "pathMappings": {
10        "/var/www/html": "${workspaceFolder}"
11      }
12    }
13  ]
14}

pathMappings는 컨테이너 내부 코드 경로와 로컬 프로젝트 경로를 정확히 맞추는 것이 핵심입니다.

4) 동작 확인 절차

  1. 컨테이너 재시작
  2. VSCode에서 "Listen for Xdebug" 시작
  3. 브라우저/테스트 요청 실행
  4. 브레이크포인트 정지 확인

자주 막히는 포인트

  1. client_host가 잘못됨
  2. 컨테이너 내부 코드 경로와 pathMappings 불일치
  3. 9003 포트 충돌 또는 방화벽 차단
  4. FPM/웹서버에 Xdebug 설정이 로드되지 않음

정리

Docker + VSCode Xdebug는 client_host, port, pathMappings 3가지만 정확히 맞추면 대부분 안정적으로 동작합니다.

Programming PHPXdebugVSCodeDocker