w wyl123ly 的博客
MD

后端-02-Nodejs与Express

107 KB 2026.10.11 原文件

后端-02-Nodejs与Express

这篇笔记讲什么

Node.js 不是一门语言,也不是一个框架,而是一个把 V8 引擎和 libuv 粘起来的 JavaScript 运行时(runtime)。理解了它的运行时结构,你才能解释那些"诡异"的现象:为什么一个 while(true) 能让整个服务失去响应、为什么 setTimeout(fn, 0) 有时比 setImmediate 晚、为什么文件读写不会阻塞主线程。

后半篇讲 Express —— 建立在 Node 之上的最小 Web 框架。它的全部魔法就是"一串中间件函数"。掌握中间件模型、错误处理和优雅关闭,你就能写出可上生产的 Node 服务。

本文版本基准:Node.js v24(LTS,Krypton) 与 Express 5.x。版本敏感处已标注「以官方最新文档为准」。


一、是什么:Node.js 的运行时结构

1.1 一句话定义

核心结论

Node.js 是基于 Chrome V8 引擎构建的 JavaScript 运行时环境,它让 JS 能脱离浏览器、在服务端运行,并提供文件系统、网络、进程等系统级能力。

要注意它"不是"什么:

常见误解事实
Node.js 是一门编程语言语言是 JavaScript(以及 TypeScript 等超集),Node 只是运行它的程序
Node.js 是一个 Web 框架框架是 Express / Fastify / NestJS;Node 自带的 node:http 只是底层库
Node.js 是"JavaScript 的 Python"定位更像"带事件循环的运行时";Python 有 GIL 且默认同步阻塞,Node 默认异步非阻塞
Node 只能写后端也能写 CLI 工具、构建工具(Vite、Webpack)、桌面端(Electron)

1.2 V8 与 libuv 的分工

Node.js 启动后,实际由两个完全不同的组件协作:

组件语言职责谁在里面跑
V8C++解析/编译/执行 JavaScript、垃圾回收(GC)、JIT 优化你的所有 JS 代码
libuvC事件循环(event loop)、线程池、异步 I/O、定时器C/C++ 回调,不跑 JS
┌──────────────────────────────────────────────┐
│  你的 JavaScript 代码                          │
├──────────────────────────────────────────────┤
│  Node.js 绑定层(C++ bindings / node_api)      │
├───────────────────────┬──────────────────────┤
│   V8 引擎              │   libuv               │
│   · 执行 JS            │   · 事件循环           │
│   · 内存管理 / GC      │   · 线程池(默认 4)    │
│   · JIT 编译           │   · epoll/kqueue/IOCP │
└───────────────────────┴──────────────────────┘

关键点:JS 代码只在 V8 里执行,而且 V8 只有一条 JS 执行线程。libuv 的工作线程从不执行你的 JS,它们只做 C 层面的系统调用,完成后把回调"投递"回主线程排队。

V8 不是 Node 独有的

Chrome、Edge、Deno、Electron 都用 V8。Node 的价值不在于 V8,而在于 libuv + 一套系统 API(node:fs、node:net、node:crypto…)。

1.3 单线程非阻塞 I/O 模型的真相

"Node 是单线程的"这句话对了一半,它是被简化到失真的说法。准确表述是:

准确的模型

执行 JavaScript 的线程只有一条(主线程 / event loop 线程);但 I/O 操作由 libuv 的线程池和操作系统内核并行完成。你的 JS 只是"发起请求"和"处理结果",中间等待的时间主线程可以去干别的。

哪些操作走哪条路,这是理解 Node 性能的关键:

操作执行方式会阻塞主线程吗
同步 API(fs.readFileSync、crypto.pbkdf2Sync)主线程直接做会,且完全阻塞
异步文件 I/O(fs.promises.readFile)libuv 线程池(默认 4 线程)不会
DNS 解析(dns.lookup)libuv 线程池(调 getaddrinfo)不会
网络 I/O(TCP/HTTP/socket)操作系统异步机制(epoll/kqueue/IOCP)不会,不占线程池
定时器(setTimeout)libuv 定时器堆不会
crypto 的 pbkdf2/scrypt/randomByteslibuv 线程池不会
crypto 的 createHash/createHmac主线程(用 CPU)会
zlib 压缩(异步形式)libuv 线程池不会
你的业务逻辑(循环、JSON、计算)主线程必然占用

线程池大小由环境变量 UV_THREADPOOL_SIZE 控制(默认 4)。这是新手最容易踩的隐性瓶颈:如果同时发起 10 个 fs.readFile,只有 4 个能立刻开始,其余 6 个在排队。

// 演示:线程池只有 4 个位置
// 运行:UV_THREADPOOL_SIZE=4 node pool-demo.mjs
import { pbkdf2 } from 'node:crypto';
import { promisify } from 'node:util';

const pbkdf2Async = promisify(pbkdf2);
const start = Date.now();

// 发起 8 个 CPU 型加密任务,它们全部交给 libuv 线程池
for (let i = 0; i < 8; i++) {
  pbkdf2Async('secret', 'salt', 200_000, 64, 'sha512').then(() => {
    // 你会看到耗时分成两批:前 4 个一批,后 4 个一批
    console.log(`任务 ${i} 完成,耗时 ${Date.now() - start} ms`);
  });
}

什么时候该调 UV_THREADPOOL_SIZE

当你的服务同时处理大量文件读写、DNS 解析或 pbkdf2 密码哈希时,把线程池调到 CPU 核数(或更高)通常有明显收益。但注意:它影响的是进程级的 C 线程数,调太大反而增加上下文切换开销。


二、为什么这样设计:CPU 密集任务是唯一的敌人

2.1 设计动机

传统 Web 服务器的模型是"一个连接一个线程"(Apache prefork、早期 Tomcat)。线程很贵:每个线程约 1MB 栈内存,1 万个并发连接就要 1 万线程,调度开销和内存都爆炸。

Node 的选择是:用一条线程 + 事件循环处理全部连接。代价是——任何一次长时间的同步计算,都会让所有连接一起等待。这就是著名的"C10K 问题"的正解与副作用。

所以 Node 的强项与弱项非常分明:

场景适合 Node 吗原因
API 网关、BFF 层✅ 非常适合大量 I/O 等待、少量计算
实时通信(WebSocket、SSE)✅ 非常适合长连接多,事件驱动天然契合
服务端渲染(SSR)✅ 适合主要是拼接字符串 + 请求后端
图片/视频转码❌ 不适合重 CPU,需交给 worker 或独立服务
大规模数据计算、科学计算❌ 不适合应交给 Python/C++/Go
密码哈希(bcrypt/argon2)⚠️ 需注意异步版走线程池;同步版必阻塞

2.2 一个死循环如何拖垮整个服务

这是每个 Node 开发者都要亲眼见一次的现象。下面是一个故意写坏的服务:

// bad-server.mjs —— 反面教材,不要在生产中使用
import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/cpu') {
    // 同步计算 2 秒:这段时间里 V8 完全被占用,
    // 事件循环无法推进,所有其他请求的回调都排在队列里出不来
    const end = Date.now() + 2000;
    let x = 0;
    while (Date.now() < end) x++;
    res.end(`计算完成,x=${x}\n`);
  } else {
    res.end('pong\n');   // 这个"应该瞬间返回"的接口也会被拖死
  }
});

server.listen(3000, () => console.log('http://localhost:3000'));

用两个终端实测:

# 终端 A:发起一个重的 CPU 请求
curl http://localhost:3000/cpu

# 终端 B:在 A 还没返回时立刻发起轻量请求 —— 你会发现它也要等 2 秒
time curl http://localhost:3000/ping

这就是 Node 最致命的坑

/ping 本身一行计算都没有,却要排队 2 秒。因为事件循环被 /cpu 的 while 占住了——不是"慢",而是整个进程的所有请求都被冻结。

更隐蔽的版本:JSON.parse 一个 50MB 的字符串、对一个 10 万条数组做同步 .sort()、用 fs.readFileSync 读大文件、bcrypt.hashSync。它们在压测时表现为"P99 延迟突然飙到几秒,同时 QPS 断崖下跌"。

2.3 三种解法与选型

方案隔离级别内存共享通信成本适用场景
worker_threads同进程内线程✅ 可共享 ArrayBuffer低(结构化克隆)CPU 密集型计算,数据量大
child_process独立进程❌中(IPC / stdio)需要隔离崩溃、调用外部程序
cluster独立进程❌中横向扩展 HTTP 服务(见第七节)
拆成独立服务独立机器❌高(网络)转码、报表等长任务,可独立扩容

下面用 worker_threads 修掉上面的问题。先把计算挪到 worker 文件:

// cpu-worker.mjs —— 在 worker 线程里执行的重计算
import { parentPort, workerData } from 'node:worker_threads';

// 模拟一个耗时 2 秒的同步计算
function heavyCompute(ms) {
  const end = Date.now() + ms;
  let x = 0;
  while (Date.now() < end) x++;
  return x;
}

// worker 线程里没有主线程的事件循环负担,可以放心同步阻塞
parentPort.postMessage({ result: heavyCompute(workerData.ms) });
// good-server.mjs —— 把计算丢给 worker,主线程始终空闲
import http from 'node:http';
import { Worker } from 'node:worker_threads';

// 把"创建 worker"包装成 Promise,这样路由里可以 await
function runOnWorker(ms) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(new URL('./cpu-worker.mjs', import.meta.url), {
      workerData: { ms },
    });
    worker.once('message', resolve);          // 正常结果
    worker.once('error', reject);             // 未捕获异常
    worker.once('exit', (code) => {           // 异常退出码兜底
      if (code !== 0) reject(new Error(`worker 退出码 ${code}`));
    });
  });
}

const server = http.createServer(async (req, res) => {
  if (req.url === '/cpu') {
    const { result } = await runOnWorker(2000);
    res.end(`计算完成,x=${result}\n`);
  } else {
    res.end('pong\n');   // 现在它是真的瞬间返回
  }
});

server.listen(3000, () => console.log('http://localhost:3000'));

再跑一次同样的测试:/ping 会在几毫秒内返回,而 /cpu 请求仍在后台计算。

worker 的正确用法:用池,不要每次新建

上面为了演示清晰,每个请求新建一个 Worker。生产环境必须用线程池(如 piscina),因为创建一个 Worker 的开销约 10–30ms,比很多计算任务本身还贵。官方文档也明确提示:"In practice, use a pool of Workers for these kinds of tasks."

另外:worker_threads 对 CPU 密集任务有效,对 I/O 密集任务没有帮助——Node 内置的异步 I/O 比 worker 更高效。


三、事件循环:六个阶段与两个队列

3.1 阶段划分

Node 的事件循环比浏览器复杂得多。它由 libuv 实现,每一次"循环"按固定顺序经过若干阶段:

   ┌───────────────────────────┐
┌─►│           timers          │  setTimeout / setInterval 到期回调
│  └─────────────┬─────────────┘
│  ┌─────────────▼─────────────┐
│  │     pending callbacks     │  上一轮延迟的 I/O 回调(如 TCP 错误)
│  └─────────────┬─────────────┘
│  ┌─────────────▼─────────────┐
│  │       idle, prepare       │  内部使用
│  └─────────────┬─────────────┘
│  ┌─────────────▼─────────────┐
│  │           poll            │  ★ 核心:取新 I/O 事件、执行 I/O 回调
│  └─────────────┬─────────────┘     无事可做时在这里等待
│  ┌─────────────▼─────────────┐
│  │           check           │  setImmediate 回调
│  └─────────────┬─────────────┘
│  ┌─────────────▼─────────────┐
└──┤      close callbacks      │  socket.on('close') 等
   └───────────────────────────┘
阶段处理什么相关 API
timers到期的定时器回调setTimeout、setInterval
pending callbacks推迟到下一轮的系统操作回调TCP ECONNREFUSED 等错误回调
poll取新 I/O 事件并执行回调;队列空且无 setImmediate 时在此阻塞等待fs、net、http 的回调
check紧跟在 poll 之后执行setImmediate
close callbacks关闭类回调socket.on('close')

两个不属于任何阶段的特殊队列,它们会在每个阶段之间和每个回调执行完之后被清空:

队列加入方式执行时机递归风险
nextTick 队列process.nextTick(fn)当前操作结束后立即执行,优先于 Promise⚠️ 递归调用会饿死事件循环
microtask 队列Promise.then、queueMicrotask、await每个 macrotask 之后清空同样可饿死,但通常更可控

3.2 process.nextTick 与 setImmediate 的区别

这是面试高频题,也是实践中的真实陷阱。

// order.mjs
import fs from 'node:fs';

console.log('① 同步开始');

setTimeout(() => console.log('⑤ setTimeout'), 0);
setImmediate(() => console.log('⑥ setImmediate'));

