Node.js Inspector：从断点、Worker 到崩溃诊断

一个 Node.js 服务只在打包后的生产制品里偶发卡住。开发者连接调试器后能看到主线程仍在处理定时器，于是判断进程没有问题；真正积压任务的却是同一 PID 内的 worker。另一次异常栈准确指向 src/order.ts，但该行在当前提交里根本不会抛错。最后发现发布目录混入了上一轮构建的 .map 文件。调试器显示的文件名和行号很精确，却不等于调试对象与源码身份正确。

还有一种更危险的“修复”：为了远程连接方便，把 Inspector 监听改成所有网卡，并把 WebSocket URL 当成密码。Inspector 客户端可以求值表达式、改写全局状态和控制执行，URL 中的 UUID 只是定位会话的地址，不承担认证。可靠的 Node.js 调试必须同时回答四件事：连的是哪个 isolate，源码映射属于哪次构建，诊断制品泄露了什么，以及调试入口是否已经彻底退出。

Node.js Inspector 与诊断证据链从回环 Inspector 与 CDP Session 进入主线程、Worker、Source Map 和 Diagnostic Report，再以构建身份、容量边界和退出复查约束现场。高清原图

先认清 Inspector 连接的不是一个只读日志窗口

Node.js 把 V8 Inspector 暴露为 Chrome DevTools Protocol，简称 CDP。启动参数创建 Inspector 服务，发现端点返回目标及 WebSocket URL，客户端再通过这个通道启用 Runtime、Debugger、Profiler 等 domain。每条连接都持有自己的 Session 状态：启用过哪些 domain、设置了哪些断点、选择了哪个调用帧，都不会因为进程还活着就自动成为可恢复事务。断开后重连，要重新建立这些状态。

--inspect 在用户代码继续执行时开放入口；--inspect-brk 在用户脚本开头暂停；目标发行线支持时，--inspect-wait 会等待客户端连接后再开始执行。无人连接时，后两种等待语义会直接改变启动可用性。默认监听是 127.0.0.1:9229，把端口写成 0 可以由系统分配一次性端口。下文以 Node.js 24 LTS CLI 文档作为示例口径；项目使用其他发行线时必须切换到对应版本页，不能用滚动 latest 页面替代实际版本。

CDP 的 Runtime.evaluate 能在目标进程权限下执行表达式，Debugger.pause 会改变事件循环推进，变量修改还可能影响后续请求。能访问 Inspector 的身份，实质上获得了目标进程的代码执行和内存读取能力。Node.js 调试安全说明明确反对把该端口暴露到公网；即使只监听回环，本机其他进程也可能连接，所以主机登录权、进程用户和会话时限仍是安全边界。

安装从 Node.js 发行线开始，而不是安装一个 Inspector 包

Inspector、内置调试器和 node:inspector 都随 Node.js 提供，不需要全局安装第三方调试服务。先在项目真实运行环境核对版本与二进制来源：

node --version
node -p "JSON.stringify({execPath:process.execPath,v8:process.versions.v8,modules:process.versions.modules})"

第一条确定 Node.js 发行线，第二条把实际可执行文件、V8 和模块 ABI 放进证据。团队应从 Node.js Releases选择仍受维护的生产发行线，再核对该发行线的 Inspector、source map 与 report 文档。Current 中出现的新参数不能直接写进旧 LTS 的启动模板，发行线处于 LTS 也不意味着所有第三方 Inspector 前端都已验证兼容。

后面的 CDP WebSocket 示例要求全局 WebSocket 可用；它从 Node.js 20.10/21.0 开始提供，到 22.4 才标记稳定，而且仍可被 --no-experimental-websocket 关闭。Worker 示例还使用 Node.js 19 引入的 node:inspector/promises。因此不能只写“Node.js 20+”便假设两段代码都能运行：启动前分别检查 typeof WebSocket 与 import('node:inspector/promises')，不满足时使用项目锁定的 WebSocket 客户端或回调式 node:inspector，并把实际分支写进证据。

