如何为 Node.js 多层子进程启动调试（以 OpenClaw 为例）

问题背景

项目使用 pnpm gateway:watch:debug 启动后，在 chrome://inspect/#devices 的 Sources 页签只能看到 scripts/run-node.mjs，看不到任何业务代码文件。

根本原因

该项目的启动链分三层：

watch-node.mjs（顶层 watch 进程）
  └── node --inspect --watch ... run-node.mjs（中间层，负责构建判断）
       └── node openclaw.mjs（实际业务进程）

--inspect flag 只加在了中间层 run-node.mjs 上，真正运行业务代码的 openclaw.mjs 没有携带该 flag，所以 Chrome DevTools 看不到业务代码。

解决思路

需要让 --inspect 沿着进程链一路传递到最终的业务进程，同时避免多个进程抢占同一调试端口。

具体改动

1. scripts/watch-node.mjs — 分离 inspect flag，不污染其他子进程

原来的逻辑会把所有参数（包括 --inspect）直接传给子进程，导致 NODE_OPTIONS 污染所有下游进程引发端口冲突。改为显式分离：

const inspectFlags = deps.args.filter(
  (a) => a === "--inspect" || a === "--inspect-brk" 
      || a.startsWith("--inspect=") || a.startsWith("--inspect-brk="),
);
const filteredArgs = deps.args.filter((a) => !inspectFlags.includes(a));

if (inspectFlags.length > 0) {
  childEnv.OPENCLAW_DEBUG_BUILD = "1";
  childEnv.OPENCLAW_INSPECT_FLAGS = inspectFlags.join(" ");
}

const watchProcess = deps.spawn(execPath, [...inspectFlags, ...buildWatchArgs(filteredArgs)], ...);

• inspectFlags 作为 Node 参数直接传给中间进程（不经过 shell 环境变量）
• OPENCLAW_INSPECT_FLAGS 存入环境变量，供下一层读取
• OPENCLAW_DEBUG_BUILD=1 触发带 sourcemap 的构建

2. scripts/run-node.mjs — 将 inspect flag 转发给业务进程

const inspectNodeArgs = deps.env.OPENCLAW_INSPECT_FLAGS
  ? deps.env.OPENCLAW_INSPECT_FLAGS.split(" ")
      .filter(Boolean)
      .map((flag) => {
        if (flag === "--inspect") return "--inspect=0";
        if (flag === "--inspect-brk") return "--inspect-brk=0";
        return flag;
      })
  : [];

const nodeProcess = deps.spawn(execPath, [...inspectNodeArgs, "openclaw.mjs", ...deps.args], ...);

使用 --inspect=0 让操作系统自动分配空闲端口，避免与父进程的 9229 端口冲突。

3. tsdown.config.ts — debug 构建时开启 sourcemap

const isDebugBuild = process.env.OPENCLAW_DEBUG_BUILD === "1";

// 在 nodeBuildConfig 中：
...(isDebugBuild ? { sourcemap: true, minify: false } : {}),

没有 sourcemap，DevTools 只能看到编译后的 JS，无法映射到 TypeScript 源文件。

4. package.json — 新增调试命令

"gateway:watch:debug": "node scripts/watch-node.mjs --inspect gateway --force"

最终效果

启动后终端输出：

Debugger listening on ws://127.0.0.1:XXXXX/...

在 chrome://inspect/#devices 中可以看到业务进程的调试 target，点击后 Sources 页签显示完整的 TypeScript 源文件，可正常打断点调试。

关键经验

1. 多层子进程调试，每层都需要 --inspect，但不能共享同一端口
2. 用 --inspect=0 而不是固定端口，让 OS 自动分配，彻底避免冲突
3. 不要用 NODE_OPTIONS 传 inspect flag，会污染所有子孙进程，导致批量端口冲突
4. sourcemap 缺失是常见遗漏，生产构建通常关闭 sourcemap，调试时必须显式开启