Node インスペクトデバッガー は何をしますか？
Node.jsのデバッグでインスペクタアクセスが必要な場合に使用します。隠れたローカル変数、非同期ハング、不安定なテスト、子プロセス、起動時の競合、メモリ増大、CPUのホットパスなどが対象です。
まずは node inspect をデフォルトとして使用してください。スクリプトによるブレークポイントの設定、自動状態取得、ヒープスナップショット、CPUプロファイルが必要な場合にのみChrome DevTools Protocol (CDP) を使用します。
クイックスタート
- エントリで一時停止:
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つのファイルを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または一意のポートを使用してください。 - ブレークポイントが機能しない場合は、ファイルパス、ソースマップの動作、コードが既にその行を通過したかどうかを確認してください。
- デタッチ後にプロセスがフリーズしたように見える場合、デバッガでまだ一時停止している可能性があります。