PHP：WSL+DockerでのPHPデバッグ方法

公開：2026.04.19 22:06

WSL+DockerでのPHPデバッグ方法

WSL Docker上に構築したPHPコンテナをWindows上のVSCodeからデバッグする方法。

環境

◆ Windows 11 25H2 (26200.8037) + WSL + Docker
◆ WSL：

PS C:\Users\xxx> wsl --version
WSL バージョン: 2.3.24.0
カーネル バージョン: 5.15.153.1-2
WSLg バージョン: 1.0.65
MSRDC バージョン: 1.2.5620
Direct3D バージョン: 1.611.1-81528511
DXCore バージョン: 10.0.26100.1-240331-1435.ge-release
Windows バージョン: 10.0.26200.8037

◆ Ubuntu：

xxx@xxx:~$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 24.04.1 LTS
Release: 24.04
Codename: noble

PHP環境は過去記事「Docker 学習 #4：Docker Composeを学ぶ」で作成したPHPコンテナを使用する。

手順

1. PHPコンテナに接続

docker exec -it (CONTAINER ID) /bin/bash

※ (CONTAINER ID)は "docker ps" コマンドで確認。

2. PHPコンテナにxdebugをインストール

PHPコンテナにて以下コマンドを実行

pecl install xdebug

実行結果：

root@05fa4e42bbcd:/usr/local/lib/php/HTML# pecl install xdebug
downloading xdebug-3.5.1.tgz ...
Starting to download xdebug-3.5.1.tgz (282,739 bytes)
..........................................................done: 282,739 bytes
115 source files, building
　：省略
Build process completed successfully
Installing '/usr/local/lib/php/extensions/no-debug-non-zts-20230831/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.5.1
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20230831/xdebug.so" to php.ini
     

3. xdebug.ini作成

WSL上にxdebug.iniを作成する。
保存場所は compose.yaml と同じ階層(~/docker/php)とした。

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes

; VSCode側へ接続する
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

; ログ（トラブル時）
xdebug.log=/tmp/xdebug.log
    

4. xdebug.iniをコンテナへコピー

以下コマンドでxdebug.iniをコンテナにコピーする。(CONTAINER ID)は "docker ps" コマンドで確認。

docker cp ./xdebug.ini (CONTAINER ID):/usr/local/etc/php/conf.d/xdebug.ini

実行結果：

root@xxx:~/docker/php# docker cp ./xdebug.ini 05fa4e42bbcd:/usr/local/etc/php/conf.d/xdebug.ini
Successfully copied 207B (transferred 2.05kB) to 05fa4e42bbcd:/usr/local/etc/php/conf.d/xdebug.ini
    

5. コンテナ再起動

docker restart (CONTAINER ID)

実行結果：

root@xxx:~/docker/php# docker restart 05fa4e42bbcd
05fa4e42bbcd
    

6. VSCodeにPHP Debug拡張機能をインストール

Windows上のVSCodeに "PHP Debug (xdebug.org)" をインストールする。

7.デバッグできない・・
WSL(Ubuntu)のIPアドレスを調べる。

ip route

実行結果：

  root@xxx:~/docker/php# ip route
  default via 172.25.0.1 dev eth0 proto kernel
  　：
    

8. debug.ini修正

PHPコンテナに接続し /usr/local/etc/php/conf.d/xdebug.ini を修正。
vimにて修正しようと思ったが "bash: vim: command not found" になってしまったのでvimをインストール。

実行結果：

root@05fa4e42bbcd:/usr/local/etc/php/conf.d# apt install vim
　：省略
Processing triggers for libc-bin (2.41-12+deb13u2) ...      
    

"vim /usr/local/etc/php/conf.d.xdebug.ini" コマンドで xdebug.iniを修正
xdebug.client_host= の値を先ほど 7. で調べたIPアドレスに変更する。

9. コンテナ再起動

10. デバッグ実行

デバッグできました。

---

PHP WSL Docker VSCode デバッグ