node-inspect-debugger

Node Inspect デバッガー

隠れたローカル変数、非同期処理のハング、不安定なテスト、子プロセス、起動時の競合、メモリの増加、CPU のホットパスなど、インスペクターへのアクセスが必要な Node.js のデバッグに使用します。

まずは node inspect を使用してください。スクリプトによるブレークポイント、自動化された状態のキャプチャ、ヒープスナップショット、CPU プロファイルが必要な場合に限り、Chrome DevTools Protocol を使用してください。

クイックスタート

• 起動時に一時停止：node inspect path/to/script.js
• TypeScript：node --inspect-brk --import tsx path/to/script.ts
• 既存の PID：kill -SIGUSR1 <pid> の後に node inspect -p <pid>
• インスペクターのターゲット一覧：curl -s http://127.0.0.1:9229/json/list | jq
• OpenClaw CLI のパス：node --inspect-brk openclaw.mjs ...
• OpenClaw テストのパス：OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

デバッガー REPL

• 続行／ステップ実行：cont、next、step、out、pause
• ブレークポイント：sb('file.js', 42)、sb(42)、sb('functionName')、breakpoints、cb('file.js', 42)
• 調査：bt、list(8)、watch('expr')、exec expr
• 現在のスコープ：repl を実行してから、ローカル変数を直接評価します。Ctrl+C で REPL モードを終了します。
• 安全に終了する：プロセスを続行する場合は、終了前に cont を実行します。続行しない場合は kill を実行します。

OpenClaw のヒント

• インスペクターのバインドには 127.0.0.1 を優先してください。ネットワークが隔離されていない限り、--inspect=0.0.0.0 を公開しないでください。
• Vitest では、ワーカーを 1 つにして単一のファイルをデバッグしてください。ステップ実行中はワーカープールを使用しないでください。
• TS ソースのブレークポイントでは、必要に応じて --enable-source-maps を使用してください。node inspect には出力されたパスが表示される場合があります。
• 子プロセスでは、NODE_OPTIONS=--inspect-brk でインスペクターを引き継げますが、各子プロセスには個別のポートが必要です。
• 長時間稼働するゲートウェイや開発プロセスでは、/json/list でターゲットを確認してから、PID を指定して接続してください。

プログラムからの CDP 利用

プロジェクトがすでに依存している場合を除き、リポジトリの外部にツールをインストールしてください。

mkdir -p /tmp/cdp-tools
npm --prefix /tmp/cdp-tools i chrome-remote-interface
NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs

最小構成のドライバー：

const CDP = require("chrome-remote-interface");

(async () => {
  const client = await CDP({ port: 9229 });
  const { Debugger, Runtime } = client;

  Debugger.paused(async ({ callFrames, reason }) => {
    const top = callFrames[0];
    console.log("paused", reason, top.url, top.location.lineNumber + 1);
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: "JSON.stringify({ pid: process.pid })",
    });
    console.log(result.value ?? result.description);
    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();
  await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 });
  await Runtime.runIfWaitingForDebugger();
})();

プロファイル

• CPU：Profiler を有効にし、start を実行して待機後、stop を実行します。/tmp/profile.cpuprofile に書き込み、Chrome DevTools で開きます。
• ヒープ：HeapProfiler を有効にし、addHeapSnapshotChunk でデータを収集してから、takeHeapSnapshot を呼び出し、/tmp/heap.heapsnapshot に書き込みます。

注意点

• --inspect は一時停止しません。コードの実行前にセットアップが必要な場合は --inspect-brk を使用してください。
• デフォルトのポートは 9229 です。並列のターゲットには --inspect=0 または一意のポートを使用してください。
• ブレークポイントで停止しない場合は、ファイルパス、ソースマップの動作、実行がすでにその行を通過していないかを確認してください。
• デタッチ後にプロセスがフリーズしたように見える場合、デバッガーで一時停止したままになっている可能性があります。