后端-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 启动后,实际由两个完全不同的组件协作:
| 组件 | 语言 | 职责 | 谁在里面跑 |
|---|---|---|---|
| V8 | C++ | 解析/编译/执行 JavaScript、垃圾回收(GC)、JIT 优化 | 你的所有 JS 代码 |
| libuv | C | 事件循环(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/randomBytes | libuv 线程池 | 不会 |
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 层后强制 ≥4ms | 1ms |
| 定时器精度 | 受渲染帧影响 | 受事件循环各阶段耗时影响 |
实践含义
在 Node 里写"让出控制权"的代码,用
await new Promise(r => setImmediate(r));在浏览器里通常用setTimeout(r, 0)或requestAnimationFrame。同一个习惯不要跨环境照搬。
四、模块系统:CommonJS 与 ESM
4.1 两套系统的本质差异
| 对比项 | CommonJS (CJS) | ES Module (ESM) |
|---|---|---|
| 语法 | require() / module.exports | import / export |
| 加载时机 | 运行时、同步 | 解析时确定依赖图,异步加载 |
| 加载结果 | 值的拷贝(对原始类型) | 值的实时只读绑定(live binding) |
| 能否条件加载 | ✅ 可以写在 if 里 | ❌ 静态 import 不行,需 await import() |
顶层 await | ❌ | ✅ |
this 在模块顶层 | module.exports | undefined |
| 循环依赖行为 | 得到未完成的导出对象 | 得到 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 === module | import.meta.main(v24.2.0+) |
require.resolve('./x') | import.meta.resolve('./x.js') |
require('./x')(动态、条件) | await import('./x.js') |
加载 .json | import data from './d.json' with { type: 'json' } |
加载原生插件 .node | module.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 里importCJS)一直是支持的,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) 指的是:当写入端比读取端快时,系统向上游传递"慢一点"的信号,避免内存被撑爆。
四类流:
| 类型 | 例子 | 典型方法 |
|---|---|---|
| Readable | fs.createReadStream、HTTP 请求体 | read()、pipe()、on('data') |
| Writable | fs.createWriteStream、HTTP 响应 | write()、end()、drain 事件 |
| Duplex | TCP socket | 兼有读写 |
| Transform | zlib.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) 的函数,能做四件事:
- 执行任意代码;
- 修改
req/res对象; - 结束请求-响应周期(调用
res.send()/res.end()等); - 调用
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]) | 把请求体读成 Buffer | Webhook 签名验证 |
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 4 | Express 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 |
| 安全响应头 | helmet | app.use(helmet()) |
| CORS | cors | 用函数式 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 | ✅ journald | Linux 服务器、系统级托管 |
| 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 自身开销)。
十三、练习题
- (基础·事件循环顺序) 不运行代码,写出下面程序的输出顺序,然后运行验证。若输出与你预期不同,解释原因。
```js
setTimeout(() => console.log('A'), 0);
setImmediate(() => console.log('B'));
process.nextTick(() => console.log('C'));
Promise.resolve().then(() => console.log('D'));
console.log('E');
```
- (基础·模块系统) 把一个使用
__dirname、require、require.main === module的 CommonJS 文件改写成 ESM,用import.meta.dirname、import.meta.main和await import()替换。写出改后的完整代码,并说明package.json需要改什么。
- (进阶·中间件执行顺序) 下面的中间件链有什么问题?请指出会发生什么、以及如何修正。
```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);
```
- (进阶·阻塞事件循环) 你的服务有个
/report接口需要把 20 万行数据聚合成 CSV。当前实现用同步字符串拼接并在主线程完成,压测发现所有接口的 P99 从 30ms 涨到 8s。请给出至少两种改造方案,并用代码说明其中一种(提示:worker_threads与stream的区别在于——前者解决 CPU 占用,后者解决内存占用)。
- (进阶·优雅关闭) 为下面这个不完整的关闭逻辑找出所有缺陷,并写出正确版本:
```js
process.on('SIGTERM', () => {
pool.end().then(() => server.close());
process.exit(0);
});
```
- (思考题) 你的团队要把一个 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-regexpv8):<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)的配置项会随版本变化,使用前请查阅各自官方文档。