本地最小启动使用随机端口，避免和另一个开发进程争抢 9229：

node --inspect=127.0.0.1:0 app.mjs

标准错误应出现类似 Debugger listening on ws://127.0.0.1:<port>/<uuid> 的消息。随后只从回环读取发现端点：

curl http://127.0.0.1:<port>/json/list

预期 JSON 中至少有 type: "node"、目标标题和 webSocketDebuggerUrl。端口可连但 /json/list 没有预期目标，或客户端连接后没有完成 CDP 命令响应，都不能算调试成功。--inspect-publish-uid 可以控制 UUID 是否发布到 stderr 和 HTTP 发现面，但隐藏某个发现入口不是认证措施。

Unix 平台还存在一条容易被忽略的动态入口：向进程发送 SIGUSR1 可以激活 Inspector，--inspect-port 决定此时使用的地址与端口。线上进程即使启动命令没有 --inspect，也要核对信号权限、进程管理器和实际监听；目标发行线支持 --disable-sigusr1 时可显式关闭，不支持时则由 OS 信号权限与运行账户隔离承担边界。Windows 没有这条 SIGUSR1 路径。一次来源不明的 9229 监听，不能在未核对启动参数和信号事件前归因于“部署模板偷偷打开了调试”。

正向实验：沿发现端点进入 CDP，并证明状态确实被修改

下面的实验只使用合成变量和一次性进程。先创建 target.mjs：

globalThis.family39 = 41;

console.log(`target pid=${process.pid}`);
setInterval(() => {
  console.log(`family39=${globalThis.family39}`);
}, 2000);

启动目标，把 stderr 中的随机端口记为 <port>：

node --inspect=127.0.0.1:0 target.mjs

先执行 node -p "typeof WebSocket"。输出为 function 才能直接运行下面的 evaluate.mjs；若输出 undefined，应改用项目已经锁定和审计的 WebSocket 客户端，并把依赖版本记入实验清单，不要临时下载未知脚本。

const endpoint = process.argv[2];

if (!endpoint || typeof WebSocket !== 'function') {
  throw new Error('usage: node evaluate.mjs <webSocketDebuggerUrl>; WebSocket is required');
}

const ws = new WebSocket(endpoint);
let completed = false;
const timeout = setTimeout(() => {
  console.error('CDP_TIMEOUT');
  process.exitCode = 2;
  ws.close();
}, 5000);

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    id: 1,
    method: 'Runtime.evaluate',
    params: {
      expression: 'globalThis.family39 = 42',
      returnByValue: true
    }
  }));
});
ws.addEventListener('message', ({ data }) => {
  const message = JSON.parse(String(data));
  if (message.id !== 1) return;
  clearTimeout(timeout);
  completed = true;
  if (message.error) {
    console.error(JSON.stringify(message.error));
    process.exitCode = 3;
    ws.close();
    return;
  }
  console.log(JSON.stringify(message.result.result));
  ws.close();
});
ws.addEventListener('error', () => {
  clearTimeout(timeout);
  process.exitCode = 4;
});
ws.addEventListener('close', () => {
  clearTimeout(timeout);
  if (!completed && process.exitCode === undefined) process.exitCode = 5;
});

从 /json/list 复制完整 webSocketDebuggerUrl 后执行：

node evaluate.mjs 'ws://127.0.0.1:<port>/<uuid>'

客户端成功时退出码为 0，并打印包含 value: 42 的 CDP 结果；目标随后从 family39=41 变为 family39=42。超时、协议错误、WebSocket 错误和响应前断开分别留下非零退出码，不能把一个沉默挂起的客户端算作通过。这组证据同时证明了目标身份、协议响应和运行状态改变；只保存“已连接”截图会漏掉连错进程的可能。实验结束时向目标发送正常终止信号，并确认随机端口不再监听。