process.nextTick(() => console.log('③ nextTick'));
Promise.resolve().then(() => console.log('④ promise.then'));

fs.readFile(import.meta.filename, () => {
  // 这个回调在 poll 阶段执行,此时已进入某一轮循环
  console.log('⑦ I/O 回调');
  setTimeout(() => console.log('⑨ I/O 里的 setTimeout'), 0);
  setImmediate(() => console.log('⑧ I/O 里的 setImmediate'));
});

console.log('② 同步结束');

输出(Node v24 实测行为):

① 同步开始
② 同步结束
③ nextTick
④ promise.then
⑤ setTimeout          ← 或 ⑥,见下方说明
⑥ setImmediate
⑦ I/O 回调
⑧ I/O 里的 setImmediate   ← 一定先于 ⑨
⑨ I/O 里的 setTimeout

三条必须记住的结论

1. process.nextTick 的优先级高于 Promise。它是"当前操作之后、任何 I/O 之前"。

2. 在主模块里,setTimeout(fn, 0) 与 setImmediate(fn) 的先后顺序不确定——取决于进程启动耗时是否已超过 1ms、定时器是否已在 timers 阶段之前到期。不要依赖这个顺序。

3. 在 I/O 回调内部,setImmediate 永远早于 setTimeout。因为 I/O 回调在 poll 阶段执行,紧接着就是 check 阶段(setImmediate),而 setTimeout 要等到下一轮的 timers 阶段。这是唯一确定的顺序。

process.nextTick 的递归陷阱

```js

function recurse() {

process.nextTick(recurse); // 永远不会让出事件循环

}

recurse(); // 进程卡死,I/O 全部饿死,连日志都刷不出来

```

nextTick 队列在当前操作后必须被清空才会继续,所以递归填充它等于写了个死循环。需要"让出一轮"时,用 setImmediate(进入下一轮循环)而不是 process.nextTick。

3.3 与浏览器事件循环的差异

交叉引用:JavaScript-04-异步编程 里讲的是浏览器侧的模型,两者不是同一套实现。

对比项浏览器Node.js
实现者HTML 规范 + 浏览器引擎libuv
循环结构单一循环:task → microtask → 渲染多阶段(timers/poll/check/close…)
是否有渲染阶段有(requestAnimationFrame、样式布局)无
微任务清空时机每个 task 之后每个阶段之间 + 每个回调之后
setImmediate❌ 不存在✅ check 阶段(IE 曾有非标准实现)
process.nextTick❌ 不存在✅ 优先级高于 Promise
queueMicrotask✅✅
MessageChannel✅ 常用于调度✅ 在 worker_threads 中
setTimeout(fn, 0) 最小延迟嵌套 5 层后强制 ≥4ms1ms
定时器精度受渲染帧影响受事件循环各阶段耗时影响

实践含义

在 Node 里写"让出控制权"的代码,用 await new Promise(r => setImmediate(r));在浏览器里通常用 setTimeout(r, 0) 或 requestAnimationFrame。同一个习惯不要跨环境照搬。


四、模块系统:CommonJS 与 ESM

4.1 两套系统的本质差异

对比项CommonJS (CJS)ES Module (ESM)
语法require() / module.exportsimport / export
加载时机运行时、同步解析时确定依赖图,异步加载
加载结果值的拷贝(对原始类型)值的实时只读绑定(live binding)
能否条件加载✅ 可以写在 if 里❌ 静态 import 不行,需 await import()
顶层 await❌✅
this 在模块顶层module.exportsundefined
循环依赖行为得到未完成的导出对象得到 TDZ 报错或未初始化绑定
文件扩展名可省略相对路径必须写扩展名
变量__filename、__dirname 可用❌ 不可用,用 import.meta.*
能否读 require.cache✅❌ 独立缓存
NODE_PATH 生效✅❌

4.2 package.json 的 type 字段与判定规则

Node 判定一个 .js 文件用哪套系统,规则是(见 Modules: Packages):

条件判定结果
扩展名 .mjs强制 ESM
扩展名 .cjs强制 CJS
扩展名 .js 且最近 package.json 的 type: "module"ESM
扩展名 .js 且最近 package.json 的 type: "commonjs" 或未设置看内容:含 ESM 语法则 ESM,否则 CJS
{
  "name": "demo",
  "version": "1.0.0",
  "type": "module",          // 让本目录下的 .js 默认按 ESM 解析
  "main": "./src/index.js",
  "exports": {               // 比 main 更严格:控制外部能 import 哪些路径
    ".": "./src/index.js",
    "./utils": "./src/utils.js"
  }
}

type: "module" 是开关,不是建议

一个仓库里混用两种系统是最常见的 Node 报错来源。典型症状:

- ReferenceError: require is not defined in ES module scope → 你在 ESM 文件里用了 require

- ReferenceError: __dirname is not defined → 你在 ESM 文件里用了 __dirname

- SyntaxError: Cannot use import statement outside a module → 你在 CJS 文件里用了 import

- ERR_MODULE_NOT_FOUND → ESM 相对导入漏了 .js 扩展名

建议:新项目统一用 ESM;维护老项目时不要混改,一个目录保持一种风格。

4.3 __dirname 在 ESM 中的替代

CJS 里 __dirname 是模块包装函数注入的参数,ESM 没有它。Node v24 提供了两种替代:

// 方式一(推荐):import.meta.dirname / import.meta.filename
// v20.11.0 引入,v24.0.0 起不再是实验性特性
console.log(import.meta.dirname);    // 当前文件所在目录的绝对路径
console.log(import.meta.filename);   // 当前文件的绝对路径
console.log(import.meta.url);        // file:///... URL 形式

// 方式二(兼容老版本):手动从 URL 转换
import { fileURLToPath } from 'node:url';
import path from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

还有几个 CJS 习惯用法的 ESM 等价物:

CJS 写法ESM 等价物
require.main === moduleimport.meta.main(v24.2.0+)
require.resolve('./x')import.meta.resolve('./x.js')
require('./x')(动态、条件)await import('./x.js')
加载 .jsonimport data from './d.json' with { type: 'json' }
加载原生插件 .nodemodule.createRequire(import.meta.url)
// 判断"是否作为入口直接运行",ESM 写法(v24.2.0+)
if (import.meta.main) {
  main();
}
// 补一个 CJS 侧的现代化能力:Node 22.12+ 支持 require() 直接加载 ESM
// 但仅限"同步 ESM"(不含顶层 await)
const esmModule = require('./some-esm.mjs');   // 在 CJS 文件中可行

关于互操作性

Node 官方文档明确说明:CommonJS 的 require 目前只支持加载同步的 ES 模块(即不含顶层 await 的 ESM)。含顶层 await 的 ESM 必须用 await import()。反向(ESM 里 import CJS)一直是支持的,CJS 的 module.exports 会成为 ESM 的 default 导出。


五、内置模块实用清单

以下都是零依赖就能用的能力。熟悉它们能显著减少 npm 包的引入。

5.1 node:fs/promises —— 推荐的文件 API

不要用 fs.readFileSync(阻塞)也不要手写 util.promisify(fs.readFile),直接用 node:fs/promises:

import { readFile, writeFile, mkdir, readdir, stat, rm } from 'node:fs/promises';
import path from 'node:path';

// 读取 JSON 配置
const config = JSON.parse(await readFile('./config.json', 'utf8'));

// 递归创建目录(recursive 是幂等的,已存在不报错)
await mkdir('./data/logs', { recursive: true });

// 原子写入:先写临时文件再 rename,避免读到半个文件
const tmp = path.join('./data', `.tmp-${process.pid}`);
await writeFile(tmp, JSON.stringify(config, null, 2));
await (await import('node:fs/promises')).rename(tmp, './data/config.json');

// 判断文件是否存在(不要用 fs.existsSync,已废弃风格)
async function exists(p) {
  try { await stat(p); return true; } catch { return false; }
}

5.2 node:path —— 永远不要手拼路径

import path from 'node:path';

path.join('a', 'b', '..', 'c');        // 'a/c'   —— 规范化并跨平台处理分隔符
path.resolve('src', 'index.js');       // 绝对路径,基于 process.cwd()
path.basename('/tmp/x.txt');           // 'x.txt'
path.extname('/tmp/x.tar.gz');         // '.gz'   —— 只取最后一段!
path.dirname('/tmp/a/b.txt');          // '/tmp/a'
path.parse('/tmp/a/b.txt');            // { root, dir, base, ext, name }
path.sep;                              // Windows '\\',Linux '/'
path.posix.join('a', 'b');             // 强制用 '/' 拼接,适合生成 URL

path.join ≠ path.resolve

join 只做字符串拼接与规范化;resolve 会从右往左找到第一个绝对路径片段,并以 process.cwd() 为基准补全。path.resolve('a') 的结果依赖你从哪个目录启动进程——这正是容器里"本地能跑、上线 404"的常见原因。要基于文件位置而非工作目录,用 import.meta.dirname。

5.3 node:os 与 node:process

import os from 'node:os';
import process from 'node:process';

// os:拿机器与资源信息,常用于健康检查、日志、自适应并发
os.cpus().length;          // CPU 逻辑核数(cluster / 线程池调优的依据)
os.totalmem();             // 总内存(字节)
os.freemem();              // 空闲内存
os.loadavg();              // 1/5/15 分钟负载(Windows 上恒为 [0,0,0])
os.hostname();
os.platform();             // 'linux' | 'darwin' | 'win32'
os.arch();                 // 'x64' | 'arm64'
os.tmpdir();               // 临时目录,跨平台

// process:当前进程
process.pid;
process.version;           // 'v24.21.0' 之类
process.cwd();             // 工作目录(不是脚本目录!)
process.env.NODE_ENV;
process.argv;              // ['node', '/path/app.js', '--flag']
process.uptime();          // 秒
process.memoryUsage();     // { rss, heapTotal, heapUsed, external, arrayBuffers }
process.exitCode = 1;      // 推荐:设置退出码后让进程自然结束
process.hrtime.bigint();   // 高精度单调时钟,用于性能测量

用 process.hrtime.bigint() 而不是 Date.now() 测耗时

Date.now() 会受系统时钟调整(NTP 校时、夏令时)影响,可能出现负数;hrtime.bigint() 是单调递增的纳秒计数器。

5.4 node:crypto —— 密码与随机数

交叉引用:后端-06-认证与授权 讲完整的认证方案,这里只列关键 API。

import { randomUUID, randomBytes, createHash, timingSafeEqual, scrypt } from 'node:crypto';
import { promisify } from 'node:util';

randomUUID();                    // 无需依赖的 UUID v4
randomBytes(32).toString('hex'); // 密码学安全随机数;不要用 Math.random()

// 校验签名/Token 时用恒定时间比较,防时序攻击
function safeEqual(a, b) {
  const ba = Buffer.from(a), bb = Buffer.from(b);
  if (ba.length !== bb.length) return false;      // 长度不同直接 false
  return timingSafeEqual(ba, bb);
}

// 密码哈希:用 scrypt(内存硬)或 argon2/bcrypt 库;绝不用 MD5/SHA1
const scryptAsync = promisify(scrypt);
async function hashPassword(password) {
  const salt = randomBytes(16);
  const derived = await scryptAsync(password, salt, 64);   // 走 libuv 线程池
  return `scrypt$${salt.toString('hex')}$${derived.toString('hex')}`;
}

// 计算文件摘要(注意:createHash 在主线程跑,大文件会阻塞)
createHash('sha256').update('hello').digest('hex');

用 Math.random() 生成令牌 = 没有安全

会话 ID、密码重置令牌、验证码必须用 crypto.randomBytes() / crypto.randomUUID()。Math.random() 是可预测的 PRNG。

5.5 node:stream —— 流与背压

流是 Node 处理大数据的核心抽象。背压(backpressure) 指的是:当写入端比读取端快时,系统向上游传递"慢一点"的信号,避免内存被撑爆。

四类流:

类型例子典型方法
Readablefs.createReadStream、HTTP 请求体read()、pipe()、on('data')
Writablefs.createWriteStream、HTTP 响应write()、end()、drain 事件
DuplexTCP socket兼有读写
Transformzlib.createGzip()读入→转换→写出
// 反面教材:把 2GB 文件全读进内存
import { readFile, writeFile } from 'node:fs/promises';
const big = await readFile('./huge.log');       // 💥 内存直接爆掉
await writeFile('./huge.copy.log', big);
// 正确做法:用管道,内存占用恒定(约等于缓冲区大小)
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';

await pipeline(
  createReadStream('./huge.log'),   // 源
  createGzip(),                     // 转换
  createWriteStream('./huge.log.gz')// 目标
);
// pipeline 会自动处理背压、错误传播和资源清理
// 手动理解背压:write() 返回 false 表示缓冲区满,必须等 'drain'
import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';

const out = createWriteStream('./out.txt');
const source = Readable.from(Array.from({ length: 1e5 }, (_, i) => `行 ${i}\n`));

