Node.jsのデバッグ

このガイドは、Node.jsアプリケーションとスクリプトのデバッグを開始するのに役立ちます。

インスペクターを有効にする

--inspectスイッチで起動すると、Node.jsプロセスはデバッグクライアントをリッスンします。 デフォルトでは、ホストとポート127.0.0.1:9229でリッスンします。 各プロセスには、一意のUUIDも割り当てられます。

インスペクタークライアントは、接続するためにホストアドレス、ポート、およびUUIDを知っていて、指定する必要があります。 完全なURLは、ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55eのようになります。

Node.jsは、SIGUSR1シグナルを受信した場合にも、デバッグメッセージのリッスンを開始します。 （SIGUSR1はWindowsでは使用できません。）Node.js 7以前では、これはレガシーデバッガーAPIをアクティブにします。 Node.js 8以降では、インスペクターAPIがアクティブになります。

セキュリティへの影響

デバッガーはNode.js実行環境にフルアクセスできるため、このポートに接続できる悪意のある行為者は、Node.jsプロセスに代わって任意のコードを実行できる可能性があります。 パブリックネットワークとプライベートネットワークでデバッガーポートを公開することのセキュリティへの影響を理解することが重要です。

デバッグポートを公開することは安全ではありません

デバッガーがパブリックIPアドレスまたは0.0.0.0などにバインドされている場合、IPアドレスに到達できるクライアントはすべて、制限なしにデバッガーに接続でき、任意のコードを実行できます。

デフォルトでは、node --inspectは127.0.0.1にバインドされます。 デバッガーへの外部接続を許可する場合は、パブリックIPアドレスまたは0.0.0.0などを明示的に指定する必要があります。 そうすることで、潜在的に重大なセキュリティの脅威にさらされる可能性があります。 セキュリティの脆弱性を防ぐために、適切なファイアウォールとアクセス制御が設定されていることを確認することをお勧めします。

リモートデバッガークライアントの安全な接続を許可する方法については、「リモートデバッグシナリオの有効化」セクションを参照してください。

ローカルアプリケーションはインスペクターにフルアクセスできます

インスペクターポートを127.0.0.1（デフォルト）にバインドした場合でも、マシンでローカルに実行されているアプリケーションはすべて無制限にアクセスできます。 これは、ローカルデバッガーが簡単に接続できるようにするための設計です。

ブラウザ、WebSockets、および同一オリジンポリシー

Webブラウザで開いているWebサイトは、ブラウザのセキュリティモデルの下でWebSocketおよびHTTPリクエストを行うことができます。 一意のデバッガーセッションIDを取得するには、初期HTTP接続が必要です。 同一オリジンポリシーにより、WebサイトはこのHTTP接続を行うことができなくなります。 DNSリバインディング攻撃に対する追加のセキュリティとして、Node.jsは、接続の「ホスト」ヘッダーがIPアドレスまたはlocalhostを正確に指定していることを確認します。

これらのセキュリティポリシーにより、ホスト名を指定してリモートデバッグサーバーに接続できなくなります。 この制限は、IPアドレスを指定するか、以下で説明するようにsshトンネルを使用することで回避できます。

インスペクタークライアント

最小限のCLIデバッガーは、node inspect myscript.jsで使用できます。 いくつかの商用およびオープンソースツールもNode.jsインスペクターに接続できます。

Chrome DevTools 55+、Microsoft Edge

• オプション1：Chromiumベースのブラウザでchrome://inspectを開くか、Edgeでedge://inspectを開きます。 「設定」ボタンをクリックし、ターゲットホストとポートがリストされていることを確認します。
• オプション2：/json/listの出力（上記を参照）または--inspectヒントテキストからdevtoolsFrontendUrlをコピーしてChromeに貼り付けます。

Node.jsとChromeは同じプラットフォームで実行する必要があることに注意してください。

Visual Studio Code 1.10+

• デバッグパネルで、設定アイコンをクリックして.vscode/launch.jsonを開きます。 初期設定として「Node.js」を選択します。

Visual Studio 2017+

• メニューから「デバッグ」>「デバッグの開始」を選択するか、F5キーを押します。
• 詳細な手順.

JetBrains WebStormおよびその他のJetBrains IDE

• 新しいNode.jsデバッグ構成を作成し、「デバッグ」をクリックします。 --inspectは、Node.js 7+のデフォルトで使用されます。 無効にするには、IDEレジストリでjs.debugger.node.use.inspectのチェックを外します。 WebStormおよびその他のJetBrains IDEでのNode.jsの実行とデバッグの詳細については、WebStormオンラインヘルプをご覧ください。

chrome-remote-interface

• インスペクタープロトコルエンドポイントへの接続を容易にするライブラリ。

Gitpod

• 「デバッグ」ビューからNode.jsデバッグ構成を開始するか、F5キーを押します。 詳細な手順

Eclipse IDEとEclipse Wild Web Developer拡張機能

• .jsファイルから、「デバッグ」>「Nodeプログラム」を選択するか、
• 実行中のNode.jsアプリケーション（既に--inspectで開始されている）にデバッガーを接続するためのデバッグ構成を作成します。

コマンドラインオプション

次の表に、デバッグに対するさまざまなランタイムフラグの影響を示します

リモートデバッグシナリオの有効化

デバッガをパブリック IP アドレスでリッスンさせることは決して推奨しません。リモートデバッグ接続を許可する必要がある場合は、代わりに ssh トンネルを使用することをお勧めします。以下は、説明のみを目的とした例です。続行する前に、特権サービスへのリモートアクセスを許可することのセキュリティリスクを理解してください。

リモートマシン remote.example.com で Node.js を実行していて、デバッグできるようにしたいとします。そのマシンでは、インスペクターが localhost（デフォルト）のみをリッスンするように node プロセスを開始する必要があります。

node --inspect server.js

次に、デバッグクライアント接続を開始するローカルマシンで、ssh トンネルを設定できます。

ssh -L 9221:localhost:9229 [email protected]

これは、ローカルマシンのポート 9221 への接続が remote.example.com のポート 9229 に転送される ssh トンネルセッションを開始します。これで、Chrome DevTools や Visual Studio Code などのデバッガを localhost:9221 に接続できます。Node.js アプリケーションがローカルで実行されているかのようにデバッグできるはずです。

レガシーデバッガ

レガシーデバッガは Node.js 7.7.0 で非推奨になりました。代わりに --inspect とインスペクターを使用してください。

バージョン 7 以前で **--debug** または **--debug-brk** スイッチを使用して開始すると、Node.js は、廃止された V8 デバッグプロトコルで定義されたデバッグコマンドを TCP ポート（デフォルトでは 5858）でリッスンします。このプロトコルを話すデバッガクライアントは、実行中のプロセスに接続してデバッグできます。一般的なものがいくつか以下にリストされています。

V8 デバッグプロトコルは、もはや保守も文書化もされていません。

組み込みデバッガ

node debug script_name.js を開始して、組み込みのコマンドラインデバッガでスクリプトを開始します。スクリプトは、--debug-brk オプションで開始された別の Node.js プロセスで開始され、最初の Node.js プロセスは _debugger.js スクリプトを実行してターゲットに接続します。

node-inspector

Chromium で使用されているインスペクタープロトコルを Node.js で使用されている V8 デバッガプロトコルに変換する中間プロセスを使用して、Chrome DevTools で Node.js アプリをデバッグします。