反向实验：UUID 不会缩小通配监听的暴露面

安全反例只需要证明监听地址错误，不需要从第二台主机实施连接，更不应在共享网络中模拟攻击。把同一个合成目标改成：

node --inspect=0.0.0.0:0 target.mjs

Linux 可用 ss -ltnp，Windows 可用下面的命令核对监听对象：

Get-NetTCPConnection -State Listen |
  Where-Object OwningProcess -eq <pid> |
  Select-Object LocalAddress, LocalPort, OwningProcess

预期反向证据是 0.0.0.0、:: 或平台等价的通配地址，而不是“外部连接已经成功”。仍能从回环取得 UUID，只说明发现端点可用，不能证明其他网卡不可达。立即终止该进程，恢复 127.0.0.1:0 并再次检查 IPv4 与 IPv6 监听，直到目标 PID 没有残留端口。

远程目标保持回环监听，通过受控 SSH 本地转发进入：

ssh -N -L 9229:127.0.0.1:<remote-port> user@debug-host

客户端只连工作站的 127.0.0.1:9229。SSH 主机身份、账号授权和审计承担远程边界；Inspector 自身没有因此获得多租户认证。容器还要检查端口发布和 Service 配置，回环绑定不能抵消错误的宿主网络模式或额外代理。

同一个 PID 内，主线程与 Worker 是不同调试对象

Worker Threads 在同一进程中创建独立 JavaScript 执行线程和 isolate，threadId 不是 PID。Node.js 24 Worker Threads 文档说明了 execArgv 继承和线程身份。外部客户端显示主进程已连接，并不自动证明每个 worker 都已选择、暂停或设置断点。

node:inspector 提供进程内 CDP Session。worker 内调用 session.connect() 连接当前 worker 的 Inspector backend；只有在 worker 中才能调用 connectToMainThread() 连接主线程。下面的完整实验用 API 级证据区分二者：

import { Session } from 'node:inspector/promises';
import { Worker, isMainThread, parentPort, threadId } from 'node:worker_threads';

if (isMainThread) {
  globalThis.runtimeRole = 'main';
  const worker = new Worker(new URL(import.meta.url));
  worker.on('message', console.log);
} else {
  globalThis.runtimeRole = `worker-${threadId}`;

  const own = new Session();
  own.connect();
  const ownResult = await own.post('Runtime.evaluate', {
    expression: 'globalThis.runtimeRole',
    returnByValue: true
  });
  own.disconnect();

  const main = new Session();
  main.connectToMainThread();
  const mainResult = await main.post('Runtime.evaluate', {
    expression: '({pid:process.pid, role:globalThis.runtimeRole})',
    returnByValue: true
  });
  main.disconnect();

  parentPort.postMessage({
    workerThreadId: threadId,
    workerRole: ownResult.result.value,
    main: mainResult.result.value
  });
}

运行 node worker-inspector.mjs，预期 workerThreadId 为非零值，workerRole 类似 worker-1，而 main.role 为 main；worker 与 main 返回相同 PID。若外部前端只能看见主目标，应以该前端实际 target 列表和断点命中证据验收，不能把某个客户端的自动附加体验写成 Node.js 的协议保证。

同线程 Session.connect() 适合这里的无暂停求值，却不适合在同一个执行线程给自己设置断点：被暂停的程序与负责恢复它的调试器是同一线程，可能形成自锁。真正需要断点时，应从 worker 用 connectToMainThread() 控制主线程，或使用独立进程经 WebSocket 连接。这个边界也解释了为什么“进程内 API 能求值”不能自动推出“进程内断点方案可用”。

还要警惕 preload 递归。worker 默认继承不影响进程级状态的 Node 参数；如果 --require 或 --import 的 preload 无条件创建 worker，每个新 worker 可能再次加载 preload 并继续扩张。项目创建 worker 时应显式审查 execArgv，worker pool 则用 AsyncResource 关联任务与回调，让异步诊断能回到业务任务，而不是只剩无上下文的线程编号。

