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 ブラウザで開かれたウェブサイトは、ブラウザのセキュリティモデルに基づいて WebSocket と HTTP リクエストを行うことができます。一意のデバッガセッション ID を取得するには、初期の HTTP 接続が必要です。同一オリジンポリシーにより、ウェブサイトが HTTP 接続を行うことが防止されます。DNS リバインディング攻撃に対する追加のセキュリティとして、Node.js は接続の「Host」ヘッダーが IP アドレスまたはlocalhostを正確に指定していることを検証します。
これらのセキュリティポリシーにより、ホスト名を指定してリモートデバッグサーバーに接続することが禁止されています。この制限を回避するには、IP アドレスを指定するか、下記で説明するように ssh トンネルを使用します。
インスペクタクライアント
node inspect myscript.jsを使用すると、最小限の CLI デバッガを使用できます。いくつかの商用およびオープンソースツールも Node.js インスペクタに接続できます。
Chrome DevTools 55+、Microsoft Edge
- オプション 1: Chromium ベースのブラウザでは
chrome://inspectを、Edge ではedge://inspectを開きます。「設定」ボタンをクリックし、ターゲットホストとポートがリストされていることを確認します。 - オプション 2:
/json/listの出力（上記参照）または--inspectヒントテキストからdevtoolsFrontendUrlをコピーし、Chrome に貼り付けます。
詳細については、https://github.com/ChromeDevTools/devtools-frontend、https://www.microsoftedgeinsider.comを参照してください。
Visual Studio Code 1.10+
- デバッグパネルで、設定アイコンをクリックして
.vscode/launch.jsonを開きます。初期設定には「Node.js」を選択します。
詳細については、https://github.com/microsoft/vscodeを参照してください。
JetBrains WebStorm およびその他の JetBrains IDE
- 新しい Node.js デバッグ構成を作成し、デバッグを開始します。Node.js 7+では
--inspectがデフォルトで使用されます。無効にするには、IDE レジストリでjs.debugger.node.use.inspectのチェックを外します。WebStorm およびその他の JetBrains IDE での Node.js の実行とデバッグの詳細については、WebStorm オンラインヘルプを参照してください。
chrome-remote-interface
- Inspector Protocolエンドポイントへの接続を容易にするライブラリ。 詳細はhttps://github.com/cyrus-and/chrome-remote-interfaceを参照してください。
Gitpod
- 「デバッグ」ビューから Node.js デバッグ構成を開始するか、
F5キーを押します。詳細な手順
詳細はhttps://www.gitpod.ioを参照してください。
Eclipse IDE with Eclipse Wild Web Developer extension
.jsファイルから「デバッグとして実行... > Node プログラム」を選択するか、デバッガーを稼働中の Node.js アプリケーション（--inspectで既に開始済み）にアタッチするデバッグ構成を作成します。
詳細はhttps://eclipse.org/eclipseideを参照してください。
コマンドラインオプション
以下の表は、様々な実行時フラグがデバッグに与える影響を示しています。
| フラグ | 意味 |
|---|---|
--inspect | Node.js インスペクターによるデバッグを有効にします。デフォルトのアドレスとポート（127.0.0.1:9229）でリスンします |
--inspect-brk | Node.js インスペクターによるデバッグを有効にします。デフォルトのアドレスとポート（127.0.0.1:9229）でリスンします。ユーザーコードの開始前にブレークします |
--inspect=[host:port] | インスペクターエージェントを有効にします。アドレスまたはホスト名 host（デフォルト：127.0.0.1）にバインドします。ポート port（デフォルト：9229）でリスンします |
--inspect-brk=[host:port] | インスペクターエージェントを有効にします。アドレスまたはホスト名 host（デフォルト：127.0.0.1）にバインドします。ポート port（デフォルト：9229）でリスンします。ユーザーコードの開始前にブレークします |
--inspect-wait | インスペクターエージェントを有効にします。デフォルトのアドレスとポート（127.0.0.1:9229）でリスンします。デバッガーがアタッチされるのを待ちます。 |
--inspect-wait=[host:port] | インスペクターエージェントを有効にします。アドレスまたはホスト名 host（デフォルト：127.0.0.1）にバインドします。ポート port（デフォルト：9229）でリスンします。デバッガーがアタッチされるのを待ちます。 |
node inspect script.js | --inspectフラグの下でユーザーのスクリプトを実行する子プロセスを生成し、メインプロセスを使用して CLI デバッガーを実行します。 |
node inspect --port=xxxx script.js | --inspectフラグの下でユーザーのスクリプトを実行する子プロセスを生成し、メインプロセスを使用して CLI デバッガーを実行します。ポート port（デフォルト：9229）でリスンします |
リモートデバッグシナリオの有効化
デバッガがパブリック IP アドレスでリスンすることを避けることをお勧めします。リモートデバッグ接続を許可する必要がある場合は、代わりに ssh トンネルを使用することをお勧めします。以下の例は説明目的でのみ提供されています。続行する前に、特権サービスへのリモートアクセスを許可することのセキュリティリスクを理解してください。
リモートマシン remote.example.com で Node.js を実行しており、デバッグしたいとします。そのマシンでは、インスペクタが localhost（デフォルト）のみをリスンするように node プロセスを開始する必要があります。
node --inspect app.jsデバッグクライアント接続を開始するローカルマシンで、ssh トンネルを設定できます。
ssh -L 9225:localhost:9229 remote.example.comこれにより、ローカルマシンのポート 9221 への接続が remote.example.com のポート 9229 に転送される ssh トンネルセッションが開始されます。これで、Chrome DevTools や Visual Studio Code などのデバッガを localhost:9221 に接続でき、Node.js アプリケーションがローカルで実行されているかのようにデバッグできるようになります。
従来のデバッガ
従来のデバッガは Node.js 7.7.0 以降非推奨になりました。--inspect と Inspector を使用してください。
バージョン 7 以前で--debugまたは--debug-brkスイッチで起動した場合、Node.js は廃止された V8 デバッグプロトコルで定義されたデバッグコマンドを TCP ポート（デフォルトでは5858）でリスンします。このプロトコルに対応するデバッガクライアントであれば、実行中のプロセスに接続してデバッグできます。一般的なクライアントをいくつか以下に示します。
V8 デバッグプロトコルは、もはや保守または文書化されていません。
組み込みデバッガ
node debug script_name.jsで起動すると、組み込みのコマンドラインデバッガでスクリプトが開始されます。スクリプトは--debug-brkオプションで開始された別の Node.js プロセスで開始され、最初の Node.js プロセスは_debugger.jsスクリプトを実行し、ターゲットに接続します。詳細はdocsを参照してください。
node-inspector
Chromium で使用されているInspector Protocolを Node.js で使用されている V8 Debugger protocol に変換する中間プロセスを用いて、Chrome DevTools で Node.js アプリケーションをデバッグします。詳細はhttps://github.com/node-inspector/node-inspectorを参照してください。