1 / 4概念
Ecosystem: Standard Library
Node 的核心模块就是运行时能力的全部入口:文件、网络、进程、线程、二进制与加密。判断标准不是记住多少 API,而是能否说清一次读写用同步、回调还是流,以及背压在哪里生效。
1 概念
1.1 一句话定义
Node 用一组内建模块把操作系统能力暴露给 JavaScript。同一个能力常有三种风格:同步、回调、Promise;数据量不确定时用流,确定时用缓冲。
1.2 它解决什么问题
- 访问系统资源:文件、网络、进程、信号,无需原生扩展。
- 流式处理:大文件与长连接不把内容全部读进内存。
- 并发利用:工作线程处理 CPU 任务,集群利用多核。
- 统一错误约定:
errno字符串代码贯穿所有系统调用。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 事件循环阶段、libuv 线程池 | Runtime Environment |
tsc、打包、包管理器 | Toolchain |
| 框架的路由与依赖注入 | Backend Frameworks |
浏览器的 fetch 与 DOM API | Browser Environment |
| 部署与进程管理 | 仓库运维章节 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 核心模块 | 随 Node 发布的内建模块 | 与 npm 包不同 |
node: 前缀 | 显式标记核心模块 | 与同名用户包区分 |
Buffer | 定长二进制缓冲 | 是 Uint8Array 的子类 |
| 流 | 分块传输数据的抽象 | 不等于文件 |
| 背压 | 消费方通知生产方降速 | 靠 highWaterMark 生效 |
EventEmitter | 事件发布订阅基类 | 同步调用监听器 |
errno 代码 | 系统错误字符串码 | 与 errno 数值不同 |
| 工作线程 | 独立事件循环的线程 | 不是进程 |
| 句柄 | 打开的文件或套接字 | 必须显式关闭 |
2 机制
2.1 心智模型
把核心模块分成四组:数据(fs、stream、buffer、zlib)、通信(net、http、dgram、dns)、进程(process、child_process、worker_threads、cluster)、支撑(path、url、util、events、crypto、os、timers)。先选组,再选风格。
2.2 机制拆解
- 三种风格:同步阻塞当前线程;回调遵循
err优先;Promise 版在fs/promises等子路径。 Buffer:定长、字节序敏感;Buffer.alloc会清零,allocUnsafe不清零,可能泄露上一段内存。- 流与背压:写入超过
highWaterMark时write返回false,生产方应暂停直到drain。 - HTTP:
http.createServer每个请求两个流(请求体与响应),不消费请求体会占住连接。 - 工作线程:各自独立的事件循环,消息按结构化克隆传递,可用
transferList转移ArrayBuffer。 - 子进程:
spawn不经过 shell,exec经过 shell 因此有注入风险,fork专用于 Node 脚本并提供 IPC。 - 集群:主进程监听端口,把连接分给多个工作进程;调度策略默认轮询。
errno约定:错误对象带code,例如ENOENT、EACCES、EMFILE;判断用code,不用消息文本。
2.3 完整枚举
核心模块,这是常用集合:
| 模块 | 用途 |
|---|---|
fs | 文件与目录 |
path | 路径拼接与解析 |
process | 当前进程信息与控制 |
buffer | 二进制缓冲 |
stream | 流式读写 |
net | TCP 套接字与服务器 |
http / https | HTTP 客户端与服务器 |
http2 | HTTP/2 |
dgram | UDP |
dns | 域名解析 |
worker_threads | 工作线程 |
cluster | 多进程共享端口 |
child_process | 启动子进程 |
events | 事件发射器 |
crypto | 哈希、加密、随机数 |
zlib | 压缩与解压 |
util | 类型判断、promisify、格式化 |
url | URL 解析与编码 |
os | 系统信息与 CPU 数 |
timers | 定时器与 setImmediate |
perf_hooks | 性能计时 |
diagnostics_channel | 进程内诊断通道 |
vm | 沙箱执行 |
fs 的三种风格:
| 风格 | 写法 | 场景 |
|---|---|---|
| 同步 | readFileSync | 启动配置、脚本 |
| 回调 | readFile(path, cb) | 旧代码 |
| Promise | fs/promises 的 readFile | 新代码 |
四种流:
| 类型 | 方向 | 典型来源 |
|---|---|---|
Readable | 只读 | 文件读、请求体 |
Writable | 只写 | 文件写、响应体 |
Duplex | 双向 | 套接字 |
Transform | 双向且转换 | 压缩、加解密 |
子进程的四种启动方式:
| 方法 | 经过 shell | 输入输出 | 适用 |
|---|---|---|---|
spawn | 否 | 流 | 长时间运行、输出大 |
exec | 是 | 缓冲字符串 | 短命令、脚本 |
execFile | 否 | 缓冲 | 可执行文件 |
fork | 否 | IPC | 启动另一个 Node 脚本 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 流默认水位 | 16 KiB | 对象模式为 16 个对象 |
| HTTP 头部上限 | 16 KiB | 超过返回 431 |
Buffer 上限 | 约 4 GB | 由 buffer.constants.MAX_LENGTH 决定 |
| 文件描述符 | 受 ulimit -n 限制 | 默认常见 1024 或 65535 |
| 工作线程启动 | 数十毫秒 | 小任务不值得 |
EMFILE | 打开句柄过多 | 必须显式关闭 |
3 实践
3.1 最小示例
用流处理一个大文件:读、转换、写,全程不把文件读进内存。pipeline 负责错误传播与关闭。
import {createReadStream, createWriteStream} from 'node:fs';
import {createGzip} from 'node:zlib';
import {pipeline} from 'node:stream/promises';
await pipeline(
createReadStream('access.log'),
createGzip({level: 6}),
createWriteStream('access.log.gz'),
);
追踪数据流:读流按块产出 Buffer,压缩流把每块压小交给写流;写流处理不过来时 write 返回 false,pipeline 会暂停读流,等 drain 再继续。任一环节出错,pipeline 销毁全部流并让 await 抛出,不会留下半开句柄。
对照写法:await fs.readFile('access.log') 会把整个文件读进内存,文件大到一定程度就 ENOMEM。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 读文本 | fs.readFile(path, 'utf8') | 依赖编码参数 |
| 判断存在 | fs.access 或 stat | 用 err.code 判断 |
| 递归创建 | fs.mkdir(dir, {recursive: true}) | 已存在不报错 |
| 遍历目录 | fs.readdir(dir, {withFileTypes: true}) | 拿 Dirent 判断类型 |
| 拼路径 | path.join(a, b) | 不用字符串拼接 |
| 解析路径 | path.parse(p) | 拿扩展名与目录 |
| 读环境变量 | process.env.KEY | 总是字符串或 undefined |
| 退出码 | process.exitCode = 1 | 比 exit 温和 |
| 压缩 | zlib.gzipSync(buffer) | 大文件用流 |
| 哈希 | crypto.createHash('sha256') | 流式更新 |
3.3 标准流程
- 先确定数据量级:确定大小用缓冲,不确定用流。
- 再确定阻塞代价:启动路径可用同步 API,请求路径一律异步。
- 每个打开的句柄都要在
finally里关闭,或用流自动管理。 - 流处理用
pipeline,不要手写pipe加错误监听。 - 系统错误按
code分支处理,未知错误原样上报。 - 用性能钩子测关键路径,不要凭感觉优化。
3.4 与相邻技术的组合
- 运行时:核心模块的异步操作最终落在 libuv 线程池;线程池默认四个。
- TypeScript:
@types/node提供声明;ESM 下用node:前缀。 - 框架:NestJS 等框架封装了
http与流,但底层约定不变。 - 工具链:打包器会替换部分核心模块,服务端构建要标记为外部依赖。
- 操作系统:文件描述符与信号是宿主资源,容器里要相应调高。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| I/O 风格 | 同步 / 回调 / Promise | 阻塞与可读性 |
| 数据形态 | 缓冲 / 流 | 内存占用与首字节时间 |
| 并发模型 | 单进程 / 工作线程 / 集群 | CPU 利用率与隔离 |
| 子进程 | spawn / exec / fork | shell 风险与 IPC |
| 错误处理 | code / 异常类型 | 可诊断性 |
3.6 决策规则
- 请求路径禁止同步文件 API,启动路径可以用。
- 超过几十兆的数据一律走流。
- 子进程优先
spawn或execFile,只在需要 shell 特性时用exec,并对参数做白名单。 - 每个
createServer都要处理clientError,否则畸形请求会挂住连接。 - 句柄泄漏用
process._getActiveHandles或诊断通道排查,不要靠猜。 - 生产环境设置
server.headersTimeout与requestTimeout,避免慢速攻击。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 同步 API | 简单、顺序清晰 | 阻塞事件循环 | 启动与脚本 |
| Promise API | 可组合 | 需要异步上下文 | 请求路径 |
| 流 | 内存恒定 | 复杂度高 | 大文件、长连接 |
| 工作线程 | 真并行 | 通信与启动成本 | CPU 密集 |
| 集群 | 利用多核 | 状态不共享 | 无状态服务 |
| 原生扩展 | 极致性能 | 构建与维护 | 特殊场景 |
3.8 何时不该用
- 不要在请求处理里用
readFileSync,一个慢磁盘就能拖垮全部并发。 - 不要用
exec拼接用户输入,命令注入是必然结果。 - 不要把工作线程当通用异步方案,小任务克隆成本高于计算。
- 不要手写流的错误与关闭逻辑,
pipeline已经覆盖。 - 不要依赖
process.exit清理资源,它会跳过finally。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
EMFILE 打开文件失败 | 句柄未关闭 | 用 finally 或流 |
| 进程内存持续上涨 | 用缓冲读大文件 | 改流式 |
| 请求一直不返回 | 请求体未被消费 | 读完或显式销毁 |
| 压缩后文件损坏 | 流未写完就退出 | await pipeline |
| 子进程命令注入 | exec 拼接输入 | 换 spawn 并校验参数 |
| 工作线程退出无输出 | 主线程未等待 | 监听 exit 与 message |
| 集群下会话丢失 | 状态在进程内存 | 外置会话存储 |
| 错误判断失效 | 比较 message 文本 | 比较 err.code |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 请求里同步 I/O | 阻塞事件循环 | 异步 API |
Buffer.allocUnsafe 后直接读 | 泄露旧内存 | alloc 或写满 |
用 pipe 不处理错误 | 泄漏句柄 | pipeline |
忽略 drain | 内存膨胀 | 按背压暂停 |
process.exit(0) 收尾 | 跳过清理 | 设 exitCode |
4.3 可观测信号
活动句柄数、事件循环延迟、文件描述符使用量、errno 分布、流的水位与暂停次数、工作线程往返耗时、线程池队列长度。
4.4 安全 / 性能 / 一致性边界
- 注入边界:
exec与 shell 拼接是命令注入入口;spawn传参数组不经过 shell。 - 内存边界:
allocUnsafe不擦除内存;流的水位决定驻留内存上限。 - 句柄边界:文件描述符是有限资源,容器里通常比宿主更低。
- 权限边界:Node 的权限模型还在演进,生产隔离要靠容器与系统用户。