Source Map 只有与生成物同身份时才是证据

--enable-source-maps 让异常栈在读取 Error.stack 时尽力把生成位置映射到原始源码。它不能补回缺失 map，也不能判断 map 是否来自同一次构建；覆盖 Error.prepareStackTrace 还可能阻止默认映射。频繁构造并读取错误栈的服务应在真实负载下测量延迟，不能把开关当成零成本格式美化。

一个可解释的项目实验可以使用已锁定的 TypeScript 编译器：

npm install --save-dev --save-exact typescript@<approved-version>
npx tsc --version

创建 tsconfig.json，让编译器同时生成 JavaScript 与外部 map：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "inlineSources": true,
    "strict": true
  },
  "include": ["src/**/*.ts"]
}

再创建 src/boom.ts。它只包含合成值，不读取环境或业务数据：

function normalizeOrder(input: string): never {
  const normalized = input.trim().toUpperCase();
  throw new Error(`synthetic failure: ${normalized}`);
}

normalizeOrder('family-39');

编译后分别运行生成文件：

npx tsc --project tsconfig.json
node dist/boom.js
node --enable-source-maps dist/boom.js

预期第一份栈指向 dist/boom.js，第二份指向 src/boom.ts 的 throw 行。为了让过期 map 反例不依赖随手编辑，先把当前 map 保存为构建 A：

node -e "require('node:fs').copyFileSync('dist/boom.js.map','boom-a.js.map')"

然后把 src/boom.ts 完整替换为构建 B；新增的两行会同时改变生成文件和原始源码位置：

function normalizeOrder(input: string): never {
  const normalized = input.trim().toUpperCase();
  const prefix = 'synthetic';
  const message = `${prefix} failure: ${normalized}`;
  throw new Error(message);
}

normalizeOrder('family-39');

重新编译并保存 B 的正确 map，再故意把 A 的 map 覆盖到 B：

npx tsc --project tsconfig.json
node -e "const f=require('node:fs');f.copyFileSync('dist/boom.js.map','boom-b.js.map');f.copyFileSync('boom-a.js.map','dist/boom.js.map')"
node --enable-source-maps dist/boom.js

反向结果可能是错误的原始行、缺失映射，或仍落到生成文件；稳定判据不是背诵某个行号，而是它不能同时满足“指向构建 B 的 throw 语句”和“map 摘要属于构建 B”。恢复 boom-b.js.map 后重新运行，栈才应指向 B 的实际抛错语句：

node -e "require('node:fs').copyFileSync('boom-b.js.map','dist/boom.js.map')"
node --enable-source-maps dist/boom.js

每次对照都计算并保存生成文件与 map 的摘要：

node -e "const fs=require('node:fs'),c=require('node:crypto'); for(const f of ['dist/boom.js','dist/boom.js.map']) console.log(f,c.createHash('sha256').update(fs.readFileSync(f)).digest('hex'))"

发布证据应绑定源码提交、lockfile、Node.js 与编译器版本、生成文件摘要、map 摘要和部署制品 ID。浏览器能打开某个 .ts 文件、函数名看起来合理，都不能替代这组身份关系。

Diagnostic Report 是敏感现场，不是普通 JSON 日志

Node.js 24 Diagnostic Report可以通过 API、未捕获异常、fatal error 或受支持平台的信号产生 JSON 摘要，包含 JavaScript/native 栈、堆统计、libuv handle、平台信息和 worker 报告。它默认还可能包含环境变量与网络接口；Windows 不支持信号触发。excludeNetwork 从 Node.js 20.13/22.0 提供，excludeEnv 从 22.13/23.3 提供；较旧发行线没有这些字段，不能用属性不存在时静默跳过来宣称报告已减敏。这些开关也只减少指定字段，不会把命令行、路径、主机名、模块或 handle endpoint 全部脱敏。

