Node.js 架构图解析：事件循环、线程池与 N-API

By Leeting Yan

理解 Node.js 的底层，必须从其运行时结构开始：事件循环、线程池、V8、libuv、模块系统与 N-API 扩展层。

下面的架构图展示了 Node.js 的完整结构，包括 JS 层到 C++ 层，再到操作系统的路径。

1. Node.js Runtime 总体架构图

┌───────────────────────────────────────────────┐
│                   JavaScript                  │
│  (用户代码、模块、async/await、Promise、FS API) │
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│            Node.js Built-in Modules           │
│ (fs, http, net, timers, crypto, stream, etc.) │
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│          Node Bindings (C/C++ Bridge)         │
│   将 JS API 映射到系统调用和 libuv 函数调用        │
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────┬──────────────────┐
│           V8              │      libuv       │
│  (解析、编译、执行 JS)     │ (事件循环, I/O, 线程池) │
└───────────────────────────┴──────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│                Operating System                │
│      (TCP, File System, DNS, Threads, …)       │
└───────────────────────────────────────────────┘

架构可分为三层：

  • 语言执行层（V8）
  • 异步 I/O 层（libuv）
  • 扩展层（N-API / C++ Addons）

Node.js = (V8) + (libuv) + (C++ glue code)。

2. 事件循环（Event Loop）架构与阶段图

libuv 事件循环是 Node.js 并发能力的核心。

下图展示了事件循环的阶段顺序：

┌─────────────────────────────────────────────┐
│                timers                       │
│     执行 setTimeout / setInterval 回调        │
└─────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│            pending callbacks                │
│     执行上轮未处理的回调（某些系统级）          │
└─────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│               idle / prepare                │
└─────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│                   poll                      │
│  ★ 核心阶段：等待 I/O、处理 I/O 回调           │
│  若无待处理 I/O，可进入阻塞等待                │
└─────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│                   check                     │
│     执行 setImmediate 回调                   │
└─────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│               close callbacks               │
│        例如 socket.on('close') 回调           │
└─────────────────────────────────────────────┘

关键说明

poll 阶段是 Node.js 的“心脏”

  • 处理大多数 I/O 回调
  • 监听新连接
  • 决定是否阻塞等待（高效）

setImmediate 与 setTimeout 的执行顺序取决于阶段差异

这是许多初学者的常见困惑。

Promise 回调属于 microtask，运行于阶段之间

与事件循环阶段 无关，而是：

每个阶段结束 → 清空微任务队列 → 进入下一个阶段

3. libuv 线程池架构图

尽管 Node.js 是“单线程执行 JS”，但 libuv 后面隐藏着一个线程池。

默认线程数：4（可通过 UV_THREADPOOL_SIZE 调整至 1~128）

线程池示意图：

         JS 主线程


┌──────────────────────────────────────────────┐
│ 执行 JS 逻辑、调度事件循环、处理微任务 queue   │
└──────────────────────────────────────────────┘
│
异步调用（文件 I/O、DNS、crypto 等）
▼
┌──────────────────────────────────────────────┐
│                libuv Thread Pool             │
├─────────────────────┬────────────────────────┤
│  Worker 1           │  Worker 2              │
│  文件读写任务        │  压缩/加密任务          │
├─────────────────────┼────────────────────────┤
│  Worker 3           │  Worker 4              │
│  DNS 查询           │  其他 CPU-heavy 任务     │
└─────────────────────┴────────────────────────┘

哪些任务进入线程池？

功能 是否进入线程池 原因
文件读写 (fs) ✔ OS 文件系统本身是阻塞的
DNS.resolve ✔ 非网络请求
crypto.pbkdf2 ✔ 重 CPU 运算
网络请求 (HTTP/TCP) ✘（交由内核事件驱动） 不需要线程池

线程池专门处理“阻塞但可异步化”的任务。

4. N-API（Node Addon API）调用链架构图

N-API 是 Node 提供的 稳定 C/C++ 扩展接口，用于：

  • 性能关键模块
  • 绑定系统库
  • AI、压缩、音视频编解码等重计算模块
  • 跨语言桥接（如 Rust / Zig / C++ 与 Node 联动）

下面是从 JS 调用到 C/C++ 执行的链路：

JS 调用层
┌──────────────────────────────────────┐
│ const addon = require('mypkg')       │
│ addon.runTask(data)                  │
└──────────────────────────────────────┘
│
▼
绑定层（Node Bindings）
┌──────────────────────────────────────┐
│ 解析函数参数，封装成 napi_value       │
│ 调用注册的 C/C++ 方法                  │
└──────────────────────────────────────┘
│
▼
N-API 层（ABI 稳定）
┌──────────────────────────────────────┐
│ napi_call_function(...)              │
│ napi_create_buffer(...)              │
│ napi_get_value_string_utf8(...)      │
└──────────────────────────────────────┘
│
▼
C/C++ Addon 实现层
┌──────────────────────────────────────┐
│  void RunTask(...) {                  │
│      // 执行计算或调用系统功能         │
│  }                                    │
└──────────────────────────────────────┘
│
▼
（可选）libuv → 线程池
┌──────────────────────────────────────┐
│ 在后台线程执行耗时任务                │
│ 完成后将回调推回事件循环              │
└──────────────────────────────────────┘

为什么 N-API 很重要？

因为：

  • Node.js 版本升级不会破坏 ABI
  • Addons 不用每次重新编译
  • 可以封装高性能语言（Rust/Zig/C++）

现代许多性能模块（如 bcrypt、sharp、llama-node）都依赖 N-API。

5. Node.js 架构的互相协作方式（数据流总结）

下面给出一个 JS 调用到系统层的完整路径示例：

用户 JS 调用 → Node 内置 API → Node Bindings →
libuv 调用 → OS 异步接口 → 事件循环 →
回调重新进入 JS 主线程

而 C++ 扩展路径示例：

JS → N-API → C/C++ Addon → （可选）libuv → JS 回调

Node.js 通过这种“JS → C++ → libuv → OS”模型，将一个脚本语言变成了一个高性能服务器运行时。

6. 架构理解带来的工程启示

Node 适合：

  • 高并发 API 服务
  • WebSocket / 实时系统
  • 中间层（BFF）
  • 工具链（Vite / Webpack / ESLint）
  • 边缘场景（Cloudflare + Node API 对齐）

避免阻塞事件循环

  • 不要在主线程做大量 JSON 解析
  • 不要进行 CPU-heavy 加密
  • 不要循环 10M 次数字计算

改用：

  • Worker Threads
  • N-API + C++/Rust
  • 微服务拆分

理解事件循环阶段是写出高质量 Node 程序的关键

它直接影响：

  • Promise 顺序
  • setTimeout vs setImmediate
  • I/O 回调时序
  • Stream backpressure 行为

结语

Node.js 的“快”不是因为 JavaScript 本身，而是因为其 运行时架构：

  • V8 的高速执行
  • libuv 的事件驱动模型
  • 线程池的隐藏并行能力
  • N-API 的扩展能力
  • JS 主线程只负责轻量逻辑的设计

理解这些底层机制，会让你写出更稳定、更高性能、更可预期的 Node.js 程序。