【Xdebug】リモートサーバに構築したコンテナにMacから接続する方法【Docker】

リモートサーバ上のLinux環境の上でPHPコンテナをDockerで立ち上げ、Xdebugを使いVisual Studio Codeからリモートデバッグを行う方法について設定に詰まりました。

結論としては、Linux環境ではXdebugの設定に利用するhost.docker.internalが使えないため、VSCodeの設定が必要でした。

環境によるXdebugの設定の違い

ブレークポイントでとまらない原因と対策

ローカルマシン（Mac）上では同じような設定で接続できるのに、開発用にLinuxをリモートサーバとしてVScodeで接続したところ、Xdebugがブレークポイントで止まらずに解決するまでに少々時間がかかりました。設定周りを調べていてそもそもLinuxでDockerコンテナを立ち上げる場合とMac/WindowsでDockerコンテナを立ち上げる場合の違いがありました。

どうやらLinux環境でDockerを使用する場合、host.docker.internalがデフォルトで利用できないようです。設定を追加することもできるようですが、Linuxの場合はDockerを立ち上げるホストマシンのIPを指定することがよさそうです。

Linux で host.docker.internal が繋がらないのは接続先が Docker のイーサネットブリッジを Listen していないからかもしれない

HosokowaRさんのスクラップ

https://zenn.dev

Dockerコンテナ内にhost.docker.internalが適用されているかを確認する方法 | clameyes

Dockerを活用して開発を進めている中で、ローカル環境のAPIにDockerコンテナのアプリからアクセスしたいと思う場合があります。Linux(Ubuntu)を使っている際に、このような状況に直面しました。そこでh...

https://bou7254.com

Docker環境でも、Mac/WindowsとLinuxでは設定が違う

MacやWindowsのDockerではDockerはLinuxカーネルを必要としています。つまりDocker (Desktop)がこの仮想化レイヤーを管理し、ホストとコンテナ間の通信をしているため、host.docker.internalが立ち上がっています。

反面、Linux環境ではホストがLinuxなのでMacやWindowsほどの仮想化レイヤーがいらない。従ってDNS解決のためのいらないわけです。なるほど確かに。調べてみるとその通りですがhost.docker.internalの設定はもはや一つの記号として見ていたので、調べるまで全然意識していませんでした。

というわけで、PHPコンテナに組み込むXdebug.iniの設定は以下のようになります。

Xdebugの設定(Linux)

1
2
3
4
5

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=192.168.1.100  # Linuxの時(ホストのIPアドレス)
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

Xdebugの設定(Mac/Windows)

1
2
3
4
5

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host =host.docker.internal # Mac/Windowsの時(host.docker.internalを利用)
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

VScodeのlaunch.jsonの設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

"configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003, // xdebug.iniで設定したポート番号
            "pathMappings": {
                // Dockerのドキュメントルート:ローカルのドキュメントルート
                "/var/www/html/": "${workspaceRoot}/src"
            }
        },