SSH トンネル経由のリモートデバッグ

このチュートリアルでは、SSH トンネル (SSH ポート転送とも呼ばれます) を使用して、Xdebug を実行しているリモートサーバーと PhpStorm を実行している開発マシンとの間に安全な接続を設定する方法について説明します。これは、間にファイアウォールがある場合、NAT ルーターが直接接続を妨げている場合、または ISP またはネットワークインフラストラクチャが開発者マシンへの受信 TCP 接続を許可していない場合に、リモートマシンでコードをデバッグできます。

リモートサーバーが開発者マシンに直接接続できる場合 (たとえば、Vagrant マシンを使用)、SSH トンネルは必要ない場合もあります。

前提条件

1. デバッガーはリモートサーバー上にセットアップされています

デバッグを開始する前に、PHP アプリケーションが実行される Web サーバーにデバッグエンジンがインストールされ、適切に構成されていることを確認してください。

PhpStorm は、最も人気のある 2 つのツール、Xdebug(英語) と Zend デバッガー(英語)によるデバッグをサポートしています。これらのツールは、互いにブロックし合うため、同時に使用することはできません。この問題を回避するには、Xdebug を構成するおよび Zend デバッガーの構成に従って、関連する PHP インタープリターの php.ini ファイルを更新する必要があります。

例: Xdebug では、サーバーの php.ini で次の設定が指定されていることを確認します。

                    [xdebug]
                    zend_extension="<path to xdebug extension>"
                    xdebug.mode=debug
                    xdebug.client_host=127.0.0.1
                    xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"
                

                    [xdebug]
                    zend_extension="<path to xdebug extension>"
                    xdebug.remote_enable=1
                    xdebug.remote_host=127.0.0.1
                    xdebug.remote_port="<the port (9000 by default) to which Xdebug connects>"
                

zend_extension : Xdebug デバッグエンジンを使用することを示す設定。xdebug に設定するか、/usr/lib/php/20190902/xdebug.so などの xdebug.so ファイルへのフルパスを使用します。
xdebug.mode : 有効にする Xdebug 機能を制御する設定。デバッグの場合は debug に設定します。
xdebug.client_host : PhpStorm が実行され、Xdebug からの受信接続を待機している IP アドレスまたはホスト名。
xdebug.client_port : PhpStorm が実行されるホスト上で Xdebug が接続を試みるポート。デフォルトのポートは 9003 です。

2. PhpStorm では受信デバッガー接続のリッスンが有効になっています

PhpStorm では、次のいずれかを実行して、受信デバッグ接続のリッスンを有効にします。

ツールバー / ステータスバーのをクリックします。
メインメニューで実行 | PHP デバッグ接続のリッスンを開始を選択します。

これにより、Web サーバーでデバッグセッションが開始されると PhpStorm が反応し、デバッグツールウィンドウが自動的に開きます。デバッグセッションを開始する前に、ブレークポイントが設定されているか、設定ダイアログ Ctrl+Alt+S のデバッグページで PHP スクリプトの最初の行で中断するオプションが有効になっていることを確認してください。

SSH トンネルをセットアップする

デバッグセッションを開始すると、Xdebug がリモートサーバーから、PhpStorm がリッスンしている開発者マシンのポートへの TCP 接続を開始します。

SSH ポート転送の考え方は、リモートサーバー上に「仮想」TCP ポートを作成し、そのトラフィックを開発者マシン上の TCP ポートに送信して、トラフィックを SSH 経由でトンネリングすることです。

SSH トンネルをセットアップする

SSH ポート転送を設定するには、コマンドラインで次の ssh コマンドを実行します。

ssh -R 9003:localhost:9003 username@hostname

ssh -R 9000:localhost:9000 username@hostname

ssh -R 10137:localhost:10137 username@hostname

9003:localhost:9003 の 9003: は、 Xdebug 接続が localhost に転送される SSH サーバー (転送ホスト) 上のポートです。
9003:localhost:9003 の localhost:9003 は、SSH クライアント (PhpStorm を実行しているマシン) の IP アドレスと、Xdebug 接続が転送されるポートです。localhost は、基本的にこの ssh コマンドを実行しているマシンです。
username@hostname は、SSH サーバー (転送ホスト) のアドレスと、そのサーバーでの SSH 認証に必要なユーザー名です。

SSH トンネルが正常に設定されていることを確認するには、PhpStorm ブックマークレット、ブラウザーデバッグ拡張機能、または PhpStorm を使用した PHP CLI スクリプトのデバッグで概説されている手法を使用して、リモートサーバーでデバッグセッションを開始します。PhpStorm が受信接続を検出するとすぐに、それを受け入れるように求める Xdebug からの受信接続ダイアログが表示されます。

PhpStorm でのデバッグプロセスの詳細については、ゼロコンフィギュレーションデバッグおよび中断されたプログラムを調べるを参照してください。

リモート PHP インタープリターまたは SSH トンネルを介して PHP CLI スクリプトをデバッグする

リモート PHP インタープリターが適切に設定されている場合、デバッグにリモート PHP インタープリターを利用して実行 / デバッグ構成を作成することが可能です。