项目可把显式诊断入口写成默认关闭的函数：

import { mkdirSync } from 'node:fs';

export function writeDiagnosticReportIfRequested() {
  if (process.env.ENABLE_NODE_REPORT !== '1') return null;

  const directory = process.env.NODE_REPORT_DIR;
  if (!directory) throw new Error('NODE_REPORT_DIR is required');
  mkdirSync(directory, { recursive: true, mode: 0o700 });

  if ('excludeEnv' in process.report) process.report.excludeEnv = true;
  if ('excludeNetwork' in process.report) process.report.excludeNetwork = true;
  process.report.directory = directory;
  return process.report.writeReport();
}

mode: 0o700 只影响新建目录，在 Windows 上也不等同于受限 ACL；目录已经存在时，它不会自动收紧旧权限。实际包装器还要拒绝符号链接或越出批准根目录的解析结果，并按平台验证 owner、ACL 和可写空间。上面的函数只展示“默认关闭、排除字段、显式目录”三项应用接入，不承担完整的证据目录配置。

在纯合成环境中调用一次，使用 Node.js 自身解析 JSON，只输出字段是否存在，不要用 cat 把整份报告回显到终端或 CI 日志：

node -e "const fs=require('node:fs');const p=process.argv[1],r=JSON.parse(fs.readFileSync(p,'utf8'));console.log({reportVersion:r.header?.reportVersion,hasEnv:'environmentVariables' in r,hasNetwork:'networkInterfaces' in (r.header ?? {})})" <report-path>

environmentVariables 位于报告顶层，而 networkInterfaces 位于 header；检查错层级会让网络排除在未生效时也显示 false。预期在目标版本支持且开关生效时，hasEnv 与 hasNetwork 都为 false；再用一份没有排除开关的纯合成报告做反证，预期二者为 true，才能证明检测器本身没有恒为假。这仍不是“报告已脱敏”的证明。报告、heap snapshot、CPU profile 和 Inspector 中展开的变量都可能带有 token、Cookie、请求正文、密钥和个人数据，必须进入受限加密存储，传输前审查，到期销毁；真实现场不得上传公共工单、聊天、普通 CI 制品区或第三方在线分析服务。

进程退出以后，Inspector 会话不能变成事后调试器

Inspector 的 WebSocket、UUID、断点和调用帧都依赖活着的 isolate。进程崩溃后，重启一个同版本服务再打开原 URL，不会恢复旧堆、旧事件循环或旧 Session；端口复用甚至可能把客户端带到另一个实例。崩溃后可用的是事先或崩溃路径实际写出的 Diagnostic Report、heap snapshot、CPU/heap profile、操作系统 core，以及与它们匹配的 Node.js 可执行文件、native addon、生成物和 source map。Diagnostic Report 只有堆统计与栈等摘要，不是完整堆转储，也不能替代 core 中的 native 状态。

现场分流先看证据是否真的存在：进程仍活着且允许暂停，才用 Inspector/CDP；进程已退出但 report 已落盘，先核对 report 中的进程、Node/V8、事件与制品身份；只有 core 与匹配 native 符号可用时，转入受控的 core/native 调试链。没有预采集制品时，应明确记录“状态不可恢复”，再通过合成复现、持续 profile 或下一次崩溃策略补证，不能把新进程的断点结果伪装成旧事故结论。

项目接入要默认关闭，并把容量失败写成明确结果

仓库适合保存诊断策略和脚本，不适合保存报告、heap snapshot、profile、WebSocket URL 或真实变量。可以为本地和受控诊断副本提供独立脚本：

{
  "scripts": {
    "debug:local": "node --inspect-brk=127.0.0.1:0 --enable-source-maps dist/server.js",
    "diagnose:local": "node --inspect=127.0.0.1:0 --enable-source-maps dist/server.js"
  }
}