for await (const chunk of source) {
  // 返回 false → 内部缓冲已满,继续写会占用内存
  if (!out.write(chunk)) {
    await new Promise((resolve) => out.once('drain', resolve));
  }
}
out.end();

优先用 pipeline()

stream.pipeline()(Promise 版在 node:stream/promises)会正确处理:所有流的错误传播、出错时销毁下游流、完成时关闭资源。手写 .pipe() 链在中间出错时不会自动清理,容易泄漏文件句柄。

另外,Express 的 res 本身就是一个 Writable 流,所以"生成大文件下载"和"代理转发"都应该走 pipeline():

// Express 中流式返回大文件(自动支持 Range 请求请改用 res.sendFile)
import { pipeline } from 'node:stream/promises';
import { createReadStream } from 'node:fs';

app.get('/download/:name', async (req, res, next) => {
  res.setHeader('Content-Type', 'application/octet-stream');
  // res 是 Writable 流,断连时 pipeline 会自动销毁读取流
  await pipeline(createReadStream(`./files/${req.params.name}`), res);
});

5.6 node:http —— 框架之下的那一层

Express 就是 node:http 的封装。知道底层长什么样,调试时不会抓瞎:

import http from 'node:http';

const server = http.createServer((req, res) => {
  // req:IncomingMessage(Readable 流)
  console.log(req.method, req.url, req.httpVersion);   // 'GET' '/a?b=1' '1.1'
  console.log(req.headers);                            // 全是小写键

  // res:ServerResponse(Writable 流)
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json; charset=utf-8');
  res.end(JSON.stringify({ ok: true }));
});

// keepAliveTimeout:空闲连接保持多久;headersTimeout:收完请求头的超时
server.keepAliveTimeout = 65_000;   // 应略大于上游反向代理的 keepalive
server.headersTimeout = 66_000;     // 必须大于 keepAliveTimeout
server.requestTimeout = 300_000;    // 单个请求总超时

server.listen(3000, '0.0.0.0', () => {
  console.log('listening on 0.0.0.0:3000');
});

keepAliveTimeout 的经典事故

Nginx / 云负载均衡默认 keepalive_timeout 60s,Node 默认 keepAliveTimeout 是 5 秒(v24 中默认值请以官方文档为准)。若 Node 的超时大于上游,反向代理会在连接上复用到一半时把它掐掉,客户端收到 502 / socket hang up,且随机出现、难以复现。

正确做法:Node 的 keepAliveTimeout 略大于上游代理的值(例如代理 60s,Node 设 65s)。


六、环境变量与配置管理

6.1 .env 与 process.env

process.env 的值永远是字符串或 undefined,这是无数 Bug 的源头:

process.env.PORT;         // '3000'(字符串!)不是 3000
process.env.DEBUG;        // 若设置了 DEBUG= 空字符串,这里是 '',是 falsy 但存在
process.env.NOT_SET;      // undefined
if (process.env.DEBUG) {} // ⚠️ DEBUG=false 时依然为真!字符串 'false' 是真值

因此必须做显式转换与校验。两种主流做法:

// 做法 A:手写零依赖校验(适合小项目)
function required(name) {
  const v = process.env[name];
  if (v === undefined || v === '') throw new Error(`缺少必需的环境变量:${name}`);
  return v;
}
function intFromEnv(name, fallback) {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  const n = Number.parseInt(raw, 10);
  if (!Number.isInteger(n)) throw new Error(`环境变量 ${name} 不是整数:${raw}`);
  return n;
}
function boolFromEnv(name, fallback) {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());  // 显式白名单
}
// 做法 B:用 zod 定义 schema(推荐,见下方完整示例 config/env.js)

.env 绝不能提交进 Git

```gitignore

.env

.env.local

.env.*.local

```

只提交 .env.example(含键名和占位值,不含真实密钥)。一旦密钥进过 Git 历史,就必须立刻轮换——删掉文件不等于删掉历史记录。

6.2 NODE_ENV 的用途与陷阱

NODE_ENV 只是一个普通环境变量,Node 本身不读它。但它被大量库用作约定:

NODE_ENV 值库的典型行为
production关闭调试输出、启用缓存、压缩错误堆栈、React 去掉 dev 警告、Express 启用视图缓存
development详细错误、热重载、宽松的 CORS
test使用测试数据库、mock 外部服务
未设置⚠️ 各库行为不一致,最危险的状态

三个 NODE_ENV 陷阱

1. NODE_ENV 不影响 Express 的错误处理。Express 只看 app.get('env'),而它的默认值来自 process.env.NODE_ENV || 'development'。以为"设了 production 就安全了"是错的——你仍然要写自己的错误处理中间件。

2. 不要在运行时改 process.env.NODE_ENV。很多库在 require 时就读取并缓存了这个值,之后再改无效。

3. 它同时承载了"性能开关"和"安全开关"两种语义。把 NODE_ENV=production 用来控制"是否返回堆栈给客户端"是可行的,但不要用它来控制"连接哪个数据库"——那是配置,不是环境语义,应该用显式的 DATABASE_URL。

6.3 配置校验:启动时失败,而不是运行时失败

配置的核心原则:fail fast

缺失或错误的配置应该在进程启动的 100ms 内报错退出,而不是等到第一个请求进来才 500。这样编排系统(K8s、PM2、systemd)能立刻发现并回滚,而不是让一个"半死"的实例留在负载均衡池里。

下面把配置模块写成完整可用的形式(用 zod 校验,见第七节示例)。

// src/config/env.js —— 配置的单一来源
import 'dotenv/config';                   // 副作用导入:把 .env 读进 process.env
import { z } from 'zod';

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  HOST: z.string().default('0.0.0.0'),

  DATABASE_URL: z.string().min(1, 'DATABASE_URL 不能为空'),
  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),

  // 逗号分隔的来源列表 → 数组;上线后务必收敛为白名单
  CORS_ORIGINS: z.string().default('http://localhost:5173')
    .transform((s) => s.split(',').map((x) => x.trim()).filter(Boolean)),

  SHUTDOWN_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
});

const parsed = EnvSchema.safeParse(process.env);

if (!parsed.success) {
  // 打印人能看懂的错误后立即退出:配置错就不该启动
  console.error('❌ 环境变量校验失败:');
  for (const issue of parsed.error.issues) {
    console.error(`   - ${issue.path.join('.') || '(根)'}: ${issue.message}`);
  }
  process.exit(1);
}

export const env = Object.freeze(parsed.data);   // 冻结,防止运行中被改
export const isProd = env.NODE_ENV === 'production';
# .env.example —— 提交这个文件,不提交 .env
NODE_ENV=development
PORT=3000
HOST=0.0.0.0
DATABASE_URL=./data/app.db
LOG_LEVEL=debug
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
SHUTDOWN_TIMEOUT_MS=10000

z.coerce.number() 解决了什么

process.env.PORT 是字符串 '3000'。z.coerce.number() 会先做 Number(value) 再校验,于是 PORT=abc 会在启动时报错而不是在 server.listen('abc') 时抛出一个费解的类型错误。这是 zod 处理环境变量最常用的技巧。


七、Express:中间件模型

7.1 核心思想:一切皆中间件

Express 的本质

官方文档的原话是:"an Express application is essentially a series of middleware function calls executed during the request-response cycle."(一个 Express 应用本质上就是请求-响应周期中执行的一串中间件函数调用。)

中间件就是一个签名为 (req, res, next) 的函数,能做四件事:

  1. 执行任意代码;
  2. 修改 req / res 对象;
  3. 结束请求-响应周期(调用 res.send() / res.end() 等);
  4. 调用 next() 把控制权交给下一个中间件。

如果既没结束响应,也没调用 next(),请求就会永远挂起——这是新手最常造成的"接口不返回"故障。

7.2 洋葱模型与执行顺序

中间件按注册顺序执行。所谓"洋葱模型"指的是:请求像穿过洋葱一样一层层深入,而 res 上的操作(或 next() 之后的代码)会沿原路返回。

// onion.mjs
import express from 'express';
const app = express();

app.use((req, res, next) => {
  console.log('① 进入 A');
  next();                              // 交给下一层
  console.log('⑦ 离开 A');             // 内层全部完成后回到这里
});

app.use((req, res, next) => {
  console.log('② 进入 B');
  next();
  console.log('⑥ 离开 B');
});

app.get('/', (req, res, next) => {
  console.log('③ 路由处理器');
  res.on('finish', () => console.log('⑤ 响应已发送(finish 事件)'));
  res.json({ ok: true });
  console.log('④ 处理器返回(响应已排队)');
});

app.listen(3000);

访问 / 的输出顺序:

① 进入 A
② 进入 B
③ 路由处理器
④ 处理器返回(响应已排队)
⑤ 响应已发送(finish 事件)
⑥ 离开 B
⑦ 离开 A

两个反直觉点

1. next() 之后的代码仍会执行,而且是在内层全部执行完之后。所以 next() 前面不要写"清理逻辑",那部分应该放在 next() 之后或 res.on('finish') 里。

2. 不要在 next() 之后再写 res.send(),会得到 ERR_HTTP_HEADERS_SENT。判断依据是 res.headersSent。

7.3 app.use 与路由级中间件的区别

对比项app.use(path?, fn)app.METHOD(path, fn) / router.METHOD
匹配方式前缀匹配(/api 也匹配 /api/users)精确匹配(受路由模式控制)
匹配的 HTTP 方法全部方法仅指定的方法
能否挂在根路径✅ app.use(fn) 匹配所有请求❌ 必须给 path
典型用途日志、CORS、鉴权、body 解析、404业务路由
与 Router 组合app.use('/api', router)router.get('/users', h)
app.use(logger);                  // 所有请求、所有方法
app.use('/api', authRequired);    // 所有 /api 开头的请求(含 /api/a/b/c)
app.get('/api/users', listUsers); // 仅 GET /api/users

// ⚠️ 中间件里的 req.path 是"去掉挂载点之后"的路径
app.use('/api', (req, res, next) => {
  console.log(req.path);       // 访问 /api/users → '/users'
  console.log(req.baseUrl);    // '/api'
  console.log(req.originalUrl);// '/api/users?x=1'(原始完整 URL)
  next();
});

路由拆分用 express.Router()

Router 是一个独立的中间件+路由实例,可以像中间件一样被 app.use() 挂载。它让每个业务模块自己管理路径前缀:

// src/features/tasks/tasks.routes.js
import { Router } from 'express';

const router = Router();

// 这里的 '/' 实际是 '/api/tasks'(由挂载点决定),模块内不需要知道前缀
router.get('/', listTasks);
router.get('/:id', getTask);
router.post('/', createTask);
router.patch('/:id', updateTask);
router.delete('/:id', deleteTask);

export default router;
// src/app.js 中挂载
app.use('/api/tasks', tasksRouter);

Router 还有 router.param()(对同名前缀参数统一预处理)和 router.route()(链式定义同一路径的多个方法)两个便利特性:

// 链式定义:一个路径的多种方法写在一起,可读性更好
router.route('/:id')
  .get(getTask)
  .patch(updateTask)
  .delete(deleteTask);

7.4 内置中间件

Express 5 内置了这些中间件(无需额外安装):

中间件作用常见配置
express.json([opts])解析 Content-Type: application/json 的请求体{ limit: '1mb' }
express.urlencoded([opts])解析表单提交(application/x-www-form-urlencoded){ extended: true }
express.raw([opts])把请求体读成 BufferWebhook 签名验证
express.text([opts])把请求体读成字符串纯文本接口
express.static(root, [opts])静态文件服务{ maxAge: '1d', etag: true }
// 只解析 JSON,并限制体积;超限会抛 413,交给错误中间件统一处理
app.use(express.json({ limit: '1mb' }));

// 只需要给 webhook 路由保留原始 Buffer,用于校验签名
app.post('/webhook', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
  const raw = req.body;                 // Buffer,未被解析
  // verifySignature(raw, req.get('x-signature')) ...
  res.sendStatus(204);
});

express.json() 的位置很关键

- 放在鉴权中间件之前:攻击者可以用超大 JSON 消耗你的 CPU,尽管请求最终会被拒绝。应该先限流/鉴权,再解析 body。

- 忘记 limit:默认限制存在,但显式写出来更清晰。1MB 通常够用;上传文件应走 multipart/form-data,绝不用 JSON 传 base64。

- 想让 req.body 可用却忘了挂载它,会得到 undefined——Express 5 中 req.body 默认是 undefined 而非 {},解构时会直接抛 TypeError。

7.5 错误处理中间件:必须四个参数

最常见的 Express 坑

错误处理中间件必须声明四个参数:(err, req, res, next)。哪怕你根本不用 next,也必须写出来,因为 Express 靠 fn.length === 4 来识别它是错误处理器。

// ✅ 会被识别为错误处理中间件
app.use((err, req, res, next) => { /* ... */ });

