稍候片刻,月出文自明。
import { monitorEventLoopDelay } from 'node:perf_hooks';
const h = monitorEventLoopDelay({ resolution: 20 }); // 每 20ms 采样一次
h.enable();
const timer = setInterval(() => {
console.log({
mean: (h.mean / 1e6).toFixed(2), // 单位是纳秒,要除以 1e6
max: (h.max / 1e6).toFixed(2),
p99: (h.percentile(99) / 1e6).toFixed(2),
});
h.reset();
}, 5000);
timer.unref(); // 只是观测,不该阻止进程退出// worker.js
import { parentPort, workerData } from 'node:worker_threads';
function fib(n) { return n < 2 ? n : fib(n - 1) + fib(n - 2); }
parentPort.postMessage({ n: workerData.n, value: fib(workerData.n) });// main.js
import { Worker } from 'node:worker_threads';
const worker = new Worker(new URL('./worker.js', import.meta.url), {
workerData: { n: 38 },
});
worker.once('message', ({ value }) => console.log(value)); // 39088169,主线程全程可响应
worker.once('error', (err) => console.error('worker 挂了', err)); // 必须监听,否则是未捕获异常
worker.once('exit', (code) => console.log('exit', code));const buf = new ArrayBuffer(64 * 1024 * 1024);
worker.postMessage({ buf }, [buf]); // transferList:所有权搬家,不复制
console.log(buf.byteLength); // 0——原线程里这块内存已经 detachconst sab = new SharedArrayBuffer(4);
const view = new Int32Array(sab);
worker.postMessage({ sab }); // 共享内存不进 transferList
Atomics.store(view, 0, 1); // 写入,对所有持有者可见
Atomics.notify(view, 0); // 唤醒在 wait 上阻塞的线程
// worker 侧:Atomics.wait(view, 0, 0) —— 值仍是 0 就一直等// cluster.js —— 一个端口,多个进程
import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';
import { createServer } from 'node:http';
if (cluster.isPrimary) {
for (let i = 0; i < availableParallelism(); i++) cluster.fork();
cluster.on('exit', (worker, code) => {
console.error(`worker ${worker.process.pid} 退出,code=${code}`);
cluster.fork(); // 简单自愈;生产里要加退避,避免崩溃循环
});
} else {
createServer((req, res) => res.end(`pid ${process.pid}`)).listen(3000);
}function reload() {
const oldWorkers = Object.values(cluster.workers);
let done = 0;
for (const old of oldWorkers) {
const next = cluster.fork();
next.once('listening', () => {
old.disconnect(); // 不再接新连接,等在途请求自然结束
old.process.once('exit', () => {
if (++done === oldWorkers.length) console.log('reload done');
});
});
}
}import { createReadStream, createWriteStream } from 'node:fs';
const rs = createReadStream('big.log', { highWaterMark: 1024 * 1024 }); // 1 MB
const ws = createWriteStream('copy.log');
rs.on('data', (chunk) => {
if (!ws.write(chunk)) { // false:写缓冲满了
rs.pause(); // 停止读,否则内存一路涨
ws.once('drain', () => rs.resume());
}
});
rs.on('end', () => ws.end());import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';
import { createReadStream, createWriteStream } from 'node:fs';
await pipeline(
createReadStream('app.log'),
createGzip(),
createWriteStream('app.log.gz')
);
// 任意一环出错都会 reject,并自动销毁沿途的流;只写 .pipe() 时错误不会往下传import { Transform } from 'node:stream';
class UpperLine extends Transform {
constructor() {
super({ objectMode: false });
this.rest = '';
}
_transform(chunk, enc, cb) {
const text = this.rest + chunk.toString('utf8');
const lines = text.split('\n');
this.rest = lines.pop(); // 最后一段可能不完整,留到下次
for (const line of lines) this.push(line.toUpperCase() + '\n');
cb();
}
_flush(cb) { // 流结束时收尾
if (this.rest) this.push(this.rest.toUpperCase());
cb();
}
}import v8 from 'node:v8';
const { heap_size_limit, used_heap_size } = v8.getHeapStatistics();
console.log((heap_size_limit / 1024 ** 3).toFixed(2) + ' GB 上限');
console.log((used_heap_size / 1024 ** 2).toFixed(1) + ' MB 在用');
const m = process.memoryUsage(); // 单位都是字节
console.log(Object.fromEntries(
Object.entries(m).map(([k, v]) => [k, (v / 1024 ** 2).toFixed(1) + 'MB'])
));import { performance, PerformanceObserver } from 'node:perf_hooks';
const obs = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
console.log(entry.name, entry.duration.toFixed(2) + 'ms');
}
});
obs.observe({ entryTypes: ['measure'] });
performance.mark('db-start');
await db.query('select 1');
performance.mark('db-end');
performance.measure('db', 'db-start', 'db-end'); // 输出 db 1.23msimport { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
const als = new AsyncLocalStorage();
export const withRequestContext = (ctx, fn) => als.run(ctx, fn);
export const log = (msg) => {
const ctx = als.getStore();
console.log(`[${ctx?.traceId ?? '-'}] ${msg}`);
};
server.on('request', (req, res) => {
const traceId = req.headers['x-trace-id'] ?? randomUUID();
withRequestContext({ traceId }, () => {
log('收到请求'); // 这条链上的所有日志都带同一个 traceId
handle(req, res);
});
});(function (exports, require, module, __filename, __dirname) {
// 你的代码
});{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"default": "./dist/index.js"
}
}
}// a.cjs
exports.loaded = false;
const b = require('./b.cjs'); // b 内部 require('./a.cjs') 拿到的是 { loaded: false }
exports.loaded = true;
// b.cjs
const a = require('./a.cjs');
console.log(a.loaded); // false —— 因为 a 还没执行到最后一行// a.mjs
import { b } from './b.mjs';
export const a = 'a';
console.log(b); // 若 b.mjs 先求值且此时访问 a,会抛 ReferenceError
// b.mjs
import { a } from './a.mjs';
export const b = a + 'b'; // Cannot access 'a' before initializationimport { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const pkg = require('./package.json'); // 只有 CJS 加载器能直接读 JSONimport { createServer } from 'node:http';
const server = createServer((req, res) => {
if (!res.write(head)) {
res.once('drain', () => res.end(body)); // 客户端读得慢,等缓冲排空再写
} else {
res.end(body);
}
});
server.headersTimeout = 10_000; // 慢速攻击:别让半个请求头挂 60 秒
server.requestTimeout = 30_000;
server.keepAliveTimeout = 5_000; // 要比上游负载均衡的空闲超时略大
server.listen(3000);const MAX = 1024 * 1024; // 1 MB
server.on('request', (req, res) => {
let size = 0;
const chunks = [];
req.on('data', (chunk) => {
size += chunk.length;
if (size > MAX) {
req.destroy(); // 直接断,别再读了
res.writeHead(413).end('too large');
return;
}
chunks.push(chunk);
});
req.on('end', () => { /* Buffer.concat(chunks) 再解析 */ });
});import { readFile } from 'node:fs/promises';
import { setTimeout as sleep } from 'node:timers/promises';
const ac = new AbortController();
// 20.3 起有 AbortSignal.any:手动取消 + 超时,任一触发就中断
const signal = AbortSignal.any([ac.signal, AbortSignal.timeout(3000)]);
try {
const text = await readFile('./a.txt', 'utf8', { signal });
await sleep(1000, undefined, { signal, ref: false }); // ref: false 不阻止进程退出
console.log(text.length);
} catch (err) {
console.log(err.name); // 超时是 TimeoutError;手动 abort 是 AbortError(或自定义 reason)
}let closing = false;
for (const sig of ['SIGTERM', 'SIGINT']) {
process.on(sig, () => {
if (closing) return;
closing = true;
server.close(() => process.exit(0)); // 等在途请求自然结束
server.closeIdleConnections(); // 18.2 起:空闲的 keep-alive 连接直接关
// server.closeAllConnections(); // 更激进:不等在途请求
setTimeout(() => process.exit(1), 10_000).unref(); // 兜底,超时硬退
});
}process.on('uncaughtException', (err) => {
console.error('fatal', err);
process.exitCode = 1; // 比 process.exit() 安全:让 stdout 有机会写完
server.close(() => process.exit(1));
});
process.on('unhandledRejection', (reason) => {
console.error('unhandled rejection', reason);
process.exitCode = 1;
});
Node.js 进阶知识点整理:多核、内存、流与生产可靠性
基础篇把运行时、模块、事件循环、进程和工程化按六条线归过档。这一篇不重复那些结论,只往五个方向再深一层:怎么把 CPU 密集任务挪出主线程、流和背压到底怎么工作、内存与 GC 在哪一层出问题、线上出故障时怎么取证据、以及把服务写稳的那些边界。
适合读者:能独立写 Node 服务,遇到「CPU 打满但 QPS 不高」「内存缓慢上涨」「优雅退出不生效」「本地能跑上线就挂」这类问题时想弄明白原因的人。示例都能用 node 直接跑,输出写在注释里;涉及版本差异和实验性功能的地方我都标了出来——Node 迭代很快,具体行为以当前版本的官方文档为准。
01|先定位瓶颈:三种资源,三条路
优化的第一步不是改代码,而是判断瓶颈在哪一层。Node 服务只有三种资源会被打满:CPU(主线程或 libuv 线程池)、内存(堆内或堆外)、下游 I/O(数据库、别的服务)。三者的解法完全不同,认错了方向,越优化越糟。
最直接的观测指标是事件循环延迟。perf_hooks 里的 monitorEventLoopDelay 采样的是「定时器到期到真正执行」的差值,健康服务通常在个位数毫秒,超过几十毫秒就说明主线程被占住了。
两个细节:h 里的数值是纳秒,别直接当毫秒打印;观测用的定时器要 unref(),否则它会成为优雅退出时「进程迟迟不退」的一个来源。
02|worker_threads:真正并行执行 JS 的唯一手段
每个 worker 是一个独立的 V8 isolate:有自己的堆、有自己的事件循环、有自己的全局环境。主线程与 worker 之间不共享普通对象——共享只有两条路:消息复制(structured clone),或者 SharedArrayBuffer。
路径用 new URL('./worker.js', import.meta.url) 最稳:直接写字符串是按当前工作目录解析的,容器里换一个启动目录就找不到文件,这是 worker 在线上「本地好好的」的典型原因。
大块二进制数据不要走复制,走转移:
转移之后原线程再访问这个 ArrayBuffer 就是空的(byteLength 变成 0),继续用会抛错。需要两边同时读写同一块内存时才用共享方案:
SharedArrayBuffer 不复制,但语言层面没有锁,读写必须配合 Atomics 才有意义。Atomics.wait 会真的阻塞所在线程,放在主线程等于卡死事件循环(浏览器主线程直接禁止这样用)。
03|cluster 与多进程:分摊连接,而不是分摊计算
worker_threads 解决「一个进程内并行算」,cluster 解决「多进程分摊连接」。cluster 的主进程负责 fork 子进程并分发连接,每个子进程都是完整的 Node 进程:独立内存、独立事件循环、独立端口句柄。
调度策略有两档:默认是主进程轮询分发(round-robin),Windows 上不支持,退化为由操作系统抢占;cluster.schedulingPolicy 可以切换。轮询分布更均匀,但也意味着同一个客户端的连续请求会落到不同进程——所以会话、限流计数这类状态不能放在进程内存里,要么做粘性会话,要么放外部存储。
零停机重启的做法是「先起新的,再断旧的」,全程保持有进程在监听:
选型可以用一句话判断:
容器时代 cluster 用得少了:进程隔离交给编排系统之后,多开副本比在进程内 fork 更干净、扩缩容也更直接。但本地起服务、或者没有编排的部署环境,cluster 仍然是最省事的多核方案。
04|流的内核:背压不是可选项
流解决的是「数据比内存大、且要边产出边消费」。它能成立靠的是一条约定:生产方必须尊重消费方的缓冲上限,也就是背压。
每个流有一个 highWaterMark:字节流默认 16 KB,objectMode 默认 16 个对象;fs.createReadStream 和 createWriteStream 单独默认 64 KB。它是「缓冲到多少就该停手」的水位线,不是硬上限——单次写入照样可能超过它。
上面是手写背压的最小版本,也是绝大多数流式内存泄漏的来源——只调用 ws.write(chunk) 而不看返回值,读多快就写多快,缓冲全堆在内存里。正确的做法是不要手写,pipeline 已经替你处理了背压、错误传播和流销毁:
三种消费方式要分清:
自定义中间层就写 Transform,_transform 里必须调用回调,否则流会停在原地不动:
objectMode 打开后,highWaterMark 的单位会从「字节」变成「个数」,chunk 也可以直接是任意对象——但这也意味着内存估算不能再按字节算。
05|内存:先分清堆内堆外
process.memoryUsage() 的几个字段经常被混着读,其实各自指向不同的东西:
所以「heapUsed 不高但 rss 一直涨」是正常现象:可能是 Buffer、可能是 native addon,也可能是 V8 还没把内存还给系统。V8 老生代在 64 位下的默认上限是 2 GB 量级(随版本和物理内存变化),真实值看 v8.getHeapStatistics().heap_size_limit,用 --max-old-space-size 调整——调到超过容器内存限制,结果就是被 OOMKilled,而不是多做几次 GC。
GC 是分代的:新生代用 Scavenge(复制存活对象,快而频繁),老生代用标记-清除/整理(慢,伴随增量标记与并发标记)。于是有三条结论:短命对象多不是问题,新生代回收很便宜;真正的麻烦是「本该短命的对象被长期引用」,它们会被晋升到老生代;频繁的 Full GC(配合 --trace-gc 能看到 Mark-Compact)通常意味着有人在疯狂分配大对象,或者堆已经贴近上限。
泄漏的常见形状比 API 用法更值得记:
定位方法:Node 12 起可以用 --heapsnapshot-signal=SIGUSR2,进程运行时发个信号就落一份堆快照(文件很大,别往生产磁盘上乱写);--heapsnapshot-near-heap-limit=3 会在接近上限时自动拍。拿两份不同时间的快照,在 Chrome DevTools 的 Memory 面板里对比,按 Delta 排序,涨得最多的构造函数就是主要嫌疑。
WeakMap / WeakSet 适合做「跟着对象走」的关联缓存,不会阻止回收;WeakRef 和 FinalizationRegistry 能在对象被回收时收到通知,但时机不保证、也可能永远不触发,不能当资源管理手段——句柄该关还是得显式关。
06|诊断:先取证据,再猜原因
线上出问题时能拿到的证据大致三类:CPU 花在哪、内存被谁占了、进程当时在等什么。
代码里的结构化埋点用 perf_hooks,比 console.time 更适合长期留着:
想把 traceId 一路带进日志,标准做法是 AsyncLocalStorage:它在异步资源之间自动传递上下文,不用把 ctx 当参数层层往下塞。
限制也要知道:AsyncLocalStorage 传播的是「异步资源上下文」,早先在别处注册、后来才触发的监听器可能拿不到正确的 store;跨进程传递仍然只能靠 HTTP 头或消息体。
07|模块深水区:解析顺序、循环依赖与双包
CommonJS 的文件不是裸的 JS,它被包了一层函数:
所以那五个名字是函数参数,不是全局变量;module.exports 才是真正的出口,exports 只是它的初始引用。require 的解析顺序是:内置模块(带 node: 前缀最稳)→ 相对/绝对路径 → 从当前目录逐级向上找 node_modules(外加 NODE_PATH 与全局目录),补扩展名的顺序是 .js、.json、.node。
exports 字段里的条件顺序有意义,从上往下第一个匹配的生效,所以 default 必须放最后:
循环依赖在两套模块系统里表现不同。CJS 是运行时同步求值,遇到循环就把「此刻已经填好的那部分」交出去,所以拿到的可能是不完整的对象:
ESM 有链接阶段:所有 import 绑定在任何代码执行前就建好,循环不会给出「半个对象」,但会在求值阶段撞上 TDZ:
顶层 await 会改变整个模块图的求值方式:模块变成异步求值,入口会等它。副作用是 require() 加载这类 ESM 会直接失败(ERR_REQUIRE_ASYNC_MODULE)——库作者写 ESM 时尽量别在入口用顶层 await,或者同时提供 CJS 入口。
最后是双包风险(dual package hazard):一个包同时提供 import 和 require 两个入口,用两种方式加载的应用就会把同一份代码加载两次,模块级状态(单例、缓存、计数器)也随之变成两份。三种规避办法:只发一种格式让调用方转译;两个入口指向同一份 CJS;或者把状态放到 globalThis 这类进程级位置。
ESM 里要做 CJS 的事,用 createRequire:
08|HTTP 的边界:连接、超时与请求体
框架把细节都藏了,出问题时还是得回到 http 这一层。四个默认值值得记住:headersTimeout 默认 60 秒、requestTimeout 默认 300 秒、keepAliveTimeout 默认 5 秒,以及每个 socket 上的 Nagle 算法默认开启。
这几个数配错会有很典型的症状:headersTimeout 太长,慢速连接能占满连接数;keepAliveTimeout 比反向代理的空闲超时短,代理复用连接时服务端已经关掉,用户看到的就是偶发 502 或 ECONNRESET。
请求体没有内建的大小上限:Content-Length 只是客户端声称的数字,分块传输时连这个都没有。所以要自己限流:
客户端方向的连接复用也要主动管理:http.Agent 的 keepAlive 在 Node 19 起全局默认开启,之前默认关闭、每次请求都要重新握手,高 QPS 下多出来的就是 TIME_WAIT 和握手延迟。fetch(undici)另有一套连接池,并发上限和超时都配在 Dispatcher / Pool 上,不受 http.Agent 影响。
09|取消与超时:AbortSignal 贯穿全链路
Promise 本身没有取消能力,Node 用的是 AbortController / AbortSignal,它已经渗到几乎所有异步 API:fetch、fs 的 promises 版本、timers/promises、流、http.request。
三个实践点:
配合 Promise.allSettled 和 Promise.any 使用时要留意语义:Promise.all 失败时不会取消其余任务,它们照旧在跑;Promise.any 全部失败抛的是 AggregateError,原因都在 errors 里。
10|可靠性:把进程写稳的四件事
一、优雅退出。收到 SIGTERM 后先停止接受新连接,等在途请求结束,同时留一个兜底超时:
二、错误边界。uncaughtException 触发时进程状态已经不可信(可能握着半写的状态、锁、连接),正确处置是记日志、上报、然后退出,交给容器重启,而不是在里面继续处理请求。unhandledRejection 从 Node 15 起默认等同于未捕获异常,会直接退出进程。
三、重试与退避。只重试「可能自愈」的错误(超时、ECONNRESET、ETIMEDOUT、EAI_AGAIN 这类),只重试幂等操作,并且必须带抖动——否则一批实例会同时重试,把刚缓过来的下游再打挂一次。
四、退出码与日志。process.exit() 会打断异步的 stdout 写入,管道里的日志可能丢;用 process.exitCode 让事件循环自然结束更稳。日志一行一条 JSON,带上 traceId、耗时、结果,比多行堆栈好检索也好聚合。
11|安全默认值:几个顺手就能关掉的口子
12|坑自查清单
下面这些是进阶阶段最容易反复踩的,出问题时先按这张表过一遍:
13|收个尾:五条线
进阶内容看着零散,其实也只有五条线:并行(worker_threads 算、cluster 接连接、child_process 跑外部程序)、数据流(highWaterMark 与背压,pipeline 兜底)、内存(堆内堆外分开看,泄漏来自长期引用)、可观测性(事件循环延迟、profile、诊断报告、traceId)、可靠性(取消、超时、错误边界、优雅退出)。
下一步建议按场景深入:写高并发服务就先把连接池、超时和请求体限制补齐;有计算任务就上 worker 池并用 profile 验证收益;遇到内存问题先做快照对比,别凭感觉改代码。参考资料以 Node 官方文档(nodejs.org/api)与各版本的发布说明为准。