node-inspect-debugger

Node Inspect Debugger 用于需要 inspector 访问权限的 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 绑定 inspector。除非网络隔离，不要暴露 --inspect=0.0.0.0。
对 Vitest，使用单 worker 调试单个文件。单步调试时避免 worker 池。
对 TS 源码断点，必要时使用 --enable-source-maps；node inspect 仍可能显示编译后的路径。
对子进程，NODE_OPTIONS=--inspect-brk 可以传播 inspector，但每个子进程需要自己的端口。
对长期运行的 gateway 或 dev 进程，先用 /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 或唯一端口。
如果断点未命中，确认文件路径、source map 行为，以及执行是否已经越过该行。
如果分离后进程看起来冻结，它可能仍暂停在调试器中。

适用场景：Node.js 调试、异步问题排查、测试不稳定分析、子进程调试、内存与 CPU 性能分析。

限制：资料未提供该技能的收费、价格、平台支持范围或效果保证等信息。

技能介绍