第 3 章代码

沿 Promise、Async/Await、Error Stack、Node 8 优化、Rust Addons、Event Loop 与 uncaughtException 检查代码层根因。

直觉起点

、、、、共同构成本页的诊断坐标。代码调试把语言语义、运行时优化和异步调度连接起来：Promise 决议错误会伪装成时序问题，栈被截断会隐藏因果，原生扩展错误可能直接破坏进程。调试不是“打开工具看看”，而是用可证伪假设组织实验：症状决定采集范围，固定样本保证比较有效，独立证据缩小根因，恢复回放证明修改没有把问题转移到别处。

六阶段诊断链

1. 复现异常

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

2. 捕获完整栈

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

3. 展开异步链

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

4. 检查优化状态

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

5. 隔离原生边界

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

6. 验证循环退出

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

核心机制深挖

代码调试把语言语义、运行时优化和异步调度连接起来：Promise 决议错误会伪装成时序问题，栈被截断会隐藏因果，原生扩展错误可能直接破坏进程。每次调查统一维护六类记录：业务症状、固定输入、运行时版本、资源所有者、首个偏离点、恢复条件。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 配置和服务端协议则必须按当前版本重新验证。

公开目录逐项讲解

第3章代码

第3章代码要放回“复现异常、捕获完整栈、展开异步链、检查优化状态、隔离原生边界、验证循环退出”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

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

3.1 Promise

Promise 的核心契约是状态只能从 pending 迁移一次，thenable 解析要防重复回调和自解析。调试时记录决议源、拒绝处理者与微任务顺序，不能只在链尾添加 catch 掩盖首次错误。

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

3.1.1 Promise/A规范

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

3.1.2 从零开始实现Promise

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

3.1.3 Promise的实现原理

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

3.1.4 safelyResolveThen

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

3.1.5 doResolve和doReject

3.1.6 Promise.prototype.then和Promise.prototype.catch

3.1.7 值穿透

3.1.8 Promise.resolve和Promise.reject

3.1.9 Promise.all

3.1.10 Promise.race

3.1.11 代码解析

3.1.11 代码解析要放回“复现异常、捕获完整栈、展开异步链、检查优化状态、隔离原生边界、验证循环退出”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

3.2 Async Await

生成器与 co 是 async/await 普及前的重要控制流桥梁。迁移时要保留并发关系、错误传播与取消语义；把 yield 机械替换为 await 可能把并行任务串行化，或丢失 yield* 的委托行为。

3.2.1 例1：async await

3.2.2 例2：co yield

3.2.3 例3：co yield*

3.2.4 例4：co bluebird

3.2.5 从yield转为yield*遇到的坑

3.2.6 async bluebird

3.3 Error Stack

错误栈由捕获位置、调用帧和格式化策略组成。扩大栈深度会增加成本，prepareStackTrace 是全局钩子；生产代码应优先使用 Error cause 和结构化字段保留因果，而非依赖脆弱字符串解析。

3.3.1 Stack Trace

3.3.2 Error.captureStackTrace

3.3.3 captureStackTrace在Mongolass中的应用

3.3.4 Error.prepareStackTrace

3.3.5 Error.prepareStackTrace的其他用法

3.3.6 Error.stackTraceLimit

3.3.7 Long Stack Trace

3.4 node@8

Node 8 所处的 V8 优化规则具有历史背景。稳定结论是先测量热点与对象形状，易变结论是某个语法必然去优化；现代运行时必须重新采样，不能沿用旧版本优化清单。

3.4.1 Ignition TurboFan

3.4.2 版本的对应关系

3.4.3 try/catch

3.4.4 delete

3.4.5 arguments

3.4.6 async性能提升

3.4.7 不会优化的特性

3.5 Rust Addons

原生扩展跨越 JavaScript、V8 与系统内存边界。FFI 需要严格声明 ABI 和生命周期；N-API 提供更稳定的版本边界，但仍要验证线程、异常、Buffer 所有权和进程崩溃路径。

3.5.1 Rust

3.5.2 FFI

3.5.3 Neon