// ❌ 只写三个参数 → Express 当成普通中间件,错误永远不会到这里
app.use((err, req, res) => { /* ... */ });

// ❌ 用默认参数/剩余参数改变了 length → 同样失效
app.use((err, req, res, next = () => {}) => { /* ... */ });
app.use((...args) => { /* ... */ });

// ❌ 用解构 → length 是 1
app.use(({ message }, req, res, next) => { /* ... */ });

正确写法与顺序:

// 1. 所有正常路由
app.use('/api/tasks', tasksRouter);

// 2. 兜底 404(没有 next(err),因为此时还没有错误)
app.use((req, res) => {
  res.status(404).json({ success: false, error: { code: 'NOT_FOUND', message: `找不到 ${req.method} ${req.originalUrl}` } });
});

// 3. 全局错误处理器 —— 必须放在最后
app.use((err, req, res, next) => {
  // 经验法则:如果响应头已经发出,就只能交还给 Express 默认处理器去销毁连接
  if (res.headersSent) return next(err);

  const status = Number.isInteger(err.status) ? err.status : 500;
  const isServerError = status >= 500;

  // 5xx 必须记录完整堆栈;4xx 通常只记一行,避免日志噪音
  if (isServerError) req.log.error({ err }, '未处理的服务端错误');
  else req.log.warn({ err: err.message, status }, '客户端错误');

  res.status(status).json({
    success: false,
    error: {
      code: err.code ?? (isServerError ? 'INTERNAL_ERROR' : 'BAD_REQUEST'),
      message: isServerError ? '服务器内部错误' : err.message,
      // 只有非生产环境才把堆栈返回给客户端
      ...(isProd ? {} : { stack: err.stack }),
    },
  });
});

res.headersSent 这个检查不能省

如果你的中间件在 next(err) 之前已经调用过 res.write()(比如流式响应中途出错),此时再调 res.status().json() 会抛 ERR_HTTP_HEADERS_SENT,导致错误处理器自身崩溃。把错误交回 next(err),让 Express 的默认处理器销毁 socket 才是正确做法。

7.6 async 处理器中抛错的版本差异

这是 Express 用户最痛的历史问题,在 Express 5 中已经改变,务必分清版本:

写法Express 4Express 5
同步 throw✅ 自动捕获✅ 自动捕获
回调式 fs.readFile(p, cb) 里 throw❌ 不捕获❌ 不捕获
返回 Promise 的处理器(含 async fn)reject❌ 不捕获,进程崩溃✅ 自动转给 next(err)
不返回的 Promise(promise.then(...) 忘了 return)❌ 不捕获❌ 不捕获
.catch(next)✅ 手动可行✅ 可行

Express 5 官方文档明确写道:"Route handlers and middleware that return a Promise call next(value) automatically when they reject or throw an error, and async functions always return a Promise, so their errors reach Express with no extra work."

// Express 5:async 处理器的错误会被自动转发
app.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id);   // reject → 自动 next(err)
  res.json(user);
});

但三类情况仍然不会被捕获,必须自己处理:

// 坑 1:忘记 return —— 表达式语句不把 Promise 交给 Express
app.get('/bad', (req, res) => {
  Promise.resolve().then(() => { throw new Error('BROKEN'); });
  // ↑ Promise 被丢弃,成为 unhandledRejection
});

// ✅ 修法:return 出去
app.get('/good', (req, res) => {
  return Promise.resolve().then(() => { throw new Error('BROKEN'); });
});

// ✅ 或者显式 .catch(next)
app.get('/good2', (req, res, next) => {
  Promise.resolve().then(() => { throw new Error('BROKEN'); }).catch(next);
});

// 坑 2:回调式 API 里的异步 throw —— 脱离了调用栈
app.get('/cb', (req, res) => {
  setTimeout(() => { throw new Error('BROKEN'); }, 0);   // 💥 进程崩溃
});

如果你还在 Express 4 上,有两条路:

// 方案 A(Express 4 专用):装 express-async-errors
// 必须在所有路由定义之前 import,它会猴补丁 patch Router 层
import 'express-async-errors';
import express from 'express';
const app = express();
app.get('/x', async (req, res) => { throw new Error('会被捕获'); });
// 方案 B:手写包装器,零依赖、行为可预测(推荐)
// 把 async 处理器的 reject 显式转成 next(err)
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

router.get('/:id', asyncHandler(async (req, res) => {
  const task = await store.get(req.params.id);
  if (!task) throw new HttpError(404, 'TASK_NOT_FOUND', '任务不存在');
  res.json({ success: true, data: task });
}));

该选哪个

- 新项目:用 Express 5,async 处理器直接写,不需要包装器。但要记得 return 每一个 Promise。

- 存量 Express 4 项目:用 asyncHandler 包装器更可控;express-async-errors 依赖内部实现,升级 Express 5 时会冲突(Express 5 已内置该能力,此时应移除这个包)。

- 无论如何,都要注册 process.on('unhandledRejection') 与 uncaughtException 作为最后防线(见第八节)。

7.7 处理链上的其他必备中间件

关注点常用包关键配置
参数校验zod(推荐)/ express-validator在路由层校验 body/query/params
安全响应头helmetapp.use(helmet())
CORScors用函数式 origin 做白名单
请求日志pino-http(生产)/ morgan(开发)输出 JSON 便于采集
限流express-rate-limit登录接口必须限流
压缩compression放在静态资源之前
会话express-session默认内存存储不可用于生产
// CORS 白名单:不要用 origin: true(等于反射任意来源)
import cors from 'cors';
import { env, isProd } from './config/env.js';

app.use(cors({
  origin(origin, callback) {
    // 同源请求(curl、服务端调用)没有 Origin 头,放行
    if (!origin) return callback(null, true);
    if (env.CORS_ORIGINS.includes(origin)) return callback(null, true);
    // 用 Error 拒绝会走到错误处理器;传 false 则只是不加 CORS 头
    callback(new Error(`CORS 不允许的来源:${origin}`));
  },
  credentials: true,                       // 允许携带 Cookie
  methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86_400,                          // 预检结果缓存 24 小时
}));

**credentials: true + origin: '*' 是无效组合**

浏览器规范明确禁止:携带凭证的跨域请求不允许 Access-Control-Allow-Origin: *。必须回显具体的来源。同时前端也要设 credentials: 'include',缺一不可。

另外提醒:CORS 是浏览器的防护机制,它不保护你的 API。curl 和任何服务端脚本都能绕过它。真正的访问控制靠鉴权(后端-06-认证与授权)。

// 请求日志:pino-http 自带 requestId,能串起同一请求的所有日志
import { pino } from 'pino';
import pinoHttp from 'pino-http';
import { randomUUID } from 'node:crypto';
import { env, isProd } from './config/env.js';

export const logger = pino({
  level: env.LOG_LEVEL,
  // 生产输出 JSON 给采集器;开发用 pino-pretty 提高可读性
  ...(isProd ? {} : { transport: { target: 'pino-pretty', options: { colorize: true } } }),
  redact: {
    // 绝不把敏感字段写进日志
    paths: ['req.headers.authorization', 'req.headers.cookie', 'req.body.password', 'req.body.token'],
    censor: '[已脱敏]',
  },
});

export const httpLogger = pinoHttp({
  logger,
  genReqId: (req, res) => {
    // 复用上游传来的 trace id,没有就生成;写回响应头方便排查
    const id = req.headers['x-request-id'] ?? randomUUID();
    res.setHeader('x-request-id', id);
    return id;
  },
  customLogLevel(req, res, err) {
    if (err || res.statusCode >= 500) return 'error';
    if (res.statusCode >= 400) return 'warn';
    return 'info';
  },
});

7.8 参数校验:在边界处拒绝非法输入

校验的位置

所有外部输入都是不可信的,包括 body、query、params、headers。校验必须发生在路由处理器的最前面,并统一转成 422/400 响应。业务代码里不应该再出现 if (!req.body.title) 这类防御性判断。

// src/features/tasks/tasks.schema.js
import { z } from 'zod';

// 状态枚举集中定义,避免字符串散落各处
export const TASK_STATUSES = ['todo', 'doing', 'done'];

export const createTaskSchema = z.object({
  title: z.string().trim().min(1, '标题不能为空').max(200, '标题最多 200 字'),
  description: z.string().max(2000).optional(),
  status: z.enum(TASK_STATUSES).default('todo'),
  dueDate: z.iso.datetime({ offset: true }).optional(),   // ISO 8601 字符串
});

// 局部更新:所有字段可选,但至少要有一个字段
export const updateTaskSchema = createTaskSchema
  .partial()
  .refine((v) => Object.keys(v).length > 0, { message: '至少要提供一个待更新字段' });

export const listQuerySchema = z.object({
  // ⚠️ query 参数永远是字符串,必须 coerce
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
  status: z.enum(TASK_STATUSES).optional(),
  q: z.string().trim().max(200).optional(),
});

export const idParamSchema = z.object({
  id: z.coerce.number().int().positive(),
});
// src/utils/validate.js —— 把 zod 的校验接到 Express 上
import { HttpError } from './http-error.js';

// 校验失败时抛出带 details 的 422,交给全局错误处理器统一输出
export function validate(schemas) {
  return (req, res, next) => {
    for (const key of ['body', 'query', 'params']) {
      const schema = schemas[key];
      if (!schema) continue;
      const result = schema.safeParse(req[key]);
      if (!result.success) {
        throw new HttpError(422, 'VALIDATION_ERROR', '请求参数校验失败', result.error.issues);
      }
      // 用解析后的值覆盖原始输入:这样查询参数已变成 number、默认值已填充
      // 注意 Express 5 中 req.query 是只读 getter,改它要用 Object.defineProperty
      if (key === 'query') {
        Object.defineProperty(req, 'query', { value: result.data, writable: true, configurable: true });
      } else {
        req[key] = result.data;
      }
    }
    next();
  };
}

req.query 在 Express 5 中是只读的

Express 5 把 req.query 改成了基于 getter 的惰性属性,直接 req.query = x 会静默失败(严格模式下抛错)。上面用 Object.defineProperty 覆盖是可行的做法;另一个更干净的选择是把解析结果挂到自定义字段上,例如 req.validatedQuery = result.data,避免与框架的内部实现耦合。


八、优雅关闭(Graceful Shutdown)

8.1 为什么必须做

容器编排系统停止一个实例时,流程是:发送 SIGTERM → 等待 terminationGracePeriodSeconds(K8s 默认 30s)→ 超时则 SIGKILL。

SIGKILL 无法被捕获,进程立刻消失。如果没有优雅关闭:

  • 正在处理的请求被硬切断,客户端收到连接重置;
  • 数据库事务中途中断,可能留下不一致数据;
  • 已提交但尚未发送的响应丢失,造成"用户以为失败、实际已成功"。

优雅关闭要做的四件事

1. 收到信号后停止接受新连接(server.close(),并标记 /healthz 为不健康,让负载均衡先把流量摘走);

2. 等待在途请求完成(同时设置上限,不能无限等);

3. 关闭外部资源:数据库连接池、Redis、消息队列消费者、定时器;

4. 正常 exit(0);超时则强制 exit(1) 并记录告警。

8.2 一个可复用的实现

// src/lifecycle/shutdown.js
import { logger } from '../config/logger.js';

/**
 * 注册优雅关闭逻辑。
 * @param {object} opts
 * @param {import('node:http').Server} opts.server HTTP 服务器实例
 * @param {() => Promise<void>} opts.onClose 关闭资源(数据库、队列等)
 * @param {number} opts.timeoutMs 最长等待时间,超时强制退出
 * @param {(ready: boolean) => void} [opts.setReady] 切换健康检查状态
 */
