第 4 章工具

用 Source Map、Chrome DevTools、VS Code、debug/repl2/power-assert 与热重载建立可控调试会话。

直觉起点

、、、、共同构成本页的诊断坐标。工具只放大证据，不替代实验设计。源码映射错位、断点副作用、调试端口暴露和热重载残留都可能制造新故障，因此会话本身也要被验收。调试不是“打开工具看看”，而是用可证伪假设组织实验：症状决定采集范围，固定样本保证比较有效，独立证据缩小根因，恢复回放证明修改没有把问题转移到别处。

六阶段诊断链

1. 保留源码映射

定义可观察症状与业务影响，冻结 Node 版本、依赖锁、入口参数、环境变量和负载数据。先写预测，再运行工具，避免从一张图反推所有可能原因。

2. 启动调试会话

标出 JavaScript 主线程、V8 堆、原生内存、文件、套接字、异步资源和外部依赖的所有者。每个资源同时登记正常结束、超时、错误与主动取消。

3. 配置断点

采集窗口必须包含预热、稳定与恢复阶段。CPU 样本、堆快照、日志、Span 和指标使用同一时间基准与请求标识，才能交叉验证。

4. 缩小状态空间

一次只改变一个故障变量，例如输入规模、缓存上限、正则模式、依赖延迟或采样配置。停止在首个状态分叉处，不用重试覆盖原始错误。

5. 验证热替换

把 2018 年历史工具与当前支持状态分开记录：保留原书要解决的问题，现代替代需要重新验证行为、开销、权限和数据格式。

6. 关闭监听资源

撤销故障并重放完全相同的样本。检查错误率、尾延迟、CPU、堆斜率、活动句柄、日志刷新与报警恢复，所有证据收敛后才签发。

核心机制深挖

工具只放大证据，不替代实验设计。源码映射错位、断点副作用、调试端口暴露和热重载残留都可能制造新故障，因此会话本身也要被验收。每次调查统一维护六类记录：业务症状、固定输入、运行时版本、资源所有者、首个偏离点、恢复条件。CPU 宽栈可能来自计算、垃圾回收或忙等待；RSS 增长可能来自 JavaScript 堆、Buffer、原生库或文件映射；日志缺失可能来自上下文传播、采样或管道背压。只有跨层证据一致，才能把相关性提升为根因。

本页签发不变量是：编译产物能映射回确定源码，断点不改变业务语义，热重载不会累积监听器或闭包，调试端口不会暴露给不可信网络。。最终输出或一张图只是证据之一。调查还要说明采样是否代表真实负载、时间线是否对齐、故障由谁观察、资源何时归还、进程怎样退出，以及修改后是否出现新的尾延迟、内存或遥测成本。

2018 版与现代 Node 的版本账本

原书出版于 2018 年，围绕 Node 8 时代的 v8-profiler、memwatch-next、旧调试入口、OpenTracing、Neon、New Relic、Elastic APM、Telegraf 与 AliNode 展开。重构保留这些正式目录和当时的问题边界，但不把停更包、私有 API 或旧协议直接推荐给新项目。现代对照包括内置 node:inspector、node:v8、诊断报告、AsyncLocalStorage、OpenTelemetry、当前 APM Agent 与持续剖析工具。

版本账本至少记录原书工具、当时用途、当前维护状态、替代入口、数据格式、权限、观测开销和迁移验收。稳定原理例如采样需要可比负载、泄漏来自错误保留、异步上下文需要传播、报警需要恢复条件不会因版本改变；命令参数、V8 优化规则、Agent 配置和服务端协议则必须按当前版本重新验证。

公开目录逐项讲解

第4章工具

第4章工具要放回“保留源码映射、启动调试会话、配置断点、缩小状态空间、验证热替换、关闭监听资源”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

实验从“保留源码映射”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.1 Source Map

Source Map 将生成代码位置映射回源码。发布时需保持产物与映射同版本、控制源码泄露，并在错误平台验证列号和内联映射；错配映射会把调查引向不存在的代码。

实验从“启动调试会话”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.1.1 uglify-es

实验从“配置断点”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.1.2 TypeScript

实验从“缩小状态空间”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.1.3 source-map-support的高级用法

实验从“验证热替换”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.2 Chrome DevTools

堆快照记录对象、引用边与支配关系；对比快照应在完成垃圾回收并执行同一负载后进行。增长对象只是入口，真正根因通常位于把它保留下来的监听器、缓存、闭包或全局集合。

实验从“关闭监听资源”开始：固定 Node 版本、入口、负载、采样窗口和环境变量，先预测正常轨迹；每次只改变一个条件，在首个偏离点保存时间、调用栈、对象保留链、日志关联标识或指标。删除故障后用同一输入重放，只有业务症状消失且资源回落才算恢复。

4.2.1 使用Chrome DevTools

4.2.2 NIM

调试器通过 Inspector 协议暂停、求值和采样。暂停会改变时序，远程调试端口拥有高权限；旧工具与私有 API 只保留历史定位，现代入口使用受保护的 --inspect 或 node:inspector。

4.2.3 inspect-process

4.2.4 process._debugProcess

4.3 Visual Studio Code

