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

如何为 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,调试时必须显式开启
相关推荐
恋猫de小郭4 分钟前
Jetpack Compose 1.13 发布,憋了这么久终有交代了
android·前端·flutter
头发还在的女程序员35 分钟前
智慧物业源码解析:房屋档案与业主变更怎样保持历史业务连续
前端·javascript·vue.js·物业管理·小区物业·智慧物业
JianZhen✓44 分钟前
电商 SKU 选择器:后端只给扁平列表,前端怎么反推规格矩阵并做到 O(1) 命中
前端·矩阵·状态模式
feixing_fx9 小时前
第一个 JS 程序:在浏览器控制台和 Node 中分别运行
开发语言·前端·javascript·前端框架·ecmascript
feixing_fx10 小时前
变量与声明:let、const、var 的选择边界
开发语言·前端·javascript·前端框架
JavaGuide13 小时前
Cloudflare 开源的这套神级安全审计 Skill 太好用了!
前端·后端
孟健14 小时前
用 unslop 拯救 AI 生成网页的塑料感,7 分钟重构落地实测
前端·人工智能·ai编程
feixing_fx14 小时前
JavaScript 是什么:从浏览器脚本到通用编程语言
开发语言·前端·javascript·前端框架·ecmascript
丘山望岳14 小时前
【开发工具】 cluade code常用快捷键
前端
小巫编程室14 小时前
我造了一个 Java 能力包:让 AI 直接调用你的业务代码
java·前端·后端