export function registerGracefulShutdown({ server, onClose, timeoutMs, setReady }) {
  let shuttingDown = false;

  const shutdown = async (signal) => {
    // 幂等:重复收到信号(用户连按 Ctrl+C)不应重复执行
    if (shuttingDown) {
      logger.warn({ signal }, '已在关闭流程中,忽略重复信号');
      return;
    }
    shuttingDown = true;
    logger.info({ signal }, '收到退出信号,开始优雅关闭');

    // ① 先让健康检查返回 503,负载均衡会停止往这里发新请求
    setReady?.(false);

    // ④ 兜底:无论如何都要在 timeoutMs 内退出,避免被 SIGKILL
    const forceExit = setTimeout(() => {
      logger.error({ timeoutMs }, '优雅关闭超时,强制退出');
      process.exit(1);
    }, timeoutMs);
    forceExit.unref();   // 别让这个定时器自己阻止进程退出

    try {
      // ② 停止接受新连接,并等待在途请求结束
      //    Node 18.2+ 的 server.close() 返回 Promise(也可用回调形式)
      await new Promise((resolve, reject) => {
        server.close((err) => (err ? reject(err) : resolve()));
      });
      logger.info('HTTP 服务器已关闭,在途请求处理完毕');

      // ③ 关闭下游资源(连接池、缓存、消息消费者)
      await onClose();
      logger.info('下游资源已释放');

      clearTimeout(forceExit);
      logger.info('优雅关闭完成');
      process.exit(0);
    } catch (err) {
      logger.error({ err }, '优雅关闭过程中出错');
      clearTimeout(forceExit);
      process.exit(1);
    }
  };

  // SIGTERM:容器编排 / systemd / PM2 的标准停止信号
  // SIGINT:Ctrl+C
  process.on('SIGTERM', () => shutdown('SIGTERM'));
  process.on('SIGINT', () => shutdown('SIGINT'));

  // 最后防线:这些情况说明进程状态已不可信,记录后退出让编排系统重启
  process.on('uncaughtException', (err) => {
    logger.fatal({ err }, 'uncaughtException:进程状态不可信,即将退出');
    shutdown('uncaughtException');
  });
  process.on('unhandledRejection', (reason) => {
    // 忽略未处理的 Promise 拒绝会掩盖真实 Bug;Node 的默认行为会终止进程
    logger.fatal({ err: reason }, 'unhandledRejection:进程状态不可信,即将退出');
    shutdown('unhandledRejection');
  });
}

8.3 连接层面的细节:closeIdleConnections

HTTP/1.1 默认开启 keep-alive,浏览器会复用连接。server.close() 只停止接受新连接,但已建立的空闲连接会一直保持,导致 server.close() 的回调迟迟不触发。

// 完整的关闭序列:先踢掉空闲连接,再等在途请求
async function closeServer(server) {
  const closed = new Promise((resolve, reject) => {
    server.close((err) => (err ? reject(err) : resolve()));
  });

  // 主动关闭所有空闲的 keep-alive 连接,让 close() 能尽快完成
  // 注意:正在处理请求的连接不会被关闭
  server.closeIdleConnections?.();

  // 再给在途请求一点时间;仍未结束的连接说明是慢请求或客户端卡住
  // 这些连接不该无限拖住关闭流程,由外层的 timeoutMs 兜底
  return closed;
}

配合 K8s 的 preStop 钩子

K8s 发 SIGTERM 同时就从 Service 里摘除 Pod,但 iptables/ipvs 规则更新有延迟(通常几百毫秒到几秒)。这段时间新请求仍可能打到正在关闭的 Pod 上。标准做法是加一个 preStop 睡眠:

```yaml

lifecycle:

preStop:

exec:

command: ["sh", "-c", "sleep 5"]

```

让 Pod 先"拒绝新流量"5 秒,再开始真正关闭。这与优雅关闭是互补的,不是替代关系。

8.4 关闭数据库连接池

// src/db/index.js 中导出关闭函数(参见第九节的完整示例)
let pool;

export function getPool() {
  if (!pool) pool = createPool();
  return pool;
}

export async function closePool() {
  if (pool) {
    await pool.end();     // 等待已借出的连接归还并释放
    pool = undefined;
    // 注意:pool.end() 之后再 getPool() 会重建连接池
    // 所以关闭流程必须确保没有任何代码还会请求连接
  }
}

三个常见的关闭顺序错误

1. 先关连接池再关 HTTP 服务器:在途请求还在查数据库,会全部报 Cannot use a pool after calling end。顺序必须是 HTTP → 业务资源。

2. process.exit() 用得太多:process.exit() 会立刻终止,不等待 stdout/stderr 刷新完成,可能丢掉最后的日志。更好的做法是设置 process.exitCode 然后让事件循环自然结束——但优雅关闭这种场景下,为了确保在超时前退出,显式 exit() 是合理的,前提是日志已 flush。

3. 忘了关闭定时器与消费者:setInterval 轮询任务、Kafka/RabbitMQ 消费者、WebSocket 心跳,都要在 onClose 里停掉,否则进程永远不会退出,或者退出前还会消费到一半的消息。


九、完整示例:Express + SQLite 的 CRUD 服务

这是本篇的端到端示例。用 Node v24 内置的 node:sqlite,所以除了 Express 和几个中间件之外不需要任何数据库依赖,克隆下来就能跑。

9.1 目录结构

task-api/
├── package.json
├── .env.example
├── .gitignore
└── src/
    ├── index.js                     # 入口:启动服务器、注册关闭流程
    ├── app.js                       # 组装 Express 应用
    ├── config/
    │   ├── env.js                   # 环境变量校验(zod)
    │   └── logger.js                # pino 日志
    ├── db/
    │   ├── index.js                 # SQLite 连接与建表
    │   └── task-store.js            # 数据访问层
    ├── middleware/
    │   ├── error-handler.js         # 统一响应与错误结构
    │   └── require-api-key.js       # 示例鉴权
    ├── features/tasks/
    │   ├── tasks.schema.js          # zod 校验规则
    │   └── tasks.routes.js          # 路由
    └── utils/
        ├── http-error.js
        └── validate.js

9.2 package.json

{
  "name": "task-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    // Node v24 为当前 LTS;node:sqlite 需要 v22.5+(以官方最新文档为准)
    "node": ">=24.0.0"
  },
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js",
    "smoke": "node scripts/smoke.js"
  },
  "dependencies": {
    "cors": "^2.8.6",
    "dotenv": "^18.0.7",
    "express": "^5.3.0",
    "helmet": "^8.3.0",
    "pino": "^10.4.0",
    "pino-http": "^11.0.0",
    "zod": "^4.6.5"
  },
  "devDependencies": {
    "pino-pretty": "^13.0.0"
  }
}

版本说明

以上为写作时(2026-10-11)npm 上的最新版本。实际安装时用 ^ 允许小版本升级即可;升级主版本前请阅读对应迁移文档。运行 npm view express version 可以查当前最新版。

9.3 配置与日志

// src/config/env.js
import 'dotenv/config';
import { z } from 'zod';

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  HOST: z.string().default('0.0.0.0'),
  DATABASE_URL: z.string().default('./data/app.db'),
  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
  CORS_ORIGINS: z
    .string()
    .default('http://localhost:5173')
    .transform((s) => s.split(',').map((x) => x.trim()).filter(Boolean)),
  API_KEY: z.string().min(16, 'API_KEY 至少 16 个字符').default('dev-only-key-please-change'),
  SHUTDOWN_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
});

const parsed = EnvSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('❌ 环境变量校验失败,进程退出:');
  for (const issue of parsed.error.issues) {
    console.error(`   - ${issue.path.join('.') || '(根)'}: ${issue.message}`);
  }
  process.exit(1);
}

export const env = Object.freeze(parsed.data);
export const isProd = env.NODE_ENV === 'production';
// src/config/logger.js
import { pino } from 'pino';
import { env, isProd } from './env.js';

export const logger = pino({
  level: env.LOG_LEVEL,
  // 开发环境用 pino-pretty 让日志可读;生产保持 JSON 便于采集
  ...(isProd
    ? {}
    : { transport: { target: 'pino-pretty', options: { colorize: true, translateTime: 'HH:MM:ss' } } }),
  redact: {
    paths: ['req.headers.authorization', 'req.headers.cookie', 'req.headers["x-api-key"]'],
    censor: '[已脱敏]',
  },
});

9.4 数据访问层

// src/db/index.js
import { DatabaseSync } from 'node:sqlite';
import { mkdirSync } from 'node:fs';
import path from 'node:path';
import { env, isProd } from '../config/env.js';
import { logger } from '../config/logger.js';

let db;

export function getDb() {
  if (db) return db;

  if (env.DATABASE_URL !== ':memory:') {
    // 确保目录存在,否则 SQLite 打开失败
    mkdirSync(path.dirname(env.DATABASE_URL), { recursive: true });
  }

  db = new DatabaseSync(env.DATABASE_URL);

  // WAL 模式让读写并发更好;外键约束默认关闭,必须显式打开
  db.exec('PRAGMA journal_mode = WAL;');
  db.exec('PRAGMA foreign_keys = ON;');

  db.exec(`
    CREATE TABLE IF NOT EXISTS tasks (
      id          INTEGER PRIMARY KEY AUTOINCREMENT,
      title       TEXT    NOT NULL,
      description TEXT,
      status      TEXT    NOT NULL DEFAULT 'todo'
                          CHECK (status IN ('todo','doing','done')),
      due_date    TEXT,
      created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
      updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
    );
    CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
  `);

  logger.info({ url: env.DATABASE_URL, prod: isProd }, '数据库已就绪');
  return db;
}

export function closeDb() {
  if (db) {
    db.close();
    db = undefined;
  }
}
// src/db/task-store.js
import { getDb } from './index.js';

// 数据库行(snake_case)→ API 输出(camelCase)的映射集中在这里
function toTask(row) {
  return {
    id: row.id,
    title: row.title,
    description: row.description ?? null,
    status: row.status,
    dueDate: row.due_date ?? null,
    createdAt: row.created_at,
    updatedAt: row.updated_at,
  };
}

export const taskStore = {
  list({ page, pageSize, status, q }) {
    const where = [];
    const params = {};
    if (status) { where.push('status = :status'); params.status = status; }
    if (q) { where.push('title LIKE :q'); params.q = `%${q}%`; }
    const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';

    const db = getDb();
    // 总数与分页数据分两次查;数据量再大时应换成游标分页
    const { total } = db
      .prepare(`SELECT COUNT(*) AS total FROM tasks ${whereSql}`)
      .get(params);

    const rows = db
      .prepare(
        `SELECT * FROM tasks ${whereSql}
         ORDER BY id DESC
         LIMIT :limit OFFSET :offset`,
      )
      .all({ ...params, limit: pageSize, offset: (page - 1) * pageSize });

    return { items: rows.map(toTask), total, page, pageSize };
  },

  get(id) {
    const row = getDb().prepare('SELECT * FROM tasks WHERE id = ?').get(id);
    return row ? toTask(row) : null;
  },

  create(input) {
    const db = getDb();
    // lastInsertRowid 可能是 BigInt,转成 Number 才能进 JSON
    const { lastInsertRowid } = db
      .prepare(
        `INSERT INTO tasks (title, description, status, due_date)
         VALUES (:title, :description, :status, :dueDate)`,
      )
      .run({
        title: input.title,
        description: input.description ?? null,
        status: input.status,
        dueDate: input.dueDate ?? null,
      });
    return this.get(Number(lastInsertRowid));
  },

  update(id, patch) {
    const current = this.get(id);
    if (!current) return null;

    // 只更新传入的字段;COALESCE 在这里不好用,因为 null 是合法值
    const next = { ...current, ...patch };
    getDb()
      .prepare(
        `UPDATE tasks
            SET title = :title,
                description = :description,
                status = :status,
                due_date = :dueDate,
                updated_at = datetime('now')
          WHERE id = :id`,
      )
      .run({
        id,
        title: next.title,
        description: next.description ?? null,
        status: next.status,
        dueDate: next.dueDate ?? null,
      });
    return this.get(id);
  },

  remove(id) {
    const { changes } = getDb().prepare('DELETE FROM tasks WHERE id = ?').run(id);
    return changes > 0;      // changes 是 BigInt 或 number,> 0 比较是安全的
  },
};

node:sqlite 的定位

node:sqlite 是 Node 内置的同步 SQLite 绑定,非常适合示例、CLI 工具、边缘场景与测试。它是同步 API——这意味着查询会阻塞事件循环。对本地文件上的小查询通常可接受,但高并发生产服务应使用 pg(PostgreSQL)配合连接池,参见 后端-05-数据库操作与ORM。版本支持情况以官方文档为准。

9.5 校验与错误处理

// src/utils/http-error.js
// 带 HTTP 语义的错误基类:业务代码只管 throw,序列化交给错误处理器
export class HttpError extends Error {
  constructor(status, code, message, details) {
    super(message);
    this.name = 'HttpError';
    this.status = status;
    this.code = code;
    if (details) this.details = details;
    Error.captureStackTrace?.(this, HttpError);
  }
}
// src/features/tasks/tasks.schema.js
import { z } from 'zod';

export const TASK_STATUSES = ['todo', 'doing', 'done'];

export const createTaskSchema = z.object({
  title: z.string().trim().min(1, '标题不能为空').max(200, '标题最长 200 字'),
  description: z.string().max(2000, '描述最长 2000 字').optional(),
  status: z.enum(TASK_STATUSES).default('todo'),
  dueDate: z.iso.datetime({ offset: true }).optional(),
});

export const updateTaskSchema = createTaskSchema
  .partial()
  .refine((v) => Object.keys(v).length > 0, { message: '至少要提供一个待更新字段' });

export const listQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
  status: z.enum(TASK_STATUSES).optional(),
  q: z.string().trim().max(200).optional(),
});