编辑器配置应固定入口、工作目录、环境和源码映射。条件断点可减少噪声但表达式可能有副作用；自动重启会改变进程身份，调查日志必须保留每次启动边界。

4.3.1 基本调试

4.3.1 基本调试要放回“保留源码映射、启动调试会话、配置断点、缩小状态空间、验证热替换、关闭监听资源”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

4.3.2 launch.json

4.3.3 技巧1：条件断点

4.3.4 技巧2：skipFiles

4.3.5 技巧3：自动重启

4.3.6 技巧4：对特定操作系统的设置

4.3.7 技巧5：多配置

4.3.8 总结

4.3.8 总结要放回“保留源码映射、启动调试会话、配置断点、缩小状态空间、验证热替换、关闭监听资源”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

4.4 debug repl2 power-assert

命名空间日志、交互式求值与富断言分别回答路径是否经过、状态是什么、期望差异在哪里。三类证据需要关联到同一用例，且不能在生产环境开放不受控求值。

4.4.1 debug

4.4.2 repl2

4.4.3 power-assert

4.5 supervisor-hot-reload

热重载通过替换可访问实现减少重启，但旧闭包、定时器和监听器可能继续存活。每次替换都要登记资源、撤销旧订阅，并用堆快照和监听器计数证明没有累积。

4.5.1 Proxy

4.5.2 用Proxy实现Hot Reload

4.5.3 supervisor-hot-reload

4.5.4 内存泄漏问题

4.5.4 内存泄漏问题要放回“保留源码映射、启动调试会话、配置断点、缩小状态空间、验证热替换、关闭监听资源”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

证据矩阵

证据层	正常样本	边界或失败	必查字段	恢复条件
业务	请求成功、延迟稳定	超时、错误、吞吐下降	路由、版本、请求标识	错误率与尾延迟回归
CPU 与循环	样本分布稳定	热点增宽、循环滞后	栈、样本数、窗口、负载	热点差异可解释
内存与资源	堆与句柄回落	保留链增长、句柄悬挂	对象、所有者、RSS、close	同负载后回到基线
日志与链路	因果可关联	缺段、重复、采样丢失	traceId、时间、错误 cause	时间线完整且单次完成
指标与报警	单位窗口明确	高基数、缺数、报警风暴	标签、聚合、阈值、责任人	触发与恢复均可演练

最小可运行实验

// launch.json 的关键思想：固定入口、源码映射和环境，而非复制临时参数。
{
  "type": "node",
  "request": "launch",
  "name": "fixed-reproduction",
  "program": "${workspaceFolder}/dist/server.js",
  "sourceMaps": true,
  "skipFiles": ["<node_internals>/**"],
  "env": { "REPRO_CASE": "timeout-17" }
}

book: Node.js 调试指南
edition: 2018-05
page: ndbg-04-tools
sample: normal | boundary | failure | recovery
fixed_input: true
evidence_clock_aligned: true
resource_owner_known: true
recovery_observed: true

state symptom and expected healthy baseline
freeze version + entry + load + sampling window
predict CPU + heap + handles + logs + metrics
change exactly one diagnostic condition
stop at the first divergent state
remove fault, replay, and wait for recovery

常见误区与故障注入

四类样本与验收

样本	注入方式	必查证据	通过条件
正常	固定小负载、依赖健康	基线、样本数、资源计数	结果可重放
边界	高并发、大对象、慢依赖	队列、背压、尾延迟、堆斜率	上限可解释
失败	异常、阻塞、泄漏、遥测断路	首个偏离点与所有者	错误不丢不重复
恢复	删除故障后同样本回放	CPU、堆、句柄、日志、报警	全部回到预算

目录证据：第4章工具、4.1 Source Map、4.1.1 uglify-es、4.1.2 TypeScript、4.1.3 source-map-support的高级用法、4.2 Chrome DevTools、4.2.1 使用Chrome DevTools、4.2.2 NIM、4.2.3 inspect-process、4.2.4 process._debugProcess、4.3 Visual Studio Code、4.3.1 基本调试、4.3.2 launch.json、4.3.3 技巧1：条件断点、4.3.4 技巧2：skipFiles、4.3.5 技巧3：自动重启、4.3.6 技巧4：对特定操作系统的设置、4.3.7 技巧5：多配置、4.3.8 总结、4.4 debug repl2 power-assert、4.4.1 debug、4.4.2 repl2、4.4.3 power-assert、4.5 supervisor-hot-reload、4.5.1 Proxy、4.5.2 用Proxy实现Hot Reload、4.5.3 supervisor-hot-reload、4.5.4 内存泄漏问题。本页按完整公开目录独立教学重构，不复制原书正文；28 个条目全部进入症状、机制、证据、版本与恢复链。

练习

小结

Source Map：对应“保留源码映射”的核心观察量。
条件断点：对应“启动调试会话”的核心观察量。
skipFiles：对应“配置断点”的核心观察量。
断言差异：对应“缩小状态空间”的核心观察量。
热重载：对应“验证热替换”的核心观察量。
28 个本页公开目录条目已全部映射到诊断链与版本账本。
先预测再采集；工具输出只是证据，业务恢复与资源回落共同决定是否通过。