Node.js 检查调试器

一、技能概述

该技能适用于需要使用 Inspector 权限进行 Node.js 调试的场景。其默认首选使用 node inspect 命令行调试器，只在需要脚本化断点、自动化状态捕获、堆快照或 CPU 性能分析时，才会使用 Chrome DevTools Protocol (CDP)。

二、核心功能

1. 快速启动调试

技能提供了多种启动调试会话的方式：

2. 调试器 REPL 命令

在调试会话中，可以使用以下命令进行交互式调试：

退出注意：如果进程应继续运行，先执行 cont 再退出；否则直接终止。

3. OpenClaw 项目调试技巧

技能包含针对 OpenClaw 项目的调试优化建议：

• Inspector 绑定：优先使用 127.0.0.1，不要暴露 --inspect=0.0.0.0，除非网络是隔离的

• Vitest 调试：使用单 worker 调试单文件，避免 stepping 时使用 worker 池

• TypeScript 源码断点：使用 --enable-source-maps 有助于 node inspect 显示源码路径

• 子进程调试：NODE_OPTIONS=--inspect-brk 可将 inspector 传播给子进程，但每个子进程需要独立端口

• 长生命周期进程：通过 PID 附加，先用 /json/list 确认目标

4. 程序化 CDP（Chrome DevTools Protocol）

当需要脚本化断点、自动化状态捕获时，可以使用 CDP 进行编程控制：

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();
})();

工具安装：在仓库外临时安装 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

5. CPU 与堆内存性能分析

技能支持通过 CDP 进行性能分析：

三、主要用途

1. 隐藏变量与异步挂起调试 —— 定位难以追踪的异步调用链和闭包变量

2. 不稳定测试（Flaky Tests）排查 —— 通过断点和单步执行定位测试间歇性失败的原因

3. 子进程与启动竞态调试 —— 调试多进程架构中的初始化顺序问题

4. 内存增长（Memory Growth）分析 —— 通过堆快照对比定位内存泄漏

5. CPU 热点（CPU Hot Paths）定位 —— 通过 CPU 性能分析找出性能瓶颈

6. OpenClaw CLI 与 Vitest 调试 —— 专门针对 OpenClaw 项目的调试场景

四、重要原则

1. 默认使用 node inspect：除非需要 CDP 的脚本化能力，否则优先使用命令行调试器

2. 不要暴露 --inspect=0.0.0.0：除非网络隔离，否则存在安全风险

3. Vitest 调试使用单 worker：避免 worker 池干扰 stepping 过程

4. 子进程需要独立端口：NODE_OPTIONS=--inspect-brk 可传播 inspector，但每个子进程需要自己的端口

5. --inspect vs --inspect-brk：--inspect 不会在启动时暂停；需要在代码运行前完成设置时使用 --inspect-brk

6. 默认端口 9229：并行调试多个目标时使用 --inspect=0 或指定唯一端口

7. 断点未命中时检查：确认文件路径、source map 行为，以及执行是否已越过该行

8. 进程冻结处理：detach 后进程看似冻结，实际可能仍暂停在调试器中

总结：Node Inspect Debugger 是 OpenClaw 项目中用于 Node.js 深度调试的技能，通过 node inspect 命令行调试器和 Chrome DevTools Protocol (CDP) 两种方式，覆盖隐藏变量、异步挂起、不稳定测试、子进程、启动竞态、内存增长和 CPU 热点等调试场景。它提供了从快速启动到程序化控制的完整调试能力，并包含针对 OpenClaw CLI 和 Vitest 测试的专门调试技巧。