3.5.4 NAPI

3.6 Event Loop

事件循环阶段决定定时器、I/O 回调、immediate 与关闭回调的机会；nextTick 队列会在阶段切换前排空。递归调度 nextTick 可能饿死 I/O，因此要同时观察延迟、活动句柄与队列增长。

3.6.1 什么是Event Loop

3.6.2 poll阶段

3.6.3 process.nextTick()

3.6.4 代码解析

3.6.4 代码解析要放回“复现异常、捕获完整栈、展开异步链、检查优化状态、隔离原生边界、验证循环退出”的完整诊断链。先写出症状、输入、资源和期望结束状态，再采集能证伪假设的最小证据。

3.7 处理uncaughtException

未捕获异常说明进程状态可能已经破坏，处理器适合记录并启动受控退出，不适合继续长期服务。ReDoS 则会阻塞主线程，应通过输入上限、线性正则或超时隔离，而不是依赖异常处理。

3.7.1 uncaughtException

3.7.2 使用llnode

Core Dump 保存进程地址空间与寄存器状态，gcore 可主动生成转储，llnode 借助调试符号检查 V8 堆和 JavaScript 栈。转储可能包含密钥与用户数据，采集、传输和销毁都需受控。

3.7.3 ReDoS

证据矩阵

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

最小可运行实验

import { AsyncLocalStorage } from "node:async_hooks";
 
const context = new AsyncLocalStorage();
 
export async function withTrace(traceId, operation) {
  return context.run({ traceId }, async () => {
    try {
      return await operation();
    } catch (cause) {
      throw new Error("operation failed", { cause });
    }
  });
}

book: Node.js 调试指南
edition: 2018-05
page: ndbg-03-code
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、堆、句柄、日志、报警	全部回到预算

目录证据：第3章代码、3.1 Promise、3.1.1 Promise/A规范、3.1.2 从零开始实现Promise、3.1.3 Promise的实现原理、3.1.4 safelyResolveThen、3.1.5 doResolve和doReject、3.1.6 Promise.prototype.then和Promise.prototype.catch、3.1.7 值穿透、3.1.8 Promise.resolve和Promise.reject、3.1.9 Promise.all、3.1.10 Promise.race、3.1.11 代码解析、3.2 Async Await、3.2.1 例1：async await、3.2.2 例2：co yield、3.2.3 例3：co yield*、3.2.4 例4：co bluebird、3.2.5 从yield转为yield*遇到的坑、3.2.6 async bluebird、3.3 Error Stack、3.3.1 Stack Trace、3.3.2 Error.captureStackTrace、3.3.3 captureStackTrace在Mongolass中的应用、3.3.4 Error.prepareStackTrace、3.3.5 Error.prepareStackTrace的其他用法、3.3.6 Error.stackTraceLimit、3.3.7 Long Stack Trace、3.4 node@8、3.4.1 Ignition TurboFan、3.4.2 版本的对应关系、3.4.3 try/catch、3.4.4 delete、3.4.5 arguments、3.4.6 async性能提升、3.4.7 不会优化的特性、3.5 Rust Addons、3.5.1 Rust、3.5.2 FFI、3.5.3 Neon、3.5.4 NAPI、3.6 Event Loop、3.6.1 什么是Event Loop、3.6.2 poll阶段、3.6.3 process.nextTick()、3.6.4 代码解析、3.7 处理uncaughtException、3.7.1 uncaughtException、3.7.2 使用llnode、3.7.3 ReDoS。本页按完整公开目录独立教学重构，不复制原书正文；50 个条目全部进入症状、机制、证据、版本与恢复链。

练习

小结

Promise 决议：对应“复现异常”的核心观察量。
异步栈：对应“捕获完整栈”的核心观察量。
TurboFan：对应“展开异步链”的核心观察量。
N-API：对应“检查优化状态”的核心观察量。
事件循环：对应“隔离原生边界”的核心观察量。
50 个本页公开目录条目已全部映射到诊断链与版本账本。
先预测再采集；工具输出只是证据，业务恢复与资源回落共同决定是否通过。