普通 start 不带 Inspector，不等待客户端。共享环境由短期部署参数打开入口，记录服务、构建、PID、监听地址、owner、批准和到期时间，但不记录完整 UUID、表达式或变量值。若需要自动生成 report，包装器应在启动前检查输出目录 ACL、可用空间和现有总量；空间不足时拒绝采集并保持服务原策略，而不是写到一半才清理旧现场。

容量预算至少考虑“单份最坏大小 × 单次最大份数 × 同时诊断实例数”，再加上传输副本、解析临时空间和安全余量。报告通常小于 heap snapshot，但 worker 树、共享库与 handle 数量会改变规模；heap snapshot 还可能显著暂停并接近堆规模。生产阈值来自目标进程基线、磁盘预算和暂停 SLO，不使用脱离负载的统一数字。

可观测指标应区分请求数、实际写出数、因容量或权限拒绝数、文件字节数、最老证据年龄、Inspector 活跃时长和清理失败数。验收看不变量：诊断窗口关闭后监听数回到零；连续受控采集后目录总量不单调增长；到期文件能被销毁且摘要索引同步移除；普通启动始终不等待调试器。

从症状回到 isolate、构建身份和控制通道

断点不命中时，先核对目标 PID、脚本 URL、生成物摘要和 source map，再判断代码是否已经执行。主线程命中而 worker 不命中，要比较 worker 的 threadId、execArgv、外部客户端 target 和任务关联；反复移动断点只会掩盖对象选错。

端口存在但客户端立即断开时，检查发现端点返回的 URL、CDP 消息与目标版本。TCP 探针成功不代表 Session 已启用 domain。重连后断点消失属于 Session 状态重建问题，不应误判成目标进程丢失代码。

栈指向错误源码时，先比较生成物与 map 摘要，检查部署是否混入旧 map，再看转换器是否支持该代码形态。恢复匹配 map 后，必须让同一合成异常重新指向实际语句；仅仅让文件名从 .js 变成 .ts 不算修复。

报告写不出时，按目录解析、进程用户、ACL、空间、并发命名和目标版本逐层检查。不要退回当前工作目录或 stdout 规避权限，因为那会扩大泄露面。若排除字段不存在，说明版本能力不满足模板，应升级受测发行线或在隔离采集后执行受控字段审查，而不是假设未知字段已被隐藏。

清理要覆盖进程、隧道、制品和代码入口

会话结束先恢复被暂停的目标，再让客户端断开并停止 SSH 转发。确认目标 PID 不再监听 Inspector；若目标仍需运行，应以无 Inspector 参数的正常入口重建实例。不要按端口盲杀进程，先用 PID 和启动命令证明 owner。

随后清理实验脚本、临时构建、旧 source map、report、heap snapshot、profile、Inspector 客户端日志和传输副本。删除前确认路径位于项目约定的临时根或受控证据目录；正式事故证据先完成交接与保留审批，不能套用本地实验删除命令。最后扫描部署模板、package.json、进程管理器和容器声明，确认没有 0.0.0.0、--inspect-brk、无限等待或长期端口发布残留。

团队把 Node.js 发行线、V8、编译器/bundler、Inspector 客户端和平台组成兼容矩阵。升级后重跑回环发现与 CDP 求值、主线程/worker 区分、正确/过期 source map、报告排除字段和清理复查五组不变量。工具 owner 维护模板与版本，服务 owner 决定暂停预算和目标实例，安全 owner 控制远程入口，数据 owner 决定诊断制品的读取与保留。

一次 Node.js 调试只有在能够证明目标 isolate 正确、源码与制品匹配、控制动作在预算内、敏感现场受控、端口与派生文件已经退出时才算闭环。Inspector 的价值不是让断点更方便，而是把运行状态、构建身份与安全退出变成可重复验证的工程能力。