export const idParamSchema = z.object({
  id: z.coerce.number().int().positive('id 必须是正整数'),
});
// src/utils/validate.js
import { HttpError } from './http-error.js';

export function validate(schemas) {
  return (req, _res, next) => {
    for (const key of ['body', 'query', 'params']) {
      const schema = schemas[key];
      if (!schema) continue;

      const result = schema.safeParse(req[key]);
      if (!result.success) {
        throw new HttpError(422, 'VALIDATION_ERROR', '请求参数校验失败', result.error.issues);
      }

      // req.query 在 Express 5 中是只读 getter,需要 defineProperty 覆盖
      if (key === 'query') {
        Object.defineProperty(req, 'query', {
          value: result.data,
          writable: true,
          configurable: true,
          enumerable: true,
        });
      } else {
        req[key] = result.data;
      }
    }
    next();
  };
}
// src/middleware/error-handler.js
import { randomUUID } from 'node:crypto';
import { ZodError } from 'zod';
import { isProd } from '../config/env.js';
import { logger } from '../config/logger.js';
import { HttpError } from '../utils/http-error.js';

// 统一成功响应结构,让前端只需要写一套解析逻辑
export function ok(res, data, status = 200) {
  return res.status(status).json({ success: true, data });
}

// 404 兜底:所有路由都没匹配上时到这里
export function notFoundHandler(req, res) {
  res.status(404).json({
    success: false,
    error: {
      code: 'NOT_FOUND',
      message: `找不到路由 ${req.method} ${req.originalUrl}`,
      requestId: req.id,
    },
  });
}

// 全局错误处理器:⚠️ 必须四个参数,Express 靠 fn.length === 4 识别
export function errorHandler(err, req, res, next) {
  // 响应已经开始发送(例如流式响应中途出错)就无法再改状态码
  // 交还给 Express 默认处理器去销毁这个 socket
  if (res.headersSent) return next(err);

  const requestId = req.id ?? randomUUID();
  let status = 500;
  let code = 'INTERNAL_ERROR';
  let message = '服务器内部错误';
  let details;

  if (err instanceof ZodError) {
    // 兜底:如果某个处理器忘了用 validate 中间件,zod 错误也不会变成 500
    status = 422;
    code = 'VALIDATION_ERROR';
    message = '请求参数校验失败';
    details = err.issues;
  } else if (err instanceof HttpError || Number.isInteger(err?.status)) {
    status = err.status;
    code = err.code ?? 'BAD_REQUEST';
    message = err.message;
    details = err.details;
  } else if (err?.type === 'entity.too.large') {
    // body-parser 抛出的超限错误
    status = 413;
    code = 'PAYLOAD_TOO_LARGE';
    message = '请求体过大';
  } else if (err?.type === 'entity.parse.failed') {
    status = 400;
    code = 'INVALID_JSON';
    message = '请求体不是合法 JSON';
  }

  const isServerError = status >= 500;
  const logPayload = { err, requestId, status, method: req.method, url: req.originalUrl };

  if (isServerError) logger.error(logPayload, '服务端错误');
  else logger.warn({ ...logPayload, err: undefined, reason: err?.message }, '客户端错误');

  res.status(status).json({
    success: false,
    error: {
      code,
      message,
      ...(details ? { details } : {}),
      requestId,
      // 堆栈只在非生产环境暴露;生产环境靠 requestId 去日志里查
      ...(isServerError && !isProd && err?.stack ? { stack: err.stack } : {}),
    },
  });
}
// src/middleware/require-api-key.js
import { timingSafeEqual } from 'node:crypto';
import { env } from '../config/env.js';
import { HttpError } from '../utils/http-error.js';

// 演示用的极简鉴权。真实项目请用 JWT / Session,见 [[后端-06-认证与授权]]
export function requireApiKey(req, _res, next) {
  const provided = req.get('x-api-key');
  if (!provided) {
    throw new HttpError(401, 'UNAUTHORIZED', '缺少 x-api-key 请求头');
  }

  const a = Buffer.from(provided);
  const b = Buffer.from(env.API_KEY);
  // 长度不同时 timingSafeEqual 会抛错,必须先比长度
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    throw new HttpError(401, 'UNAUTHORIZED', 'API Key 不正确');
  }
  next();
}

9.6 路由

// src/features/tasks/tasks.routes.js
import { Router } from 'express';
import { taskStore } from '../../db/task-store.js';
import { HttpError } from '../../utils/http-error.js';
import { validate } from '../../utils/validate.js';
import { ok } from '../../middleware/error-handler.js';
import {
  createTaskSchema,
  idParamSchema,
  listQuerySchema,
  updateTaskSchema,
} from './tasks.schema.js';

const router = Router();

// GET /api/tasks?page=1&pageSize=20&status=todo&q=报告
router.get('/', validate({ query: listQuerySchema }), (req, res) => {
  // 注意:这里 req.query 已被 validate 替换为解析后的对象
  const result = taskStore.list(req.query);
  return ok(res, result);
});

router.get('/:id', validate({ params: idParamSchema }), (req, res) => {
  const task = taskStore.get(req.params.id);
  if (!task) throw new HttpError(404, 'TASK_NOT_FOUND', '任务不存在');
  return ok(res, task);
});

router.post('/', validate({ body: createTaskSchema }), (req, res) => {
  const task = taskStore.create(req.body);
  // 201 + Location 是 REST 惯例,见 [[后端-01-HTTP与RESTfulAPI设计]]
  res.setHeader('Location', `/api/tasks/${task.id}`);
  return ok(res, task, 201);
});

router.patch('/:id', validate({ params: idParamSchema, body: updateTaskSchema }), (req, res) => {
  const updated = taskStore.update(req.params.id, req.body);
  if (!updated) throw new HttpError(404, 'TASK_NOT_FOUND', '任务不存在');
  return ok(res, updated);
});

router.delete('/:id', validate({ params: idParamSchema }), (req, res) => {
  const removed = taskStore.remove(req.params.id);
  if (!removed) throw new HttpError(404, 'TASK_NOT_FOUND', '任务不存在');
  // 204 不能带响应体,所以这里不用 ok()
  return res.status(204).end();
});

export default router;

9.7 组装应用

// src/app.js
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import { randomUUID } from 'node:crypto';
import pinoHttp from 'pino-http';

import { env, isProd } from './config/env.js';
import { logger } from './config/logger.js';
import tasksRouter from './features/tasks/tasks.routes.js';
import { requireApiKey } from './middleware/require-api-key.js';
import { errorHandler, notFoundHandler } from './middleware/error-handler.js';

export function createApp() {
  const app = express();

  // 反向代理后面才需要;设成 1 表示信任第一层代理的 X-Forwarded-* 头
  // 不设它的话 req.ip 永远是代理的 IP,限流会误伤所有人
  app.set('trust proxy', 1);
  app.disable('x-powered-by');       // 减少指纹信息,helmet 也会移除它

  // ① 安全响应头:越早越好
  app.use(helmet());

  // ② 请求日志:放在最前面,这样连 CORS 失败的请求也能被记录
  app.use(
    pinoHttp({
      logger,
      genReqId: (req, res) => {
        const id = req.headers['x-request-id'] ?? randomUUID();
        res.setHeader('x-request-id', id);
        return id;
      },
      customLogLevel: (_req, res, err) =>
        err || res.statusCode >= 500 ? 'error' : res.statusCode >= 400 ? 'warn' : 'info',
    }),
  );

  // ③ CORS:白名单模式
  app.use(
    cors({
      origin(origin, callback) {
        if (!origin) return callback(null, true);              // 同源 / curl
        if (env.CORS_ORIGINS.includes(origin)) return callback(null, true);
        return callback(new Error(`CORS 不允许的来源:${origin}`));
      },
      credentials: true,
      methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'],
      allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
      maxAge: 86_400,
    }),
  );

  // ④ 健康检查:必须在鉴权和 body 解析之前,且要轻量
  //    编排系统靠它判断实例是否就绪
  let ready = true;
  app.get('/healthz', (_req, res) => {
    res.status(ready ? 200 : 503).json({ status: ready ? 'ok' : 'shutting_down' });
  });

  // ⑤ body 解析:带体积上限;放在鉴权之后能少挨一点攻击
  app.use(express.json({ limit: '1mb' }));

  // ⑥ 业务路由(示例中全部需要 API Key)
  app.use('/api/tasks', requireApiKey, tasksRouter);

  // ⑦ 404 与全局错误处理器必须最后注册
  app.use(notFoundHandler);
  app.use(errorHandler);

  // 把 ready 开关暴露给关闭流程
  app.locals.setReady = (value) => { ready = value; };

  return app;
}

9.8 入口与启动

// src/index.js
import { createApp } from './app.js';
import { env } from './config/env.js';
import { logger } from './config/logger.js';
import { getDb, closeDb } from './db/index.js';
import { registerGracefulShutdown } from './lifecycle/shutdown.js';

// 启动前先建表;失败则进程退出,不要带着坏配置对外服务
getDb();

const app = createApp();
const server = app.listen(env.PORT, env.HOST, () => {
  logger.info({ host: env.HOST, port: env.PORT, env: env.NODE_ENV }, '🚀 服务已启动');
});

// 保持连接超时与上游反向代理协调,避免偶发 502
server.keepAliveTimeout = 65_000;
server.headersTimeout = 66_000;

registerGracefulShutdown({
  server,
  setReady: app.locals.setReady,
  timeoutMs: env.SHUTDOWN_TIMEOUT_MS,
  async onClose() {
    closeDb();                 // 顺序:先 HTTP,后数据库
    logger.info('数据库连接已关闭');
  },
});

9.9 .env.example 与 .gitignore

# .env.example —— 提交到仓库;复制成 .env 后填真实值
NODE_ENV=development
PORT=3000
HOST=0.0.0.0
DATABASE_URL=./data/app.db
LOG_LEVEL=debug
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
API_KEY=dev-only-key-please-change
SHUTDOWN_TIMEOUT_MS=10000
node_modules/
data/
.env
.env.*.local
*.log

9.10 启动与验证

# 1. 安装依赖(Node v24 LTS)
node -v                      # 应为 v24.x
npm install

# 2. 准备环境变量
cp .env.example .env         # Windows PowerShell: Copy-Item .env.example .env

# 3. 启动
npm run dev                  # 开发模式,node --watch 自动重启
# 或 npm start               # 生产式启动(不带 watch)
# 4. 用 curl 走一遍 CRUD(Windows 上可用 Git Bash 或 WSL)

# 创建
curl -s -X POST http://localhost:3000/api/tasks \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: dev-only-key-please-change' \
  -d '{"title":"写 Node 笔记","status":"doing"}'
# → {"success":true,"data":{"id":1,"title":"写 Node 笔记",...,"status":"doing",...}}

# 列表 + 过滤 + 分页
curl -s 'http://localhost:3000/api/tasks?status=doing&page=1&pageSize=10' \
  -H 'x-api-key: dev-only-key-please-change'

# 单项
curl -s http://localhost:3000/api/tasks/1 -H 'x-api-key: dev-only-key-please-change'

# 局部更新
curl -s -X PATCH http://localhost:3000/api/tasks/1 \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: dev-only-key-please-change' \
  -d '{"status":"done"}'

# 删除(期望 204,无响应体)
curl -s -i -X DELETE http://localhost:3000/api/tasks/1 \
  -H 'x-api-key: dev-only-key-please-change'

# —— 验证错误处理 ——
# 校验失败 → 422
curl -s -X POST http://localhost:3000/api/tasks \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: dev-only-key-please-change' -d '{"title":""}'
# → {"success":false,"error":{"code":"VALIDATION_ERROR","message":"请求参数校验失败","details":[...]}}

# 缺 API Key → 401
curl -s -X POST http://localhost:3000/api/tasks \
  -H 'Content-Type: application/json' -d '{"title":"x"}'

# 不存在的路由 → 404
curl -s http://localhost:3000/api/nope -H 'x-api-key: dev-only-key-please-change'

# 畸形 JSON → 400 INVALID_JSON
curl -s -X POST http://localhost:3000/api/tasks \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: dev-only-key-please-change' -d '{bad json'

# 健康检查
curl -s http://localhost:3000/healthz
# 5. 验证优雅关闭
# 在服务运行时按 Ctrl+C(等同 SIGINT),观察日志顺序:
#   收到退出信号,开始优雅关闭
#   HTTP 服务器已关闭,在途请求处理完毕
#   数据库连接已关闭
#   优雅关闭完成

为什么这个示例"完整"

它包含了一个可上生产的 Node 服务需要的骨架:配置校验、结构化日志、统一响应与错误结构、输入校验、CORS 白名单、安全头、健康检查、优雅关闭。你可以把这个目录当作模板,替换 features/tasks 为自己的业务模块。


十、进程管理:为什么不能直接 node app.js

10.1 node app.js 的四个致命问题

