mcpField
N
node-inspect-debugger

node-inspect-debugger

github.com/openclaw开发393.9k292 次安装今天更新
代码仓库

关于 node-inspect-debugger

面向 Node.js 开发者的 Inspector 调试 Skill，提供交互式检查及 Chrome DevTools Protocol 编程工作流的指导。涵盖断点、进程附加以及 CPU 和堆分析。

主要功能

  1. 01使用 node inspect 交互调试
  2. 02附加到现有进程
  3. 03通过 CDP 设置脚本断点
  4. 04采集堆快照和 CPU 分析
  5. 05调试测试及子进程

适用场景

  1. 01调查异步卡住或不稳定的测试
  2. 02附加到长期运行的 Node.js 进程
  3. 03分析 CPU 热点或内存增长
  4. 04自动采集断点状态

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/openclaw/openclaw --skill node-inspect-debugger

安装后在 Claude Code 中输入/node-inspect-debugger确认已加载。

详细介绍

Node Inspect 调试器

用于需要检查器访问权限的 Node.js 调试：隐藏的局部变量、异步卡死、不稳定测试、子进程、启动竞态、内存增长或 CPU 热点路径。

默认优先使用 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 命令行路径：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，使用一个工作线程调试一个文件。单步执行时避免使用工作线程池。
  • 对于 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 或唯一端口。
  • 如果断点未命中，请确认文件路径、源映射行为，以及执行是否已经越过该行。
  • 如果分离后进程看似冻结，它可能仍处于调试器的暂停状态。

评论

支持 Markdown