在Node.js服务端开发中，我们经常通过child_process模块创建子进程来处理耗时任务、隔离危险操作或利用多核资源。但当子进程内部发生逻辑错误时，传统的console.log往往不够用，而主进程断点又无法命中子进程代码。要真正看清子进程的执行路径，需要理解Node.js的调试协议与进程派生机制。
为什么子进程难以调试
Node.js主进程在启动时若带上--inspect参数，会开启一个基于WebSocket的调试服务，默认端口为9229。但使用child_process.spawn或exec启动的新进程，是操作系统级别的全新node实例，它并不会自动继承父进程的调试端口。子进程拥有自己的内存空间与事件循环，调试客户端如果没有显式连接过去，就完全观察不到它的运行状态。
另一个常见误区是认为只要在父进程代码里打了断点，子进程执行的同一份文件就会停下。实际上父子进程只是共享了磁盘上的脚本文件，V8引擎实例相互独立。如果子进程以普通方式启动，它内部抛出的未捕获异常只会触发exit事件，主进程拿到的往往只是一个退出码，没有堆栈细节。
使用fork并开启调试端口
child_process.fork是专为Node.js脚本设计的派生方式，默认建立IPC通信通道，且能方便地传递执行参数。我们可以在fork的options中通过execArgv注入--inspect-brk，让子进程启动后立刻暂停，等待调试器接入。这样就能在VS Code或Chrome DevTools里看到第二个调试目标。
下面的例子展示如何让子进程在9229端口之外的9333端口等待调试，并在父进程中打印出子进程的pid方便核对：
const { fork } = require('child_process');
const child = fork('./worker.js', [], {
execArgv: ['--inspect-brk=9333'],
stdio: 'inherit'
});
child.on('message', (msg) => {
console.log('来自子进程的消息:', msg);
});
console.log('子进程pid:', child.pid);
对应的worker.js可以写一段简单的循环，并在开头预留断点位置：
// worker.js
console.log('子进程启动');
let sum = 0;
for (let i = 0; i < 5; i++) {
sum += i;
}
console.log('计算结果:', sum);
process.send({ done: true });
这种方式的优点是父子进程调试端口分离，互不干扰；缺点是手动管理多个端口比较麻烦。在VS Code中，我们可以配置多个调试配置，分别attach到不同端口，也可以使用复合启动（compounds）一次性挂上。
通过环境变量统一调试
如果不想写死端口，可以利用NODE_OPTIONS环境变量。Node.js在启动时会读取该变量中的参数，因此父进程在spawn子进程前，将NODE_OPTIONS设为包含--inspect-brk的字符串，子进程就会自动开启调试。这个方法对spawn同样有效。
示例代码如下，我们在启动子进程时把调试端口定为随机可用端口，并通过子进程 stderr 抓取它打印出的调试地址：
const { spawn } = require('child_process');
const env = Object.assign({}, process.env, {
NODE_OPTIONS: '--inspect-brk=9344'
});
const child = spawn('node', ['./worker.js'], {
env: env,
stdio: ['inherit', 'inherit', 'pipe']
});
child.stderr.on('data', (data) => {
const text = data.toString();
if (text.includes('Debugger listening')) {
console.log('子进程调试信息:', text);
}
});
使用环境变量的好处是无需改动fork的execArgv，适合在测试脚本或CI中临时开启。但要注意NODE_OPTIONS在某些精简镜像中可能受限制，且不能和子进程自身的--inspect冲突，否则会启动失败。
捕获子进程的异常与输出
调试不仅靠断点，也要靠日志与异常拦截。建议在子进程入口处监听uncaughtException与unhandledRejection，将堆栈通过process.send或标准错误流抛给父进程。父进程则统一收集，避免子进程静默崩溃。
下面的代码演示了子进程内自我保护，以及父进程汇总日志的做法：
// worker.js 增强版
process.on('uncaughtException', (err) => {
console.error('子进程未捕获异常:', err.stack);
process.exit(1);
});
process.on('unhandledRejection', (reason) => {
console.error('子进程未处理的Promise拒绝:', reason);
});
setTimeout(() => {
throw new Error('模拟子进程错误');
}, 500);
// parent.js
const { fork } = require('child_process');
const child = fork('./worker.js', [], { silent: true });
child.stdout.on('data', d => console.log('[子stdout]', d.toString()));
child.stderr.on('data', d => console.log('[子stderr]', d.toString()));
child.on('exit', (code) => console.log('子进程退出码:', code));
通过silent模式与流监听，父进程相当于拥有了一个集中式日志面板。配合调试器断点，能快速区分是逻辑错误还是环境差异导致的问题。
在VS Code中的实践配置
VS Code的launch.json支持attach模式。我们可以先以调试方式启动父进程，待子进程fork出来后，再使用另一个attach配置连到子进程端口。更高级的做法是使用compounds字段，让编辑器并行启动两个调试会话。
一个典型的配置片段如下，其中第一个配置调试主进程，第二个配置在9333端口等待子进程：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "调试主进程",
"program": "${workspaceFolder}/parent.js"
},
{
"type": "node",
"request": "attach",
"name": "调试子进程",
"port": 9333
}
],
"compounds": [
{
"name": "同时调试父子",
"configurations": ["调试主进程", "调试子进程"]
}
]
}
这样点击“同时调试父子”，编辑器会先跑主进程，子进程因--inspect-brk暂停，随后attach配置连上，断点即可在两份文件间自由跳转。对于排查跨进程的上下文传递错误，这种工作流非常高效。
小结与避坑要点
调试Node.js子进程的核心在于让其继承或显式获得调试参数，并建立可观察的通信链路。fork适合纯JS脚本，spawn配合NODE_OPTIONS适合任意命令。不要依赖默认日志，要主动监听异常与流。
常见坑包括：子进程使用了不同版本的Node导致调试协议不兼容；父进程退出早于子进程使调试会话断开；以及在生产环境忘记关闭--inspect-brk，造成端口暴露。掌握上述方法后，跨进程问题将不再神秘。
Node.jschild_processdebug修改时间：2026-08-04 20:54:21