问题后果
只用到一个 CPU 核16 核机器上你的服务只用 1/16 的算力
崩溃不重启一个未捕获异常 → 进程退出 → 服务永久下线
不处理信号收到 SIGTERM 直接被默认行为杀死,无法优雅关闭
无日志与监控stdout 随终端关闭而丢失,OOM 后没有任何记录

10.2 三种方案对比

方案多核利用崩溃重启日志适用场景
PM2✅ cluster 模式✅ 自动重启✅ 内置轮转单机部署、传统 VPS
systemd⚠️ 需配多个 service 或用模板✅ Restart=always✅ journaldLinux 服务器、系统级托管
cluster 模块✅ 自己在代码里做❌ 需自己实现无学习原理 / 特殊需求
容器编排(K8s)✅ 加副本数✅ 探针 + 重启策略采集 stdout现代云原生部署

关键取舍:容器里不要再套一层进程管理器

在 Docker/K8s 里,每个容器只跑一个 Node 进程,横向扩展交给副本数(replicas)或 docker compose --scale。原因:

- 反模式:CMD pm2-runtime start app.js -i 4 让一个容器跑 4 个进程。K8s 的资源限制(CPU limit)会影响全部 4 个进程,CPU throttling 时互相拖累;日志混在一起难以归因;扩缩容粒度变成 4 倍。

- 正确做法:CMD ["node", "src/index.js"],副本数 = 期望的进程数。让编排器做它擅长的事。

唯一例外:如果容器只做 CPU 限流而没有副本机制(例如单容器部署),用 cluster 或 pm2 -i 榨满配额仍有意义。交叉引用:后端-07-Docker与容器化。

10.3 PM2

npm install -g pm2

# 以 cluster 模式启动,自动使用所有 CPU 核
pm2 start src/index.js --name task-api -i max

# 常用命令
pm2 list                 # 查看所有进程
pm2 logs task-api        # 实时日志
pm2 monit                # 资源监控面板
pm2 reload task-api      # 零停机重载(逐个重启 worker)
pm2 delete task-api

# 生成开机自启脚本
pm2 startup
pm2 save
// ecosystem.config.cjs —— PM2 配置文件(用 .cjs 因为 PM2 默认按 CJS 加载)
module.exports = {
  apps: [
    {
      name: 'task-api',
      script: 'src/index.js',
      instances: 'max',            // 或用具体数字,通常等于 CPU 核数
      exec_mode: 'cluster',
      max_memory_restart: '512M',  // 超过就重启,缓解内存泄漏
      // 优雅关闭:PM2 发 SIGINT,等待这么久后 SIGKILL
      kill_timeout: 12_000,
      wait_ready: true,            // 配合 process.send('ready') 使用
      listen_timeout: 10_000,
      env: { NODE_ENV: 'production', PORT: 3000 },
      error_file: './logs/error.log',
      out_file: './logs/out.log',
      merge_logs: true,
      time: true,
    },
  ],
};

PM2 的 wait_ready 需要你在代码里配合

设置 wait_ready: true 后,PM2 会一直等到你显式调用 process.send('ready') 才认为启动成功。这件事必须写在 server.listen 回调里,否则 pm2 reload 会超时失败:

```js

server.listen(env.PORT, env.HOST, () => {

logger.info('服务已启动');

process.send?.('ready'); // 只有被 PM2 拉起时才存在 process.send

});

```

10.4 systemd

# /etc/systemd/system/task-api.service
[Unit]
Description=Task API (Node.js)
After=network.target

[Service]
Type=simple
# 不要用 root 运行;提前创建专用用户
User=taskapi
WorkingDirectory=/srv/task-api
# 环境变量从文件读,避免密钥出现在 ps 输出里
EnvironmentFile=/srv/task-api/.env
# 用绝对路径的 node,或让 ExecStart 指向 npm
ExecStart=/usr/bin/node src/index.js
Restart=always
RestartSec=3
# 日志进 journald,用 journalctl -u task-api 查看
StandardOutput=journal
StandardError=journal

# —— 安全加固(按需放开)——
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/task-api/data

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now task-api
journalctl -u task-api -f          # 跟踪日志
sudo systemctl restart task-api

systemd 与多核

systemd 的一个 service 对应一个进程,不会自动帮你用满多核。要用满核有两种做法:① 用 systemd 模板单元(task-api@.service)启动 N 个实例并各占一个端口,前置 Nginx 做负载均衡;② 在应用内用 cluster 模块,systemd 只托管 master 进程。

10.5 cluster 模块:原理与注意事项

cluster 让多个子进程共享同一个监听端口。主进程(primary)创建监听 socket 后,把文件描述符传给 worker,由操作系统内核做负载均衡(Linux 上默认是 round-robin 风格的分发)。

// cluster-server.mjs —— 主进程负责调度与重启,worker 跑 Express
import cluster from 'node:cluster';
import os from 'node:os';
import process from 'node:process';
import { createApp } from './src/app.js';
import { env } from './src/config/env.js';
import { logger } from './src/config/logger.js';

const WORKERS = Number(process.env.WEB_CONCURRENCY) || os.cpus().length;

if (cluster.isPrimary) {
  logger.info({ workers: WORKERS }, '主进程启动');

  for (let i = 0; i < WORKERS; i++) cluster.fork();

  // worker 意外退出时补一个,保持进程数稳定
  cluster.on('exit', (worker, code, signal) => {
    logger.error({ pid: worker.process.pid, code, signal }, 'worker 退出,正在补充');
    if (!worker.exitedAfterDisconnect) cluster.fork();
  });

  // 收到 SIGTERM 时先通知所有 worker 优雅关闭
  process.on('SIGTERM', () => {
    logger.info('主进程收到 SIGTERM,通知所有 worker');
    for (const worker of Object.values(cluster.workers)) {
      worker.process.kill('SIGTERM');
    }
  });
} else {
  // —— worker 进程 ——
  const app = createApp();
  const server = app.listen(env.PORT, () => {
    logger.info({ pid: process.pid }, 'worker 已就绪');
  });

  process.on('SIGTERM', () => {
    server.close(() => process.exit(0));
  });
}

cluster 的四个陷阱

1. 进程间不共享内存。你在 worker 里写的 const cache = new Map() 每个 worker 一份,缓存命中率下降到 。要共享状态必须用 Redis 或外部存储。

2. 限流会失效。基于内存的 express-rate-limit 在 4 个 worker 下等于把限额放大 4 倍。要用 Redis 存储计数(有对应的 store 适配器)。

3. 定时任务会重复执行。每个 worker 都会跑 setInterval,导致同一任务执行 N 次。定时任务应该单独跑一个进程,或用分布式锁。

4. 主进程是单点。主进程崩溃则全部 worker 一起消失,需要 PM2/systemd/K8s 在外层兜底。

另外,Node 现在也提供了同一个进程内利用多核的能力:worker_threads + 每个线程一个 HTTP server,配合 SO_REUSEPORT(reusePort: true)也能实现负载均衡,且内存共享更容易。选型以官方最新文档与压测结果为准。


十一、性能与排查

11.1 用 --inspect 调试

# 启动时开启调试器(默认监听 127.0.0.1:9229)
node --inspect src/index.js

# 在入口第一行就暂停,等你连上再继续(调试启动逻辑必备)
node --inspect-brk src/index.js

# 只监听指定端口
node --inspect=0.0.0.0:9229 src/index.js   # ⚠️ 暴露到公网极其危险

打开 Chrome / Edge,访问 chrome://inspect → Configure 填 localhost:9229 → 点击 "inspect"。你会得到和前端一样的 DevTools:断点、单步、作用域查看、调用栈、Memory 面板的堆快照、Performance 面板的火焰图。

# 只查看调试端点信息,不进入调试会话
curl http://127.0.0.1:9229/json/list

绝不要把 --inspect 暴露到公网

调试端口没有任何认证,连接上就能执行任意代码。容器里启用调试必须绑定 127.0.0.1 并通过端口转发访问(kubectl port-forward),绝不能监听 0.0.0.0。

11.2 火焰图与性能分析

# ① 用 Node 内置的 CPU profiler(零依赖)
node --cpu-prof --cpu-prof-dir=./profiles src/index.js
# 停止进程后,profiles/ 下会生成 .cpuprofile 文件
# 用 Chrome DevTools 的 Performance 面板 "Load profile" 打开它
# ② 用 autocannon 施加真实负载
npx autocannon -c 100 -d 30 http://localhost:3000/healthz

# ③ clinic.js 三件套:一键定位瓶颈类型
npm i -g clinic
clinic doctor -- node src/index.js     # 先判断是被 CPU、I/O 还是 GC 拖住
clinic flame  -- node src/index.js     # 火焰图:谁在占用 CPU(宽 = 耗时多)
clinic bubbleprof -- node src/index.js # 异步操作气泡图:谁在等待

怎么读火焰图:

现象含义对策
某一帧特别宽该函数占用大量 CPU优化算法、加缓存、丢给 worker
出现很高的"塔"深递归或过度抽象检查递归、减少中间层
(garbage collector) 占比高GC 压力大,可能内存分配过频减少临时对象、复用 Buffer、调 --max-old-space-size
(idle) 占比高CPU 没吃满,瓶颈在别处看 bubbleprof,多半是 I/O 或下游依赖
JSON.parse/stringify 宽序列化开销大精简响应体、分页、流式输出
# ④ 直接观察事件循环是否被阻塞(Node 内置,无需装包)
node -e "
const { monitorEventLoopDelay } = require('node:perf_hooks');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
setInterval(() => {
  // p99 超过几十毫秒说明有同步阻塞或 CPU 饱和
  console.log('事件循环延迟 p99:', (h.percentile(99) / 1e6).toFixed(2), 'ms');
}, 2000);
"

11.3 内存泄漏的三大来源

Node 的内存泄漏通常不是"忘了 free",而是"有东西一直持有引用"。三大来源:

① 全局缓存无上限

// ❌ 典型的泄漏:键随时间无限增长,永不释放
const cache = new Map();
app.get('/user/:id', (req, res) => {
  cache.set(req.params.id, fetchUser(req.params.id));   // 只增不减
});

// ✅ 修法 A:LRU + 容量上限(用 lru-cache 库)
import { LRUCache } from 'lru-cache';
const cache = new LRUCache({ max: 5000, ttl: 1000 * 60 * 5 });

// ✅ 修法 B:手写 TTL 清理,并在关闭流程里 clearInterval
const ttlCache = new Map();
const sweeper = setInterval(() => {
  const now = Date.now();
  for (const [k, v] of ttlCache) if (v.expiresAt < now) ttlCache.delete(k);
}, 60_000);
sweeper.unref();   // 不阻止进程退出

② 监听器未移除

// ❌ 每个请求都往同一个 emitter 上挂监听器 → 累积到内存爆炸
//    还会触发 MaxListenersExceededWarning
app.get('/x', (req, res) => {
  process.on('some-event', handler);   // 永不移除
});

// ✅ 用 once 自动移除
process.once('some-event', handler);

// ✅ 或成对使用,并在 res 结束时清理
const onTick = () => { /* ... */ };
emitter.on('tick', onTick);
res.on('close', () => emitter.off('tick', onTick));

// ✅ 长生命周期的 EventEmitter 定期自检
if (emitter.listenerCount('tick') > 50) logger.warn('tick 监听器过多,疑似泄漏');

③ 闭包持有大对象

// ❌ 闭包捕获了 10MB 的 buffer,只要 handler 活着,buffer 就不会被 GC
function makeHandler() {
  const bigBuffer = Buffer.alloc(10 * 1024 * 1024);
  return (req, res) => {
    // 其实只用到 bigBuffer.length,却把整个 buffer 留在了闭包里
    res.end(String(bigBuffer.length));
  };
}
app.use(makeHandler());   // 泄漏:一个永久存活的中间件

// ✅ 只把需要的数据带进闭包
function makeHandler() {
  const size = Buffer.alloc(10 * 1024 * 1024).length;   // 临时对象可被回收
  return (req, res) => res.end(String(size));
}

排查流程:

# ① 打堆快照:可以在运行时按需生成,不需要重启
#    用 SIGUSR2 触发(需在代码里监听),或直接在 DevTools 里点 "Take snapshot"
kill -USR2 <pid>
// 代码中按需导出堆快照
import { writeHeapSnapshot } from 'node:v8';
import { gzipSync } from 'node:zlib';
import { writeFileSync } from 'node:fs';

app.get('/debug/heap', (req, res) => {
  // ⚠️ 必须严格鉴权 + 限流:生成快照会阻塞事件循环数秒
  const file = writeHeapSnapshot();
  res.json({ file });
});

对比快照找泄漏

1. 服务启动、压测稳定后,取快照 A;

2. 持续跑 30 分钟或 10 万请求,强制 GC(DevTools 的垃圾桶图标)后取快照 B;

3. 在 DevTools 的 Comparison 视图里比较 A → B,按 # Delta 排序;