SSH トンネルが稼働したら、PHP CLI スクリプトもデバッグできます。デバッガーはリモートマシン上で実行されるため、CLI デバッグセッションを開始するには、PHP コマンドラインスイッチを使用するか、（リモートマシン上の）環境変数を使用します。このワークフローは公式に推奨されているデバッグ方法ではありませんが、リモートサーバー側からデバッグセッションを確立する必要がある場合には便利です。

トラブルシューティング

デバッガーが接続しない、または接続を拒否する

デバッガーが接続できないか、接続を拒否する場合は、次の点を確認してください。

Xdebug が 127.0.0.1 およびポート 9000（Xdebug 2 の場合）またはポート 9003（Xdebug 3 の場合）に接続するように構成されていることを確認します。
Zend デバッガーを使用する場合は、PhpStorm ブックマークレットまたは Browser DebuggingExtension が 127.0.0.1 に接続するように構成されていることを確認してください。
SSH トンネルを設定する前に、PhpStorm が受信デバッガー接続をリッスンしていることを確認してください。
マシンが再起動されるか接続が失われると、SSH トンネルを再確立する必要があります。

リモートファイルパスがプロジェクト内のファイルパスにマップされていません

場合によってはデバッガーに接続できますが、リモートとプロジェクトファイル間のマッピングが定義されていないことを示すエラーメッセージが表示されます。これは、PhpStorm がデバッグ中のファイルに対応するローカルファイルを判別できないことを意味します。

この問題は、クリックしてパスマッピングを設定するをクリックして、必要なパスマッピングを提供することで解決できます。さらに、Web サーバーに接続するで概説されている手法を使用して、これらのマッピングを構成できます。

2026 年 1 月 08 日

関連ページ：

Vagrant

Vagrant は、仮想マシンのライフサイクルを管理するために使用されるコマンドラインユーティリティです。PhpStorm は Vagrant と完全に統合されており、Vagrant 仮想環境を構成し、仮想マシンの動作を制御し、プロジェクト内から Vagrant コマンドを実行できます。Vagrant を使用する場合、次の定義が満たされます。Vagrantfile: Vagrant 環境を定義し、仮想ボックスのすべての構成を格納し、仮想マシンの操作方法を Vagrant に指示するメイン構成ファイ...

Xdebug を構成する

Xdebug をダウンロード PHP バージョンと互換性のある Xdebug 拡張をダウンロードし、Xdebug インストールガイドの説明に従ってインストールします。事前構成された AMP (Apache、MySQL、PHP) パッケージを使用している場合は、Xdebug 拡張機能がすでにインストールされている可能性があります。パッケージに固有の手順を参照してください。Xdebug と PHP エンジンの統合アクティブな php.ini ファイルをエディターで開きます。デバッグエンジンが PhpStor...

デバッグツールウィンドウ

デバッガーセッションを開始すると、デバッグツールウィンドウが開きます。このウィンドウを使用して、デバッガーセッションを制御し、プログラムデータ (フレーム、変数など) を表示および分析し、デバッガーアクションを実行します。デフォルトでは、プログラムがブレークポイントに到達したときにデバッグツールウィンドウが開き、セッションが終了しても非表示になりません。この動作を変更するには、ビルド、実行、デプロイ | デバッガー設定ページに移動し、ブレークポイントでデバッグウィンドウを表示するチェックボック...

ブレークポイント

ブレークポイントは、特定のポイントでプログラムの実行を一時停止する特別なマーカーです。これにより、プログラムの状態と動作を調べることができます。ブレークポイントは、たとえば、特定のコード行に到達したときにプログラムを一時停止するなどの単純なものから、追加の条件をチェックしたり、ログに書き込んだりするなどのより複雑なロジックを含むものまであります。ブレークポイントは、一度設定すると、一時的なブレークポイントを除き、明示的に削除するまでプロジェクト内に残ります。ブレークポイントの種類：PhpSto

デバッグ

このページを使用して、Xdebug と Zend デバッガーの動作を設定します。事前構成この領域には、デバッガーのインストール、デバッガーのクッキーを制御してデバッグセッションを開始 / 停止するを実行するブックマークレットの生成、およびゼロコンフィギュレーションデバッグの起動に関する簡単なガイドラインが示されています。外部接続この領域で、PhpStorm がホストから受信した接続、デプロイサーバー構成として登録されていないポートを介した接続をどのように処理するかを指定します。未登録のサーバー構...

PHP CLI スクリプトをデバッグする

PHP アプリケーションは、必ずしも Web アプリケーションではありません。さまざまなコマンドラインツール、デーモン、メッセージキュー処理アプリケーション、その他の種類のアプリケーションは、通常、PHP CLI で実行されます。PHP CLI デバッグセッションを開始するには、いくつかの方法があります。PhpStorm 内から起動し、スクリプトを起動してデバッガーをアタッチすることができます。または、PhpStorm に受信デバッガー接続をリッスンさせ、IDE の外部でスクリプトを開始すること...