4. 增长最多的构造函数就是嫌疑对象,展开看 Retainers(谁在持有它),顺着引用链就能找到泄漏点。

三个高频元凶:未清理的 Map/数组、EventEmitter 上堆积的监听器、setInterval 里被闭包捕获的大对象。

11.4 其他实用手段

需求手段
查看 GC 活动node --trace-gc,或 perf_hooks 的 PerformanceObserver 监听 'gc'
增大堆上限node --max-old-space-size=4096(单位 MB);容器里必须与内存 limit 匹配
排查句柄泄漏process._getActiveHandles() / _getActiveRequests()(非公开 API,仅调试用)
检查启动耗时node --cpu-prof 抓启动阶段,或用 --trace-require-module 看模块加载时间
依赖体积npx cost-of-modules、npx depcheck 找无用依赖
诊断报告node --report-on-signal --report-signal=SIGUSR2,或 process.report.writeReport()

十二、注意事项与常见坑

Node.js 层面

1. 同步 API 是毒药。fs.Sync、crypto.Sync、JSON.parse 大字符串、大数组 .sort()、bcrypt.hashSync —— 任何一个用在高频路径上都会拖垮整个服务。开发时用同步版图方便,上线前必须全部换掉。

2. await 写在循环里会串行化。for (const id of ids) await fetch(id) 是顺序执行的,N 个请求耗时 N 倍。用 Promise.all(ids.map(fetch)) 并行;但要限制并发数(p-limit),否则会打爆下游。

3. 忘记 await 会静默失败。saveUser(user) 少了 await,报错不会抛到你这里,而是变成 unhandledRejection。开启 ESLint 的 @typescript-eslint/no-floating-promises 规则能自动发现。

4. process.env 全是字符串。if (process.env.DEBUG) 在 DEBUG=false 时依然为真。

5. UV_THREADPOOL_SIZE 只有 4。大量文件/DNS/密码哈希并发时会是瓶颈,且症状是"变慢"而不是"报错",很难定位。

6. 相对路径依赖 process.cwd()。readFile('./config.json') 读的是启动目录,不是脚本目录。用 import.meta.dirname 或 path.resolve 构造绝对路径。

Express 层面

7. 错误处理中间件必须四个参数,且必须最后注册。放在路由之前不会生效,少一个参数就退化成普通中间件。

8. async 处理器抛错的版本差异(详见 7.6):Express 5 会自动转发返回的 Promise 的 reject;Express 4 不会,需要 asyncHandler 或 express-async-errors。无论哪个版本,忘了 return 的 Promise 和回调里的 throw 都不会被捕获。

9. 中间件里既没 next() 也没结束响应 → 请求永远挂起,客户端一直转圈直到超时。加一个全局超时中间件能兜住。

10. next(err) 之后又写响应 → ERR_HTTP_HEADERS_SENT。判断 res.headersSent。

11. express.json() 挂载位置:应在限流/鉴权之后;忘记挂载则 req.body 是 undefined(Express 5),解构会抛 TypeError。

12. **CORS origin: '*' 与 credentials: true 不能共存;且 CORS 不是**安全边界。

13. req.query 在 Express 5 中只读,req.query = x 无效。

14. Express 5 的路由语法基于 path-to-regexp v8,通配符写法与 v4 不同(如 需改为具名形式 /splat),? 可选参数语法也有变化。从 v4 升级前务必读官方迁移指南(见参考来源)。

生产部署层面

15. node app.js 不是生产启动方式(见第十节)。

16. --watch / --reload 绝不能用于生产。它会监听文件并重启进程,导致:重启期间请求失败、内存翻倍、信号处理被干扰、容器里 inotify 句柄耗尽。

17. 优雅关闭的顺序是 HTTP → 资源,反了会在途请求全部 500。

18. keepAliveTimeout 必须略大于上游代理,否则偶发 502/socket hang up。

19. trust proxy 不设会导致 req.ip 错误,让基于 IP 的限流和白名单失效。

20. 容器里 --max-old-space-size 要小于内存 limit,否则被 OOM Killer 干掉且没有堆栈。留 20–30% 给堆外内存(Buffer、libuv、V8 自身开销)。


十三、练习题

  1. (基础·事件循环顺序) 不运行代码,写出下面程序的输出顺序,然后运行验证。若输出与你预期不同,解释原因。

```js

setTimeout(() => console.log('A'), 0);

setImmediate(() => console.log('B'));

process.nextTick(() => console.log('C'));

Promise.resolve().then(() => console.log('D'));

console.log('E');

```

  1. (基础·模块系统) 把一个使用 __dirname、require、require.main === module 的 CommonJS 文件改写成 ESM,用 import.meta.dirname、import.meta.main 和 await import() 替换。写出改后的完整代码,并说明 package.json 需要改什么。
  1. (进阶·中间件执行顺序) 下面的中间件链有什么问题?请指出会发生什么、以及如何修正。

```js

app.use(express.json());

app.post('/api/items', (req, res) => { res.json({ ok: true }); });

app.use((err, req, res) => { res.status(500).json({ message: err.message }); });

app.use('/api/items', itemsRouter);

```

  1. (进阶·阻塞事件循环) 你的服务有个 /report 接口需要把 20 万行数据聚合成 CSV。当前实现用同步字符串拼接并在主线程完成,压测发现所有接口的 P99 从 30ms 涨到 8s。请给出至少两种改造方案,并用代码说明其中一种(提示:worker_threads 与 stream 的区别在于——前者解决 CPU 占用,后者解决内存占用)。
  1. (进阶·优雅关闭) 为下面这个不完整的关闭逻辑找出所有缺陷,并写出正确版本:

```js

process.on('SIGTERM', () => {

pool.end().then(() => server.close());

process.exit(0);

});

```

  1. (思考题) 你的团队要把一个 Node 服务从"单机 PM2 起 4 个 cluster worker"迁移到 Kubernetes。请列出至少四项必须修改的内容(涉及:多核策略、内存限制、配置注入、日志、健康检查、优雅关闭),并解释每一项如果不改会导致什么具体故障。

十四、常见问题(FAQ)

Q1:Node.js 是单线程的,那它怎么做到高并发?既然只有一个线程,为什么比多线程的 PHP/Apache 还快?

A:准确说法是"执行 JavaScript 的线程只有一个"。高并发的关键在于:处理一个请求的时间大部分花在等待 I/O(数据库、下游 API、磁盘),而不是计算。传统模型里,等待会占住一个线程;Node 里等待是"注册回调后立刻返回",主线程继续处理下一个请求。

所以瓶颈不是"线程数",而是"主线程被计算占用的总时长"。设单请求平均等待 、CPU 时间 ,则:

一个 的接口,理论上限约 1000 QPS(单核);如果 里有 0.9ms 是同步计算,那这 0.9ms 就是纯粹的天花板。这也解释了为什么 Node 特别适合"IO 密集 + 逻辑轻"的 API 网关,而不适合做计算。

Q2:我应该学 Express 5 还是 Express 4?现有的 Express 4 项目要升级吗?

A:新项目直接用 Express 5。它的最大收益是 async 处理器返回的 Promise 会被自动处理,解决了困扰 Express 用户十年的错误捕获问题;安全响应头方面 helmet 也已适配。

存量项目不要为了升级而升级。Express 5 有一批破坏性变更(app.del() 移除、req.param() 移除、路径语法基于 path-to-regexp v8、req.query 只读、res.json(obj, status) 签名移除等),需要逐个核对。官方提供了 codemod 工具可以自动化一部分迁移,但你必须先有测试覆盖——没有测试就升级 Web 框架是赌博。

如果要升级,建议路径:① 补齐关键接口的集成测试;② 读官方迁移指南列清单;③ 跑 codemod;④ 在预发环境压测对比。以官方最新迁移文档为准。

Q3:worker_threads 和 child_process 我该用哪个?

A:判断标准是"需不需要频繁传大量数据"和"崩溃容错要求有多高":

你的情况选择
CPU 密集计算(图像处理、加密、大 JSON 解析),输入输出数据大worker_threads(可用 ArrayBuffer 零拷贝转移,通信开销小)
需要跑不可信的第三方代码,怕它崩溃或泄漏child_process(进程隔离,崩了不影响主进程)
要调用外部程序(ffmpeg、git、ImageMagick)child_process(spawn)
想利用多核跑 HTTP 服务cluster 或 K8s 副本
只是 I/O 密集都不需要,用 Node 内置的异步 I/O

一条容易忽略的注意事项:worker_threads 不是用来解决"我的异步代码写得很乱"的——它只解决 CPU 占用。用它包装 I/O 操作反而更慢。

Q4:为什么我的服务内存一直涨,重启就好了?

A:几乎可以肯定是内存泄漏(见 11.3)。先确认是不是泄漏而非正常缓存:

# 观察 30 分钟内的 heapUsed 趋势(健康的服务应呈锯齿状,GC 后回落到基线)
node -e "setInterval(() => { const m = process.memoryUsage(); console.log(new Date().toISOString(), 'heapUsed(MB)', (m.heapUsed/1048576).toFixed(1), 'rss(MB)', (m.rss/1048576).toFixed(1)); }, 5000)"

如果 heapUsed 的谷底值(每次 GC 后的最低点)持续抬升,就是真泄漏。然后按 11.3 的三类来源排查:无上限的缓存、未移除的监听器、闭包持有大对象。

临时缓解可以设 --max-old-space-size 并配合 PM2 的 max_memory_restart 定期重启,但那只是把问题藏起来——泄漏速率会随流量增长,迟早撑不到重启周期。


相关笔记

  • JavaScript-04-异步编程 —— 事件循环的浏览器侧视角:Promise、async/await、微任务队列。先读它再读本文第三节会顺畅很多。
  • JavaScript-06-模块化与工程化 —— CommonJS 与 ESM 的语言层面细节,与本文第四节互补。
  • 后端-01-HTTP与RESTfulAPI设计 —— 本文示例里的状态码、Location 头、分页参数等约定都来自这篇。
  • 后端-07-Docker与容器化 —— 第九节的服务如何打包成镜像,以及容器场景下进程管理的取舍。
  • 后端-06-认证与授权 —— 替换第九节那个演示用的 API Key 鉴权。
  • 工具-07-调试技巧 —— 通用调试方法论,可与本文第十一节的 Node 专用工具配合。
  • 版本与官方资源速查 —— Node.js 各版本的官方文档入口与当前 LTS 状态。

参考来源

核实时间 2026-10-11。以下链接均已实测可访问:

  • Node.js v24(LTS)API 文档总入口:<https://nodejs.org/docs/latest-v24.x/api/>
  • Node.js 模块:ECMAScript modules(import.meta.dirname、require(esm) 互操作、扩展名强制要求):<https://nodejs.org/docs/latest-v24.x/api/esm.html>
  • Node.js Worker threads("use a pool of Workers"、对 CPU 密集型任务的定位):<https://nodejs.org/docs/latest-v24.x/api/worker_threads.html>
  • Express 路由指南(路由方法、路径、Router、path-to-regexp v8):<https://expressjs.com/en/guide/routing.html>
  • Express 中间件指南("a series of middleware function calls"、四类中间件):<https://expressjs.com/en/guide/using-middleware.html>
  • Express 错误处理(async 处理器自动 next(err)、四参数签名、Promise 链):<https://expressjs.com/en/guide/error-handling.html>
  • Express v5 迁移指南(破坏性变更清单、codemod 工具):<https://expressjs.com/en/guide/migrating-5.html>
  • Express 生产环境安全最佳实践(helmet 默认头部、X-Powered-By、会话 Cookie):<https://expressjs.com/en/advanced/best-practice-security.html>
  • MDN(中文)JavaScript 执行模型,用于对照浏览器侧事件循环:<https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Execution_model>

版本与依赖说明:

  • 本文以 Node.js v24(Krypton,LTS) 为基准;核实时 Node 文档版本号为 v24.21.0,Current 为 v26 系列。版本状态以官方最新文档为准:<https://nodejs.org/en/about/previous-releases>
  • Express 相关章节以 Express 5.x 为准(核实时 npm 最新为 5.3.0)。Express 5 要求 Node.js 18 或更高。
  • 示例中的依赖版本(express@^5.3.0、zod@^4.6.5、helmet@^8.3.0、pino@^10.4.0、pino-http@^11.0.0、cors@^2.8.6、dotenv@^18.0.7)为写作时 npm registry 上的最新版本,通过 npm view <包名> version 可核实当前值。
  • node:sqlite 需要 Node v22.5.0 以上,其稳定性级别与 API 细节以官方文档为准:<https://nodejs.org/docs/latest-v24.x/api/sqlite.html>
  • 文中引用的第三方工具(PM2、clinic.js、autocannon、piscina、lru-cache)的配置项会随版本变化,使用前请查阅各自官方文档。